TraceView Control Commands
Note
The TraceView command line options are deprecated. Use tracepdb.exe and tracefmt.exe to parse PDBs into TMF files and parse .etl files into text, respectively.content
Use a Traceview control command to manage trace sessions, including starting and stopping the session, enabling and disabling providers, updating the properties of the trace session, and flushing trace buffers.
traceview {-start | -stop | -update | -enable | -disable | -flush | -q} SessionName [Parameters]
traceview {-enumguid | -l | -h | -x}
Command Parameters
Actions
| Action | Description |
|---|---|
| -start | Starts the specified trace session. |
| -stop | Stops the specified trace session. |
| -update | Updates the properties for the specified trace session. |
| -enable | Enables providers for the specified trace session. |
| -disable | Disables providers for the specified session. |
| -flush | Flushes the active buffers of the specified trace session. This forced flush is in addition to the automatic flushes that occur when a buffer is full and when the trace session stops. |
| -q | Query the status of the specified trace session. |
| -enumguid | Lists providers on the system that are registered with Event Tracing for Windows (ETW). |
| -l | List all trace sessions running on the computer. |
| -x | Stops all trace sessions. |
Parameters
SessionName
When used with -start, SessionName is a name that you select to represent the trace session. With all other commands, SessionName identifies the trace session.
-f [LogFile]
When used with -start, -f starts a trace log sessions. LogFile specifies the path (optional) and file name of the event trace log (.etl) file. The default is C:\LogFile.etl.
When used with -update, -f sends all new trace messages only to the specified trace log. Use this parameter to convert a real-time trace session to a trace log session or to start a new trace log for an existing trace log session. To send trace messages to a real-time trace consumer and to a trace log, use both the -rt and -f parameters in the -update command.
-rt
When used with -start, -rt starts a real-time trace sessions (A trace log session (-f) is the default.) If you use -rt and -f in a -start command, the trace messages are sent to the trace consumer and to an event trace log file.
When used with -update, -rt adds real-time message delivery to a trace log session. All new trace messages are sent directly to the trace consumer (as in a real-time trace session), in addition to a trace log.
-guid {#GUID | GUIDFile}
Specifies one or more trace providers. Use with -start to enable providers for a trace session. Use with -enable to enable the providers or to change their -flag or -level values. Use with -disable to specify the providers to disable.
GUID can specify either one control GUID (preceded by a number sign (#)) or the path (optional) and file name of a text file, such as a control GUID (.ctl) file, that contains the control GUIDs of one or more trace providers.
If you omit the -guid parameter from a -start command, TraceView starts an NT Kernel Logger trace session.
TraceView passes the values of the following subparameters to the specified providers.
| Parameter | Description |
|---|---|
| SessionName | When used with -start, SessionName is a name that you select to represent the trace session. With all other commands, SessionName identifies the trace session. |
| -f \[LogFile\] | When used with -start, -f starts a trace log sessions. LogFile specifies the path (optional) and file name of the event trace log (.etl) file. The default is C:\\LogFile.etl. When used with -update, -f sends all new trace messages only to the specified [trace log](trace-log.md). Use this parameter to convert a real-time trace session to a trace log session or to start a new trace log for an existing trace log session. To send trace messages to a real-time trace consumer and to a trace log, use both the -rt and -f parameters in the -update command. |
| -rt | When used with -start, -rt starts a real-time trace sessions (A trace log session (-f) is the default.) If you use -rt and -f in a -start command, the trace messages are sent to the trace consumer and to an event trace log file. When used with -update, -rt adds real-time message delivery to a trace log session. All new trace messages are sent directly to the trace consumer (as in a real-time trace session), in addition to a [trace log](trace-log.md). |
| -guid {\#GUID | GUIDFile} | Specifies one or more trace providers. Use with -start to enable providers for a trace session. Use with -enable to enable the providers or to change their -flag or -level values. Use with -disable to specify the providers to disable. GUID can specify either one [control GUID](control-guid.md) (preceded by a number sign (\#)) or the path (optional) and file name of a text file, such as a control GUID (.ctl) file, that contains the control GUIDs of one or more trace providers. If you omit the -guid parameter from a -start command, TraceView starts an [NT Kernel Logger trace session](nt-kernel-logger-trace-session.md). |
TraceView passes the values of the following subparameters to the specified provider:
| Subparameters of -guid | Description |
|---|---|
-flag Flag |
|
|
-level Level |
Specifies the trace level for the providers in the trace session. The level determines which events the trace provider generates. Level represents a level value in decimal or hexadecimal format. The default value is 0. The meaning of the level value is defined independently by each trace provider. Typically, the trace level represents the severity of the event (information, warning, or error). In a -start command, the level value applies to all trace providers in the trace session. To set different levels for each trace provider, use a separate -enable command for each trace provider. |
| -b BufferSize | Specifies the size, in KB, of each buffer allocated for the trace session. Use only with -start.
The default value is determined by the number of processors, the amount of physical memory, and the operating system in use. |
| -min NumberOfBuffers | Specifies the number of buffers initially allocated for storing trace messages. Use only with -start.
The default value is determined by the number of processors, the amount of physical memory, and the operating system in use. |
| -max NumberOfBuffers | When used with -start, -max specifies the maximum number of buffers allocated for the trace session. The default value is determined by the number of processors, the amount of physical memory, and the operating system in use.
When used with -update, -max changes the maximum number of buffers allocated for the trace session. |
| -ft FlushTime | When used with -start, -ft specifies how often, in seconds, the trace message buffers are flushed. When used with -update, -ft changes the flush time to the specified time.
The minimum flush time is 1 second. The default value is 0 (no forced flush). This forced flush is in addition to the flushes that happen automatically whenever a trace message buffer is full and when a trace session stops. See also: -flush. |
| -age AgeLimit | When used with -start, -age specifies how long (in minutes) unused trace buffers are kept before they are freed. When used with -update, -age changes the age limit to the specified value.
Age Limit specifies how long (in minutes) unused trace buffers are kept before they are freed. The default is 15 minutes. This parameter is valid only in Windows 2000. |
| -paged | Uses pageable memory for the trace message buffers. By default, event tracing uses nonpageable memory for buffers. Use only with -start.
Do not use this parameter when the provider is a driver that might generate trace messages at an IRQL greater than DISPATCH\_LEVEL. This parameter is not supported in Windows 2000. |
| -seq MaxFileSize | Specifies sequential logging (at end-of-file, stop recording events) to the event trace log (.etl) file. Use only with -start.
MaxFileSize specifies the maximum size of the file in MB. Without a MaxFileSize value, this parameter is ignored. Sequential logging is the default, but you can use this parameter to set the maximum file size or to use -prealloc. Without this parameter, there is no file size limit. |
| -cir MaxFileSize | Specifies circular logging (at end-of-file, record new messages over the oldest messages) in the event trace log (.etl) file. Use only with -start.
MaxFileSize specifies the maximum size of the file in MB. Without a MaxFileSize value, this parameter is ignored. The default is sequential logging with no file size limit. |
| -prealloc | Reserves space for the event trace log (.etl) file before allocating it. Use only with -start.
This parameter requires -seq or -cir with MaxFileSize. It is not valid with -newfile. The system creates the event trace log (.etl) file with a size equal to the MaxFileSize value specified by using the -seq or -cir parameters. When you stop the session, it reduces the log file to the size of its contents. |
| -newfile MaxFileSize | Creates a new event trace log (.etl) file whenever the existing file reaches MaxFileSize. Use only with -start.
MaxFileSize specifies the maximum size of each log file in MB. Without a MaxFileSize value, this parameter is ignored. When using -newfile, you must also use the -f LogFile parameter, and the value of LogFile must be a name that includes the characters %d indicate a decimal pattern--for example, trace%d.etl. Otherwise, the command fails with ERROR\_INVALID\_NAME. Windows increments the decimal value in the file name each time it creates a new file. This parameter is not valid with preallocation (-prealloc logging (-cir), with the NT Kernel Logger session, or for private trace sessions. It is not supported in Windows 2000. |
| -append | Appends the trace messages to an existing event trace log (.etl) file. The default is to create a new file. Use only with -start.
This parameter is valid only on sequential files and only when -f is used and -rt is not used. It is not supported in Windows 2000. |
| -kd | Redirects the trace messages to KD or Windbg, whichever is attached. This parameter also sets the trace buffer size to 3 KB, the maximum buffer size for the debugger, and ignores any -b parameters in the command. Use only with -start. |
Comments
A traceview command with no parameters opens the TraceView window.
You can use the TraceView -start command to start a Global Logger trace session. To do so, use the following command format. Unlike other commands, the word "GlobalLogger" in this command format is case sensitive.
traceview -start GlobalLogger [parameters]
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for