Table of contents
TOC
Collapse the table of content
Expand the table of content

TraceView Control Commands

Last Updated: 4/22/2017

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}

Parameters

Actions

-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.

Subparameters of -guidDescription

-flagFlag

Specifies the trace flags for the providers in the trace session. The flags determine which events the trace provider generates.

Flag represents a flag value defined in the trace provider, in decimal or hexadecimal format. The default value is 0. Values from 0x01000000 through 0xFF000000 are reserved for future use.

The meaning of the flags is defined independently by each trace provider. Typically, flags represent increasingly detailed reporting levels.

In a -start command, the flags value applies to all trace providers in the trace session. To set different flags for each trace provider, use a separate -enable command for each trace provider.

-levelLevel

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.

-bBufferSize
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.

-minNumberOfBuffers
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.

-maxNumberOfBuffers
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.

-ftFlushTime
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.

-ageAgeLimit
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.

-seqMaxFileSize
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.

-cirMaxFileSize
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.

In Windows XP and later systems, 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.

-newfileMaxFileSize
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 -fLogFile parameter, and the value of LogFile must be a name that includes the characters %d to 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), circular 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]

Send comments about this topic to Microsoft

© 2017 Microsoft