WPP Software Tracing
This section describes how to use the Windows software trace preprocessor (WPP) to trace the operation of a software component (trace provider). A trace provider can be one of the following:
A kernel-mode driver.
A user-mode driver, application, or dynamic-link library (DLL).
WPP software tracing supplements and enhances WMI event tracing by adding ways to simplify tracing the operation of the trace provider. It is an efficient mechanism for the trace provider to log real-time binary messages. The logged messages can subsequently be converted to a human-readable trace of the operation of the trace provider.
| When should you use WPP software tracing? |
|---|
WPP software tracing is primarily intended for debugging code during development. If you want to publish events that can be consumed by applications interested in structured ETW events, in addition to tracing during development, use the following:
|
Logging messages with WPP software tracing is similar to using Windows event logging services. The driver logs a message ID and unformatted binary data in a log file. Subsequently, a postprocessor converts the information in the log file to a human-readable form. However, WPP software tracing supports message formats that are more capable and flexible than that supported by the event logging services. For example, WPP software tracing has built-in support for IP addresses, GUIDs, system IDs, time stamps, and other useful data types. In addition, users can add custom data types relevant to their application.
An overview of the WPP software tracing process
The basic process for adding WPP software tracing to a driver or application, includes the following steps. If you use one of the Visual Studio templates provided in the WDK for creating a WDF driver, much of the work is done for you.
Define a control GUID that uniquely identifies the driver or application as a trace provider. The provider specifies this GUID in its definition of the WPP_CONTROL_GUIDS macro and in a related control file used by Tracelog or another Trace Controller.
Add the required WPP-related C preprocessor directives and WPP macro calls to the provider's source files, as described in Adding WPP Software Tracing to a Windows Driver and in WPP Software Tracing Reference.
Modify the Visual Studio project to run the WPP preprocessor and build the driver, as described in Step 6 of Adding WPP Software Tracing to a Windows Driver. You can refer to the WPP Preprocessor for more build time options.
Install the driver or component. Start a trace session and record the trace messages. Use the tools for software tracing, such as TraceView, Tracelog, Tracefmt, and Tracepdb to configure, start, and stop tracing sessions and to display and filter trace messages. These tools are included in the Windows Driver Kit (WDK).
In this section
- Adding WPP Software Tracing to a Windows Driver
- Inflight Trace Recorder for logging traces
- Using WPP Software Tracing in a Trace Provider
- Adding WPP Macros to a Trace Provider
- WPP Preprocessor
- Tracing and Diagnosability for WDF Drivers
Note Event Tracing for Windows (ETW) and WPP support most types of kernel-mode and user-mode drivers. However, ETW and WPP use types that are not available for certain types of drivers, such as miniport drivers. To determine whether a particular driver type is supported, add basic WPP macros to the driver, such as WPP_INIT_TRACING and WPP_CLEANUP. If the code does not compile because the types that are used are not defined, ETW and WPP cannot support the driver type.
For more information about ETW, see Event Tracing for Windows.
Note WPP trace providers can only be enabled by one trace session at a time. See WPP Providers for more information.
For information about the WMI library support routines that support WPP software tracing, see: