!wmitrace.setprefix

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.

Syntax

!wmitrace.setprefix PrefixVariables

Parameters

PrefixVariables

A set of variables that specify 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 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 formatting and precision of the variable. For example, %8!04X! specifies the process ID represented as a four-digit, unsigned, hexadecimal number.

DLL

Comments

The trace message prefix consists of data about the trace message that is prepended to each trace message. This data originates in the trace log (.etl) file and the trace message format (.tmf) file. You can customize the format and the 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 of setting 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.

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.