!wmitrace.setprefix

Article
10/25/2023

The !wmitrace.setprefix extension specifies the trace message prefix that is prepended to the trace messages from this session. This extension allows you to change the prefix during the debugging session.

!wmitrace.setprefix [+] PrefixVariables 
!wmitrace.setprefix

Parameters

+
Causes PrefixVariables to be appended to the trace message prefix. If the + token is not used, PrefixVariables replaces the existing trace message prefix.

PrefixVariables
A set of variables that specifies the format and data in the trace message prefix.

The variables have the format %n!x!, where %n represents a data field and !x! represents the data type. You can also include separation characters, such as colons (:), semicolons (;), parentheses ( ( ) ), braces ( { } ), and brackets ( [ ] ) to separate the fields.

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 the name of the directory in which the trace provider was built.
%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 the 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.
%!LEVEL!	string	Displays the value of the trace level that enables the trace message.
%!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 subcomponent name appears only if it is specified in the tracing code.

The symbol within exclamation marks is a conversion character that specifies the format and precision of the variable. For example, %8!04X! specifies the process ID formatted as a four-digit, unsigned, hexadecimal number.

DLL

Wmitrace.dll

This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory.

Example

The following command changes the trace message prefix in the debugger output to the following format:

!wmitrace.setprefix %2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

This extension command sets the trace message prefix to the following format:

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime:

As a result, the trace messages are prepended with the specified information in the specified format. The following code example is taken from a trace of the Tracedrv sample driver in the WDK.

tracedrv_c258: TracedrvDispatchDeviceControl: 0af4.0c64: 07/25/2003-13:55:39.998:  IOCTL = 1

Additional Information

For a conceptual overview of event tracing, see the Microsoft Windows SDK documentation. For information about trace message format files, see the "Trace Message Prefix" topic in the WDK documentation.

Remarks

When used with no parameters, !wmitrace.setprefix displays the current value of the trace message prefix.

The trace message prefix consists of data about the trace message that is prepended to each trace message during Windows software trace preprocessor (WPP) software tracing. This data originates in the trace log (.etl) file and the trace message format (.tmf) file. You can customize the format and data in trace message prefix.

The default trace message prefix is as follows:

[%9!d!]%8!04X!.%3!04X!::%4!s! [%1!s!]

and produces the following prefix:

[CPUNumber]ProcessID.ThreadID::SystemTime [ProviderDirectory]

You can change the format and data in the trace message prefix outside of the debugger by setting the %TRACE_FORMAT_PREFIX% environment variable. For an example that illustrates how to set the trace message prefix outside of the debugger, see "Example 7: Customizing the Trace Message Prefix" in the Windows Driver Kit (WDK) documentation. If the trace message prefix of your messages varies from the default, this environment variable might be set on your computer.

The prefix that you set by using this extension command affects only the debugger output. The trace message prefix that appears in the trace log is determined by the default value and the value of the %TRACE_FORMAT_PREFIX% environment variable.

This extension is only useful during WPP software tracing, and earlier (legacy) methods of Event Tracing for Windows. Trace events that are produced by other manifested providers do not use trace message format (TMF) files, and therefore this extension does not affect them.