Tracefmt Commands

To use Tracefmt, type the commands in a Command Prompt window. The following syntax displays the elements of a Tracefmt command.

To display the trace messages in readable form, Tracefmt must apply the formatting instructions in a trace message format file to the trace messages. The syntax that you use depends on whether you have a TMF file for the trace provider, or whether you want Tracefmt to create a TMF file.

To provide a TMF file or a path to a directory of TMF files:

    tracefmt [EtlFile | -rt SessionName][-tmf TMFFile | -p TMFPath ] [Options]

To create a TMF file:

    tracefmt [EtlFile | -rt SessionName]-i ImageFiles [-r SymbolPath ] [-p TmfPath ] [Options]

To display the syntax at the command line.

    tracefmt -h | /?

Parameters

EtlFile
Specifies the event trace log (.etl) file that contains the trace messages. Enter the path (optional) and file name. The default is c:\logfile.etl.

-rt SessionName
Real time. Formats trace messages from the specified real-time trace sessions, instead of from a trace log.

SessionName is the name of the trace session. The default is NT Kernel Logger.

-tmf TMFFile
Specifies the path (optional) and file name of a trace message format (.tmf) file for the trace messages. The default value is Default.tmf, a file included in the WDK.

-i ImageFiles
Directs Tracefmt to find the PDB symbol files for the specified image files and to create a TMF file from the formatting instructions in the PDB files.

ImageFiles represents the path and file names of one or more binary files (.exe, .dll, or .sys) for trace providers. Use a semicolon (;) to separate image file names.

-r SymbolPaths
Specifies the location of the private PDB symbol files for the image files specified in -i.

SymbolPaths represents one or more paths to directories that store private symbols or symbol server paths. Use a semicolon (;) to separate path names. The path names in SymbolPaths can include wildcard characters, such as an asterisk (*) to represent multiple characters and a question mark (?) to represent a single character.

If you include -i in a command, but omit -r, Tracepdb searches for the PDB files for the specified images in the paths specified by the %_NT_SYMBOL_PATH% environment variable. If the environment variable is not set, Tracepdb searches in the default symbol path, srv*\\\\symbols\\symbols.

-p TMFPath
Specifies the path to the directory that stores TMF files.

When -p is used without -i, Tracefmt searches in the path specified by -p for an existing TMF file. If -p is omitted Tracefmt looks for the TMF file in the value of the %TRACE_FORMAT_SEARCH_PATH% environment variable, if it is set. Otherwise, Tracefmt tries to apply the formatting instructions in the Default.tmf file.

When -p is used with -i, Tracefmt places the TMF file that it creates in the directory specified by -p. If -p is omitted, Tracefmt places the TMF file in the directory specified by the value of the %TRACE_FORMAT_SEARCH_PATH% environment variable, if it is set. Otherwise, Tracefmt places the file in the local directory.

-h | /?
Displays help.

-o OutputFile
Specifies alternate names for the Tracefmt output file and the Tracefmt summary message file. The default values are FmfFile.txt (for the output file) and FmtSum.txt.sum (for the summary file) in the local directory.

OutputFile is a path and file name with a .txt file name extension, such as c:\traces\trace.txt.

If you use this parameter with the -displayonly or -summaryonly options, it affects only the summary message file.

-csv
Formats the Tracefmt output file as a comma-separated, variable length (.csv) file. This format adds a detailed, structured prefix to each message, in addition to the standard trace message prefix.

This option affects the output file and the display of trace messages in the Command Prompt window, if any.

-csvheader
Adds a row of descriptive column headings to the CSV file. This header is especially useful for interpreting the structured prefix that Tracefmt adds to CSV files. By default, Tracefmt CSV files do not have column headings.

-csvquote
Doubles all quotations marks (") in the CSV file. This feature is designed for applications that display quotation marks only when they are enclosed in quotation marks.

-display
Displays the trace messages in the Command Prompt window, in addition to writing them to the output file.

-displayonly
Displays the trace messages only in the Command Prompt window, and does not create an output file.

-nosummary
Does not create a summary message file.

-summaryonly
Creates only a summary message file. Tracefmt does not create an output file.

-noprefix
Omits the trace message prefix. This option affects trace messages in the output file and the Tracefmt display.

-hires
High resolution. Displays the number of microseconds and nanoseconds in the trace message time stamp. By default, only milliseconds are displayed.

Use this option when a performance counter clock value is used for the trace message time stamp, instead of the system timer, such as when the Tracelog -UsePerfCounter parameter is used. For information about Tracelog commands, see Tracelog Command Syntax.

-seq
Displays the local or global sequence numbers in the trace message prefix. If sequence numbers were not recorded in the message, the field is uninitialized, or filled with zeros or "f"s.

-ods
Sends the formatted trace messages to the debugger for display.

-gmt
Displays the time stamp on each trace message in Greenwich Mean Time (GMT).

This option affects only the Tracefmt output file. It does not convert the time stamps in the event trace log (.etl) file. The time zone of the trace log is displayed when you submit a Tracefmt command.

-utc
Displays the time stamp on each trace message in Coordinated Universal Time (UTC). UTC is almost identical to GMT, but it represents midnight as zero.

This option affects only the Tracefmt output file. It does not convert the time stamps in the event trace log (.etl) file. The time zone of the trace log file is displayed when you submit a Tracefmt command.

-trace
Displays Tracefmt actions as they occur. This information is useful when the formatting is incorrect or when Tracefmt reports an error or exception.

The trace display can be extensive. Consider redirecting the Tracefmt output to a text file for later examination.

-v
Verbose. Displays detailed information in the Command Prompt window as Tracefmt processes each block or buffer of trace messages. Use this option when you suspect file damage or inconsistencies.

Comments

Finding the TMF file

If you omit the -i parameter, Tracefmt use the following methods to find the TMF file. The methods are listed in order that Tracefmt uses them.

• The -tmf parameter.

• The -p parameter.

• The %TRACE_FORMAT_SEARCH_PATH% environment variable.

• Default.tmf, a file included in the WDK.

If Tracefmt cannot find a TMF file, or the TMF file does not include formatting information for the trace messages, Tracefmt cannot display the messages. Instead, it writes the following error message in place of the trace message

No Format Information found.

Exception Raised

If Tracefmt cannot format a trace message parameter, it raises an exception and displays a message such as:

*****FormatMessage Header(Header) of EventTrace, parameter 23 raised an exception*****

If you see a similar exception, review the message definition in the source code, with special attention to any user-specified variable types. For more information, see DoTraceMessage.

TMF files with non-GUID file names

If the TMF file name is not a message GUID, you must use the -tmf parameter to identify the file and enter the fully qualified path to the file.

Formatting NT Kernel Logger trace messages

To format messages from the NT Kernel Logger trace session or a Global Logger trace session, use the -tmf parameter to specify the system.tmf file, a trace message format file included in the WDK..

Formatting trace messages from real-time trace sessions

When you use the -rt (real-time) parameter, Tracefmt displays a message confirming that it is in real-time mode, and then waits for trace messages from the specified trace provider. It does not return to the command prompt until the trace session stops.

Formatting QPC time stamps

Tracefmt does not format the values of the system performance counter clock (QueryPerformanceCounter) correctly. If you are using this high resolution time, use Tracerpt, a tool included in Windows, to format the trace messages. For more information, see the description of the -UsePerfCounter parameter in Tracelog Command Syntax.

Out-of-sequence trace messages

If you view a trace message file on a computer running Windows XP, the display might show trace messages that are out of sequence. To correct this problem, you can use the sequence number option when you start the trace session and view the trace using Tracefmt. You can then view the trace with Traceview and sort according to sequence number. You can also view the trace on a computer running Windows Server 2003 or later versions of Windows.