Edit

Share via

How do I add a prefix and suffix to a trace message?

  • Article

You can use a WPP Preprocessor configuration block to add data to trace messages.

The WPP configuration block is defined by the begin_wpp config and end_wpp statements that you place in your source code.

//begin_wpp config

...

configuration block

...

//end_wpp

If you put configuration data in a header file, specify the name of the header file in your project properties (for WPP Tracing). Under File Options on the property page, specify the Scan Configuration file. See WPP Preprocessor for more information.

Configuration block syntax

//USEPREFIX (Function_Name, "Format string");
Defines a format string prefix to use when the event is logged. The first parameter is the name of the function to which this prefix applies. The second parameter is the format string to use. To use the default value, specify %!STDPREFIX!. The default trace message prefix specifies the CPU number, process ID, thread ID, time stamp in Coordinated Universal Time (UTC) format, and the control GUID friendly name.

//USEPREFIX (TRACE_RETURN, "%!STDPREFIX!");

//FUNC Function_Name{args}(EXP);
Defines the name and the signature of the trace function. The braces { } are used to define set values for the function. In the following example, the function takes one argument and no format string, and the LEVEL is set to ERROR.

//FUNC TRACE_RETURN{LEVEL=ERROR}(EXP);

//USESUFFIX (Function_Name, "Format string");
Defines the format string suffix to use when the event is logged. The first parameter is the name of the function to which this suffix applies. The second parameter is the format string to use. You can use variable names in your code.

//USESUFFIX (TRACE_RETURN, "Function Return=%!HRESULT!",EXP);

Example configuration block

The following example defines a trace macro that uses the format string prefix and suffix. If you are defining a tracing macro, you must also define macros to select the logger and to check whether the event should be logged.

//MACRO: TRACE_RETURN
//
//begin_wpp config
//USEPREFIX (TRACE_RETURN, "%!STDPREFIX!");
//FUNC TRACE_RETURN{LEVEL=ERROR}(EXP);
//USESUFFIX (TRACE_RETURN, "Function Return=%!HRESULT!",EXP);
//end_wpp

//
// The next two macros are for checking if the event should be logged, and for
// choosing the logger handle to use when calling the ETW trace API
//
#define WPP_LEVEL_EXP_ENABLED(LEVEL, HR) WPP_FLAG_ENABLED(LEVEL)
#define WPP_LEVEL_EXP_LOGGER(LEVEL, HR) WPP_FLAG_LOGGER(LEVEL)

Example trace results

[0]0F78.0460::06/24/2006-15:54:54.880 [tracedrv]Function Return=0x8000000f(STATUS_DEVICE_POWERED_OFF)