WinHttpTraceCfg.exe, a Trace Configuration Tool
The Microsoft Windows HTTP Services (WinHTTP) trace configuration tool, WinHttpTraceCfg.exe, is used to configure trace capabilities for debugging and packet-sniffing purposes. The ability to monitor WinHTTP functions and their corresponding network traffic is important. Debugging applications that utilize encrypted wire protocols, such as Secure Sockets Layer (SSL), preclude sniffing packets at the network transport layer and require the ability to intercept traffic between the client and server after it has been decrypted. Microsoft Windows HTTP Services (WinHTTP) provides a trace facility that has a range of capabilities for intercepting the traffic stream between the client and server.
This trace facility can be a valuable tool for debugging. It can be used, for example, to view parameters passed to various function calls, as well as to view actual data sent and received by a WinHTTP application.
Using the Trace Facility
WinHTTP obtains tracing control parameters from the registry. These control parameters affect how WinHTTP produces trace output, and how that output is formatted. All applications that use WinHTTP share the same settings.
A trace facility configuration tool, WinHttpTraceCfg.exe, is available as a download on the Windows Server 2003 Resource Kit Tools website. The configuration tool sets or retrieves the trace facility registry settings based on the specified command line parameters.
WinHttpTraceCfg [-e <0|1>] [-l [log-file]] [-d <0|1>] [-s <0|1|2>] [-t <0|1>] [-?] [-m <file size>]
The following table lists possible parameters for the configuration tool.
|-?||Displays syntax data.
|-e||Specifies whether the trace facility is enabled or disabled.
Specifies a prefix for the log file. The prefix can include a path. The log file is written to the current directory or the directory specified in the prefix and has the following format.
If a prefix is not specified, an empty string is used. Specify "*" to delete an existing prefix.
Specifies whether the trace output is displayed in a debugger or written to a file.
Specifies how network traffic (requests and responses) is displayed.
Specifies whether top-level function calls are recorded in the trace.
Specifies the maximum size, in bytes, of a log file generated by the tracing facility. If this option is specified without a size, the minimum value is 65,535 bytes. If a log file reaches the maximum size, the contents of the file are erased. Trace data continues to be written to the log file.
Running the trace facility configuration tool and specifying no parameters retrieves and displays the current registry settings.
Log files grow rapidly and degrade application performance. Ensure that the required hard disk drive space is available before enabling the trace facility.
Interpreting Trace Data
The trace facility data stream reflects WinHTTP functions called in the application and any HTTP data sent or received. In some cases, functions called internally by WinHTTP are also shown.
The following image shows a portion of a log file generated by the trace facility. Several items are highlighted and labeled.
Each line of trace output contains information in three columns. The first column shows the date and time when the entry was recorded. The second column shows a request identifier (ID) that can be used to differentiate between multiple requests. If the log entry does not correspond to a specific request, "*Session*" is displayed in this column. It can be useful to sort the log file based on this ID to see only events that occur for a single request. The following example shows a command you can use to sort the log file.
findstr 00000001 LogFile.log
The third column shows a function call, HTTP traffic, or a status message included to help interpret the trace.
When a log entry corresponds to a function call, the parameters of the function are also recorded. Memory addresses are displayed in hexadecimal while all other values are displayed as an ASCII string. The trace facility also records the return time and value for each function.
The format of HTTP data depends on the registry settings specified with the trace facility configuration tool. When HTTP data is encrypted, the decrypted data is also shown in the trace output.