Windows Driver Kit: Driver Development Tools
Trace Message Prefix
Tracefmt adds a prefix to each trace message that consists of data stored in the event trace log (.etl) file and the trace message format (.tmf) file.
Tracefmt includes particular data elements by default, but users can add and remove elements by changing the %TRACE_FORMAT_PREFIX% environment variable, a string that specifies a message definition compatible with FormatMessage.
The format of the default trace message prefix is as follows:
[%9!d!]%8!04X!.%3!04X!::%4!s! [%1!s!]
which produces the following prefix:
[CPUNumber]ProcessID.ThreadID :: SystemTime [MessageGUIDFriendlyName]
Each %n variable represents a parameter that is described in the following table.
| Prefix variable identifier | Variable type | Description |
|---|
| %1 | string | The friendly name of the message GUID of the trace message. By default, the friendly name of a message GUID is name of the directory in which the trace provider was built.
To change the friendly name of the message GUID, use the -p parameter with Tracewpp or with the RUN_WPP macro. For more information, see Run_WPP Options.
|
| %2 | string | Source file and line number.
This variable represents the friendly name of the trace message. By default, the friendly name of a trace message is name of the source file and the line number of the code that generated the trace message.
|
| %3 | ULONG | Thread ID.
Identifies the thread that generated the trace message.
|
| %4 | string | Time stamp of the time that the trace message was generated. |
| %5 | string | Kernel time.
Displays the elapsed execution time for kernel-mode instruction, in CPU ticks, at the time that the trace message was generated.
|
| %6 | string | User time.
Displays the elapsed execution time for user-mode instruction, in CPU ticks, at the time that the trace message was generated.
|
| %7 | LONG | Sequence number.
Displays the local or global sequence number of the trace message. Local sequence numbers, which are unique only to this trace session, are the default.
|
| %8 | ULONG | Process ID.
Identifies the process that generated the trace message.
|
| %9 | ULONG | CPU number.
Identifies the CPU on which the trace message was generated.
|
| %!FUNC! | string | Function name.
Displays the name of the function that generated the trace message.
|
| %!FLAGS% | string | Displays the name of the trace flags that enable the trace message.
(Because DoTraceMessage reverses the flags and level arguments, messages generated by DoTraceMessage display the value of the trace level in this field.)
|
| %!LEVEL! | string | Displays the value of the trace level that enables the trace message.
(Because DoTraceMessage reverses the flags and level arguments, messages generated by DoTraceMessage display the name of the trace flags in this field.)
|
| %!COMPNAME! | string | Component name.
Displays the name of the component of the provider that generated the trace message. The component name appears only if it is specified in the tracing code.
|
| %!SUBCOMP! | string | Subcomponent name.
Displays the name of the subcomponent of the provider that generated the trace message. The component name appears only if it is specified in the tracing code.
|
The symbol within exclamation marks is a conversion character that specifies the formatting and precision of the variable. For example, %8!04X! specifies the process ID represented as a four-digit, unsigned hexadecimal number. These conversion characters must be included.
To change the elements, order, or formatting of the trace message prefix, use the %TRACE_FORMAT_PREFIX% environment variable. For an example, see Example 7: Customizing the Trace Message Prefix.
For an example of content in a TMF file, see Formatting Trace Messages from the tracedrv Sample.
Also, the -csv parameter adds an unconfigurable, detailed prefix to each trace message before the standard Tracefmt prefix. For a description of the fields in the CSV prefix, use the -csvheader parameter.