Error Logging in HTTP API

INFO: Error Logging in HTTP API

Article ID	:	820729
Last Review	:	October 9, 2003
Revision	:	1.0

SUMMARY

This article describes the error logging capabilities of Hypertext Transfer Protocol (HTTP) APIs.

Some errors that occur in an HTTP-based application are automatically handled by the HTTP API instead of being passed back to an application for handling. This behavior occurs because the frequency of such errors might otherwise flood an event log or an application handler.

The following topics describe the different aspects of HTTP API error logging:

•	Configure HTTP API Error Logging Registry settings control the HTTP API logs errors, the maximum permitted size of log files, and the location of the log files.
•	Format of the HTTP API Error Logs The HTTP API creates log files that comply with the World Wide Web Consortium (W3C) log file conventions. You can use standard tools to parse these log files. However, unlike W3C log files, HTTP API log files do not contain the columns names.
•	Types of Errors That the HTTP API Logs The HTTP API logs a variety of common errors.

MORE INFORMATION

Configure HTTP API Error Logging

Three registry values under an HTTP /Parameters key control the HTTP API error logging. These keys are located at the following registry key:

HKEY_LOCAL_MACHINE/System/CurrentControlSet/Services/HTTP/Parameters

Note The location and the form of the configuration values may change in later versions of the Microsoft Windows operating system.

You must have Administrator/Local System credentials to change the registry values, and to view or modify the log files and the folder that contains them.

Configuration information in the registry values is read when the HTTP API driver starts. Therefore, if you change the settings, you must stop, and then restart the driver to read the new values. To do this, type the following console commands:

net stop http

net start http

The following naming convention is used to name the log files:

httperr + sequence number + .log
Example: httperr4.log

Log files are cycled when they reach the maximum size that the ErrorLogFileTruncateSize registry value specifies. This value cannot be less than one megabyte (MB).

If the configuration of error logging is not valid, or if any type of failure occurs while the HTTP API is writing to the log files, the HTTP API uses event logging to notify administrators that error logging is not occurring.

The following table describes the registry configuration values:

Registry Value	Description
EnableErrorLogging	A DWORD that you can set to TRUE to enable error logging or to FALSE to disable it. The default value is TRUE.
ErrorLogFileTruncateSize	A DWORD that specifies the maximum size of an error log file, in bytes. The default value is one MB (0x100000). Note The specified value cannot be smaller than the default value.
ErrorLoggingDir	A String that specifies the folder where the HTTP API puts its logging files. The HTTP API creates a subfolder HTTPERR in the specified folder, and then stores the log files in the subfolder. This subfolder and the log files receive the same permission settings. The Administrator and Local System Accounts have full access. Other users do not have access. The following is the default folder when the folder is not specified in the registry: %SystemRoot%/System32/LogFiles Note The ErrorLoggingDir string value must be a fully qualified path. However, it can contain %SystemRoot%.

back to the top

Format of the HTTP API Error Logs

Generally, HTTP API error log files have the same format as W3C error logs, except that HTTP API error log files do not contain column headings. Each line of an HTTP API error log records one error. The fields appear in a specific order. A single space character (0x0020) separates each field from the previous field. In each field, plus signs (0x002B) replace space characters, tabs, and nonprintable control characters.

The following table identifies the fields and the order of the fields in an error log record:

Field	Description
Date	The Date field follows the W3C format. This field is based on Coordinated Universal Time (UTC). The Date field is always ten characters in the form of YYYY-MM-DD. For example, May 1, 2003 is expressed as 2003-05-01.
Time	The Time field follows the W3C format. This field is based on UTC. The time field is always eight characters in the form of MM:HH:SS. For example, 5:30 PM (UTC) is expressed as 17:30:00.
Client IP Address	The IP address of the affected client. The value in this field can be either an IPv4 address or an IPv6 address. If the client IP address is an IPv6 address, the ScopeId field is also included in the address.
Client Port	The port number for the affected client.
Server IP Address	The IP address of the affected server. The value in this field can be either an IPv4 address or an IPv6 address. If the server IP address is an IPv6 address, the ScopeId field is also included in the address.
Server Port	The port number of the affected server.
Protocol Version	The version of the protocol that is being used. If the connection has not been parsed sufficiently to determine the protocol version, a hyphen (0x002D) is used as a placeholder for the empty field. If either the major version number or the minor version number that is parsed is greater than or equal to 10, the version is logged as HTTP/?.?.
Verb	The verb state that the last request that is parsed passes. Unknown verbs are included, but any verb that is more than 255 bytes is truncated to this length. If a verb is not available, a hyphen (0x002D) is used as a placeholder for the empty field.
CookedURL + Query	The URL and any query that is associated with it are logged as one field that is separated by a question mark (0x3F). This field is truncated at its length limit of 4096 bytes. If this URL has been parsed ("cooked"), it is logged with local code page conversion, and is treated as a Unicode field. If this URL has not been parsed ("cooked") at the time of logging, it is copied exactly, without any Unicode conversion. If the HTTP API cannot parse this URL, a hyphen (0x002D) is used as a placeholder for the empty field.
Protocol Status	The protocol status cannot be greater than 999. If the protocol status of the response to a request is available, it is logged in this field. If the protocol status is not available, a hyphen (0x002D) is used as a placeholder for the empty field.
SiteId	Not used in this version of the HTTP API. A placeholder hyphen (0x002D) always appears in this field.
Reason Phrase	This field contains a string that identifies the type of error that is being logged. This field is never left empty.
Queue Name	This the request queue name.

The following sample lines are from an HTTP API error log:

2002-07-05 18:45:09 172.31.77.6 2094 172.31.77.6 80 HTTP/1.1 GET /qos/1kbfile.txt 503 – ConnLimit 2002-07-05 19:51:59 127.0.0.1 2780 127.0.0.1 80 HTTP/1.1 GET /ThisIsMyUrl.htm 400 – Hostname 2002-07-05 19:53:00 127.0.0.1 2894 127.0.0.1 80 HTTP/2.0 GET / 505 - Version_N/S 2002-07-05 20:06:01 172.31.77.6 64388 127.0.0.1 80 - - - - - Timer_MinBytesPerSecond

back to the top

Types of Errors That the HTTP API Logs

The HTTP API logs error responses to clients, connection time-outs, orphaned requests, and dropped connections that are handled incorrectly.

The following list identifies the types of errors that the HTTP API logs:

•	Responses to clients The HTTP API sends an error response to a client, for example, a 400 error that is caused by a parse error in the last received request. After the HTTP API sends the error response, it terminates the connection.
•	Connection time-outs The HTTP API times out a connection. If a request is pending when the connection times out, the request is used to provide more information about the connection in the error log.
•	Orphaned requests A user-mode process quits unexpectedly while there are still queued requests that are routed to that process. The HTTP API logs the orphaned requests in the error log.

Specific error types are designated by Reason Phrase strings that always appear as the last field of each error line. The following table identifies the HTTP API Reason Phrases:

Reason Phrase	Description
AppOffline	A service unavailable error occurred (an HTTP error 503). The service is not available because application errors caused the application to be taken offline.
AppPoolTimer	A service unavailable error occurred (an HTTP error 503). The service is not available because the application pool process is too busy to handle the request.
AppShutdown	A service unavailable error occurred (an HTTP error 503). The service is not available because the application shut down automatically in response to administrator policy.
BadRequest	A parse error occurred while processing a request.
Connection_Abandoned_By_AppPool	A worker process from the application pool that quit unexpectedly or orphaned a pending request by closing its handle.
Connection_Dropped	Reserved. Not currently used.
ConnLimit	A service unavailable error occurred (an HTTP error 503). The service is not available because the site level connection limit has been reached or exceeded.
Disabled	A service unavailable error occurred (an HTTP error 503). The service is not available because an administrator has taken the application offline.
EntityTooLarge	An entity exceeded the maximum size that is permitted.
FieldLength	A field length limit was exceeded.
Forbidden	A forbidden element or sequence was encountered while parsing.
Header	A parse error occurred in a header.
Hostname	A parse error occurred while processing a Hostname.
Internal	An internal server error occurred (an HTTP error 500).
Invalid_CR/LF	An illegal carriage return or line feed occurred.
LengthRequired	A required length value was missing.
N/A	A service unavailable error occurred (an HTTP error 503). The service is not available because an internal error (such as a memory allocation failure) occurred.
N/I	A not-implemented error occurred (an HTTP error 501), or a service unavailable error occurred (an HTTP error 503) because of an unknown transfer encoding.
Number	A parse error occurred while processing a number.
Precondition	A required precondition was missing.
QueueFull	A service unavailable error occurred (an HTTP error 503). The service is not available because the application request queue is full.
RequestLength	A request length limit was exceeded.
Timer_AppPool	The connection expired because a request waited too long in an application pool queue for a server application to dequeue and process it. This timeout duration is ConnectionTimeout. By default, this value is set to two minutes.
Timer_ConnectionIdle	The connection expired and remains idle. The default ConnectionTimeout duration is two minutes.
Timer_EntityBody	The connection expired before the request entity body arrived. When it is clear that a request has an entity body, the HTTP API turns on the Timer_EntityBody timer. Initially, the limit of this timer is set to the ConnectionTimeout value (typically 2 minutes). Each time another data indication is received on this request, the HTTP API resets the timer to give the connection two more minutes (or whatever is specified in ConnectionTimeout).
Timer_HeaderWait	The connection expired because the header parsing for a request took more time than the default limit of two minutes.
Timer_MinBytesPerSecond	The connection expired because the client was not receiving a response at a reasonable speed. The response send rate was slower than the default of 150 bytes/sec.
Timer_Response	Reserved. Not currently used.
URL	A parse error occurred while processing a URL.
URL_Length	A URL exceeded the maximum permitted size.
Verb	A parse error occurred while processing a verb.
Version_N/S	A version-not-supported error occurred (an HTTP error 505).

back to the top

---

APPLIES TO

•	Microsoft Windows Server 2003, Datacenter Edition
•	Microsoft Windows Server 2003, Enterprise Edition
•	Microsoft Windows Server 2003, Standard Edition
•	Microsoft Windows Server 2003, Web Edition
•	Microsoft Windows Small Business Server 2003 Premium Edition
•	Microsoft Windows Small Business Server 2003 Standard Edition

Top of Page

Keywords:

kberrmsg kbinfo kbhttp kbapi kbhttphandlers KB820729