How to Use TRACERT to Troubleshoot TCP/IP Problems in Windows

For a Microsoft Windows 2000 version of this article, see 162326.

Summary

This article describes TRACERT (Trace Route), a command-line utility that you can use to trace the path that an Internet Protocol (IP) packet takes to its destination.

This article discusses the following topics:

How to Use the TRACERT Utility

How to Use TRACERT to Troubleshoot

How to Use TRACERT Options

More Information

How to Use the TRACERT Utility

The TRACERT diagnostic utility determines the route to a destination by sending Internet Control Message Protocol (ICMP) echo packets to the destination. In these packets, TRACERT uses varying IP Time-To-Live (TTL) values. Because each router along the path is required to decrement the packet’s TTL by at least 1 before forwarding the packet, the TTL is effectively a hop counter. When the TTL on a packet reaches zero (0), the router sends an ICMP «Time Exceeded» message back to the source computer.

TRACERT sends the first echo packet with a TTL of 1 and increments the TTL by 1 on each subsequent transmission, until the destination responds or until the maximum TTL is reached. The ICMP «Time Exceeded» messages that intermediate routers send back show the route. Note however that some routers silently drop packets that have expired TTLs, and these packets are invisible to TRACERT.

TRACERT prints out an ordered list of the intermediate routers that return ICMP «Time Exceeded» messages. Using the -d option with the tracert command instructs TRACERT not to perform a DNS lookup on each IP address, so that TRACERT reports the IP address of the near-side interface of the routers.

In the following example of the tracert command and its output, the packet travels through two routers (157.54.48.1 and 11.1.0.67) to get to host 11.1.0.1. In this example, the default gateway is 157.54.48.1 and the IP address of the router on the 11.1.0.0 network is at 11.1.0.67.

C:\>tracert 11.1.0.1
The output from the command:

Tracing route to 11.1.0.1 over a maximum of 30 hops
—————————————————
1 2 ms 3 ms 2 ms 157.54.48.1
2 75 ms 83 ms 88 ms 11.1.0.67
3 73 ms 79 ms 93 ms 11.1.0.1

How to Use TRACERT to Troubleshoot

You can use TRACERT to find out where a packet stopped on the network. In the following example, the default gateway has found that there is no valid path for the host on 22.110.0.1. Probably, either the router has a configuration problem, or the 22.110.0.0 network does not exist, reflecting a bad IP address.

C:\>tracert 22.110.0.1
The output from the command:

Tracing route to 22.110.0.1 over a maximum of 30 hops
——————————————————
1 157.54.48.1 reports: Destination net unreachable.

Trace complete.
TRACERT is useful for troubleshooting large networks where several paths can lead to the same point or where many intermediate components (routers or bridges) are involved.

How to Use TRACERT Options

There are several command-line options that you can use with TRACERT, although the options are not usually necessary for standard troubleshooting.

The following example of command syntax shows all of the possible options:

tracert -d -h maximum_hops -j host-list -w timeout target_hostWhat the parameters do:

-d
Specifies to not resolve addresses to host names

-h maximum_hops
Specifies the maximum number of hops to search for the target

-j host-list
Specifies loose source route along the host-list

-w timeout
Waits the number of milliseconds specified by timeout for each
reply

target_host
Specifies the name or IP address of the target host

Trace-Command

Configures and starts a trace of the specified expression or command.

Syntax

Description

The Trace-Command cmdlet configures and starts a trace of the specified expression or command. It works like Set-TraceSource, except that it applies only to the specified command.

Examples

Example 1: Trace metadata processing, parameter binding, and an expression

This example starts a trace of metadata processing, parameter binding, and cmdlet creation and destruction of the Get-Process Notepad expression.

It uses the Name parameter to specify the trace sources, the Expression parameter to specify the command, and the PSHost parameter to send the output to the console. Because it does not specify any tracing options or listener options, the command uses the defaults:

• All for the tracing options
• None for the listener options

Example 2: Trace the actions of ParameterBinding operations

This example traces the actions of the ParameterBinding operations of PowerShell while it processes a Get-Alias expression that takes input from the pipeline.

In Trace-Command , the InputObject parameter passes an object to the expression that is being processed during the trace.

The first command stores the string i* in the $A variable. The second command uses the Trace-Command cmdlet with the ParameterBinding trace source. The PSHost parameter sends the output to the console.

The expression being processed is Get-Alias $Input , where the $Input variable is associated with the InputObject parameter. The InputObject parameter passes the variable $A to the expression. In effect, the command being processed during the trace is Get-Alias -InputObject $A» or «$A | Get-Alias .

Parameters

Specifies the parameters and parameter values for the command being traced. The alias for ArgumentList is Args. This feature is especially useful for debugging dynamic parameters.

For more information about the behavior of ArgumentList, see about_Splatting.

Type:	Object [ ]
Aliases:	Args
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies a command that is being processed during the trace.

Type:	String
Position:	1
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Indicates that the cmdlet sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Visual Studio. This parameter also selects the default trace listener.

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies the expression that is being processed during the trace. Enclose the expression in braces ( <> ).

Type:	ScriptBlock
Position:	1
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies a file that the cmdlet sends the trace output to. This parameter also selects the file trace listener.

Type:	String
Aliases:	PSPath, Path
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Forces the command to run without asking for user confirmation. Used with the FilePath parameter. Even using the Force parameter, the cmdlet cannot override security restrictions.

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies input to the expression that is being processed during the trace. You can enter a variable that represents the input that the expression accepts, or pass an object through the pipeline.

Type:	PSObject
Position:	Named
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	False

Specifies optional data to the prefix of each trace message in the output. The acceptable values for this parameter are:

• None
• LogicalOperationStack
• DateTime
• Timestamp
• ProcessId
• ThreadId
• Callstack

None is the default.

These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the ListenerOption parameter as an array of values or as a comma-separated string of those values. The cmdlet will combine the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values.

Type:	TraceOptions
Accepted values:	None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Specifies an array of PowerShell components that are traced. Enter the name of the trace source of each component. Wildcards are permitted. To find the trace sources on your computer, type Get-TraceSource .

Type:	String [ ]
Position:	0
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Determines the type of events that are traced. The acceptable values for this parameter are:

• None
• Constructor
• Dispose
• Finalizer
• Method
• Property
• Delegates
• Events
• Exception
• Lock
• Error
• Errors
• Warning
• Verbose
• WriteLine
• Data
• Scope
• ExecutionFlow
• Assert
• All

All is the default.

The following values are combinations of other values:

• ExecutionFlow : Constructor , Dispose , Finalizer , Method , Delegates , Events , Scope
• Data : Constructor , Dispose , Finalizer , Property , Verbose , WriteLine
• Errors : Error , Exception

These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the Option parameter as an array of values or as a comma-separated string of those values. The cmdlet will combine the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values.

Type:	PSTraceSourceOptions
Accepted values:	None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All
Position:	2
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Indicates that the cmdlet sends the trace output to the PowerShell host. This parameter also selects the PSHost trace listener.

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

You can pipe objects that represent input to the expression to Trace-Command .

Outputs

Returns the command trace in the debug stream.

Notes

Tracing is a method that developers use to debug and refine programs. When tracing, the program generates detailed messages about each step in its internal processing.

The PowerShell tracing cmdlets are designed to help PowerShell developers, but they are available to all users. They let you monitor nearly every aspect of the functionality of the shell.

To find the PowerShell components that are enabled for tracing, type Get-Help Get-TraceSource .

A trace source is the part of each PowerShell component that manages tracing and generates trace messages for the component. To trace a component, you identify its trace source.

A trace listener receives the output of the trace and displays it to the user. You can elect to send the trace data to a user-mode or kernel-mode debugger, to the host or console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.

When you use the commandSet parameter set, PowerShell processes the command just as it would be processed in a pipeline. For example, command discovery is not repeated for each incoming object.

The names of the Name, Expression, Option, and Command parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Name, Expression, Option or Name, Command, Option. If you include the parameter names, the parameters can appear in any order.

Tracelog Command Syntax

Tracelog has commands (or actions) that start, stop, and control a trace session.

To control a trace session you must be a member of the Performance Log Users group or the Administrators group on the computer (Run as administrator).

Parameters

For information about the Tracelog parameters, see [actions] [options].

[actions]

-addautologger [LoggerName]
Configures the registry entries for an autologger session. An autologger session is the preferred method for tracing the activity of a driver or other trace provider during system boot. You must specify the session GUID using the -sessionguid option. The tracelog -addautologger command takes the same options as the Tracelog -start command.

-capturestate [LoggerName]
Requests all providers enabled to LoggerName to log state information. The keywords enabled help determine the kind of information that is logged.

-disable [LoggerName]
Disables the specified trace providers. When a provider is disabled, it continues to run, but it stops generating trace messages.

The tracelog -stop command disables the trace providers before stopping the session. You do not need to disable providers before stopping a trace session. However, you can use the tracelog -disable command to disable selected providers without stopping a trace session.

Disabling stops the trace provider from sending trace messages to the trace session buffers, but it does not flush the buffers or stop the trace session. Use a tracelog -flush command to flush the buffers and a tracelog -stop or tracelog -x (stop all) command to stop the trace session.

Tracelog uses the EnableTrace function to implement a tracelog -disable command. For more information about this function, see the Microsoft Windows SDK documentation.

-enable [LoggerName]
Enables one or more trace providers for the LoggerName trace session.

When you enable a provider, the provider generates trace messages and sends them to the buffers of a trace session. If the provider is not running (or is not loaded) when you enable it, the system pre-registers the provider, that is, it reserves space for the provider in the ETW registration database and saves the enable command. When the provider starts and actually registers, it receives the saved enable command and begins sending trace messages to the session.

The tracelog -start command enables any providers specified by the optional -guid parameter in the tracelog -start command. You do not need to submit a separate tracelog -enable command.

You can use a tracelog -enable command to add a provider to a running trace session, to change the flags and level for a provider while it is tracing, or to re-enable a provider that you disabled by using a tracelog -disable command.

When using the tracelog -enable command, first submit a tracelog -start command to start the trace session, and then submit the tracelog -enable command to enable the providers.

You can enable a running provider repeatedly without disabling it. (You might do this to change the flags and levels.)

The trace flags and trace level that you specify with the -flag and -level parameters are passed to all trace providers represented by the -guid parameter. To specify different flags and levels for each trace provider, submit a separate tracelog -enable command for each provider, with its own flag and level settings.

If you enable any of the NT Kernel Logger flags (such as -noprocess, -nothread, -fio, or -cm) while a Global Logger trace session is running, the Global Logger session is converted to an NT Kernel Logger trace session. This feature is designed to trace kernel events during the boot process.

-enableex [LoggerName]
Identical to -enable. This option may be removed in future versions of Tracelog.

-enumguid
Enumerates (or lists) providers on the system that are registered with Event Tracing for Windows (ETW). For a description of the Enumguid display, see Tracelog Enumguid Display.

Tracelog uses the EnumerateTraceGuids function to implement a tracelog -enumguid command. For more information about this function, see the Microsoft Windows SDK documentation.

-enumguidex [#guid]
Enumerates (or lists) providers on the system that are registered with Event Tracing for Windows (ETW). For a description of the EnumguidEx display, see Tracelog Enumguid Display.

Tracelog uses the EnumerateTraceGuidsEx function to implement a tracelog -enumguidex command. For more information about this function, see the Microsoft Windows SDK documentation.

-flush [LoggerName]
Flushes the active buffers of the LoggerName trace session. If LoggerName is not specified, Tracelog flushes the buffers of the NT Kernel Logger trace session.

This forced flush is in addition to the flushes that occur automatically whenever a trace message buffer is full and when the trace session stops, and in addition to the flushes that are activated by the flush timer (-ft).

When you flush the buffers of a trace session, the events in the buffers are delivered to the trace log or trace consumer immediately.

Flushing does not disable the trace provider or redirect the trace messages. After the buffers are flushed, the trace provider continues writing events to the buffers.

Tracelog uses the FlushTrace function to implement a tracelog -flush command. For more information about this function, see the Microsoft Windows SDK documentation.

You can use the tracelog -flush command with the -f Logfile option to flush the trace messages that are currently in the buffer to the specified trace log (.etl) file. This parameter is valid only for buffered trace sessions (-buffering); for other trace session types, the -f parameter is ignored.

This flush affects only the current contents of the buffer. It does not redirect future trace messages to the trace log.

-l [-lp]
Lists the properties of all trace sessions running on the computer.

If you pass the -lp option, Tracelog will also list all the providers enabled to each session.

-q [LoggerName] [-lp]
Lists (queries) the properties of the specified trace session. If you do not specify LoggerName, Tracelog queries the NT Kernel Logger trace session.

If you pass the -lp option, Tracelog will also list all the providers enabled to the session.

-remove GlobalLogger
Removes and reinitializes the registry values for a Global Logger trace session. It sets the value of the Start entry to 0 (do not start) and deletes the other registry entries. The tracelog -remove command works only for Global Logger trace sessions. All other session name values are invalid.

The tracelog -remove command is not required. However, if you do not set the value of the Start entry to 0, a Global Logger session starts every time you reboot the system.

If you do not use a tracelog -remove command, the options from the previous session are still in the registry, and they will be used for the new session unless you submit a tracelog -start command with different values for the same options.

-start [LoggerName]
Starts a trace session using the LoggerName that you select to represent the trace session.

Use GlobalLogger as the LoggerName to specify a Global Logger Trace Session. The session starts when you restart the computer.

The LoggerName can be any name that meets Windows naming guidelines, up to 1,024 characters. If the name includes spaces, enclose the name in quotation marks. Tracelog is not case-sensitive.

The default is «NT Kernel Logger». If you omit this parameter, Tracelog starts an NT Kernel Logger trace session and declares an error if you use the -guid parameter to specify a different trace provider.

-stop [LoggerName]
Disables the providers in the specified trace session and then terminates the session.

The tracelog -stop command both disables the trace providers and stops the trace session. A tracelog -disable command only disables the trace providers.

If you start a Boot-Time Global Logger session which traces kernel events, you need to use the command tracelog -stop «NT Kernel Logger» or tracelog -stop GlobalLogger to stop it. When you use either of commands to stop a Global Logger trace session trace session, Tracelog stops the provider, but it does not reset the values of the registry entries. To reset the values of the Global Logger registry entries, use tracelog -remove.

-systemrundown [LoggerName]
Requests the SystemTraceProvider to log rundown events directed at LoggerName session. See Configuring and Starting a SystemTraceProvider Session for information about starting a trace session.

This command is only available on Windows 8 and later versions of Windows.

-timeout value
Specifies the timeout value, in milliseconds (ms), to use when enabling providers with the tracelog -enable command. The default timeout is 0.

If the timeout value is 0, the Tracelog will call each provider’s enable callback and return immediately, without waiting for the callback to complete.

To enable providers synchronously, specify a timeout value. If you specify a timeout value, Tracelog will wait until each provider’s enable callback exits or the timeout expires.

When enabling multiple providers at once, the timeout is applied to each one sequentially.

-update [LoggerName]
The tracelog -update command changes the properties of a trace session while it is running.

In a tracelog -update command, the —guid parameter is valid only when updating a private trace session (-um).To add or remove providers from a standard trace session while the session is running, use the tracelog -enable and tracelog -disable commands.

If you start a trace log session (-f), you can update to a real-time session (-rt), but messages continue to be sent to the trace log in addition to the trace consumer. You cannot eliminate the log from the session by updating. However, before you can add real-time message delivery to a trace log session, you must first use the tracelog -flush command to flush the buffers.

If you start a real-time session (-rt) and then update to a trace log session (-f), new trace messages are no longer sent directly to the trace consumer; they are sent only to the trace log. To add a trace log to a real-time trace session, use both -rt and -f in the tracelog -update command. Before you can add real-time message delivery to a trace log session, you must first use the tracelog -flush command to flush the buffers.

For a private (user-mode) trace session, you can update only the log file name (-f) and the flush timer value (-ft).

To update the flags and levels, use the tracelog -enable command to re-enable the provider with new flags or levels.

Tracelog uses the ControlTrace function to implement a tracelog -update command. For more information about this function, see the Microsoft Windows SDK documentation.

[options]

-addtotriagedump

This option should not be used except when you might need to view events from a kernel dump using the debugger.

Specifies that any active buffers for the session are available to be added to a triage memory dump. Triage dumps are limited in size, and if the session’s buffers cause the dump to exceed its maximum size, the buffers will be left out.

-append
Appends the trace messages to the event trace log (.etl) file specified by the -f parameter. The default is to create a new file.

This parameter is valid only in commands that include -f and do not include -rt or -cir.

-b BufferSize
Specifies the size, in KB, of each buffer 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.

-bt n
Specifies the number (n) of buffers to fill before starting to flush them. This option is available starting in Windows 8.1.

-buffering
Starts a buffered trace session.

In a buffered trace session, the trace messages are retained in the trace buffers. They are not sent to a trace consumer or recorded in a trace log.

-cir MaxFileSize
Specifies circular logging (at end-of-file, record new messages over the oldest messages) in the event trace log (.etl) file. 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.

-cm
Enables tracing of registry (Configuration Manager) access. This parameter is valid only for an NT Kernel Logger trace session.

-critsec
Traces critical section events for a process in a private trace session. You can start a critical section process logger on any user-mode process, even one that is not instrumented for tracing.

Use -pids to specify the process. Do not use -guid with -critsec. The system defines a custom GUID (CritSecGuid) for critical section traces. You cannot use -heap and -critsec in the same command.

-dpcisr
Enables tracing of deferred procedure calls (DPCs), interrupt service requests (ISRs), image load events (-img), and context switches in the kernel. This parameter is valid only for an NT Kernel Logger trace session.

This option is supported only in the version of Tracelog included in the Windows Driver Kit for Windows Vista and later versions of the WDK. The –dpcisr option cannot be used with the -eflag option.

Use the -UsePerfCounter parameter with -dpcisr. This parameter, which provides a unique time stamp for each event, is required by Tracerpt, a tool used to format and interpret DPC/ISR events. For information about interpreting and formatting these events, see «Comments», below.

-eflag n [flag. ]
Enables kernel events using additional flags for NT Kernel Logger trace sessions, most notably, the flags to enable tracing of DPC, ISR, and context switch events. The -eflag option cannot be used with the –dpcisr option.

-enableproperty n
See the description of EnabledProperties in the EnableParameters struct passed as a parameter to EnableTraceEx2 for descriptions and supported values.

-EventIdFilter <-in|-out> **** n **** id1 id2 .
Specifies an event id filter with n event ids (maximum 64 event ids allowed). This option is available starting in Windows 8.1.

-ExeFilter Executable_file [; Executable_file . ]
Specifies the names of executable files to filter. You can specify a list of files. Separate the names of the files using semi-colons. Files not listed are excluded. This option is available starting in Windows 8.1.

-f [LogFile]
Starts a trace log session. LogFile specifies the path (optional) and file name of the event trace log (.etl) file. The default is C:\LogFile.etl. To place the file on a remote computer, include the computer name or IP address in the path.

If you use -rt with -f, the trace messages are sent to the consumer and to an event trace log file. You cannot use -rt or -f with -buffering.

-fio
Enables tracing of file I/O events. This parameter is valid only for an NT Kernel Logger trace session.

-flag Flag

Flags have been superseded by keywords. Use -matchanykw unless you are enabling a WPP provider.

Specifies the trace flags for the providers in the trace session. The flag value determines 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 flag value is defined independently by each trace provider. Typically, flags represent increasingly detailed reporting levels.

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

-ft FlushTime
Specifies how often, in seconds, the trace message buffers are flushed. 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 the tracelog -flush command.

-guid <#GUID | file | *name>
Enables the specified trace providers.

If a file is specified, Tracelog will enable tracing for all the providers specified in the file. The file must be formatted as:

If a provider GUID is specified, the GUID must be preceeded by a number sign (#).

If a provider name is specified, the name must be preceeded by an asterisk (*). The name will then be converted into a GUID using the same algorithm as .NET’s Event Source. This GUID will then be used to enable the provider.

If you omit this parameter, no trace providers will send messages to the trace session. However, after starting the trace session, you can use a tracelog -enable command to enable one or more trace providers for the session.

-gs
Generates a global sequence number for each trace message.

Global sequence numbers are unique for all trace sessions on the computer. By default, there are no sequence numbers.

This parameter is not valid with the NT Kernel Logger trace session.

-heap
Traces heap memory events for a user-mode process. You can start a heap process logger on any user-mode process, even one that is not instrumented for tracing.

Use -pids to specify the process. Do not use -guid with -heap. The system defines a custom GUID (HeapGuid) for heap memory traces. You cannot use -heap and -critsec in the same command.

-hf
Enables tracing of hard page faults (page faults that require disk access to resolve). This parameter is valid only for an NT Kernel Logger trace session.

-hybridshutdown <stop|persist>
Controls hybrid shutdown logger behavior. This option is available starting in Windows 8.

stop will cause the session to stop when the system performs a hybrid shutdown. persist will cause the session to continue after the system starts up again from a hybrid shutdown.

-img
Enables tracing of image load events. This parameter is valid only for an NT Kernel Logger trace session.

-independent

Independent mode should be enabled on every trace session.

Enables independent mode on the trace session. Independent mode allows the session to collect events that other non-independent-mode sessions have dropped. This option is available starting in Windows 8.1.

-kb
Use kilobytes (KB) for log file size. The default is megabytes (MB).

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

The debugger must be running when you submit a Tracelog command with -kd. Otherwise, Tracelog stops responding.

For information about displaying trace messages in a kernel debugger, see Comments.

-Lbr *EventName[**+EventName+. ]:Filter[,*Filter. ]
Configure LBR tracing on kernel events.

Use -eflag Help for a list of kernel events.

-level n
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).

The level value specified in a tracelog -start command applies to all trace providers in the trace session. To set different levels for each trace provider, use tracelog -enable.

-lowcapacity

This option should not be used unless necessary to reduce memory costs. Using this option makes each event slower to log.

Uses a single buffer at a time to gather events generated on multiple processors. This option selects the EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING logging mode. For more information, see the Windows SDK.

-ls
Generates a local sequence number for each trace message.

Local sequence numbers are unique within a trace session. By default, there are no sequence numbers.

This parameter is not valid with the NT Kernel Logger trace session.

-max NumberOfBuffers
Specifies the maximum number of buffers that Tracelog allocates 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.

-matchallkw n
Specifies the MatchAllKeyWord bitmask that restricts the category of events the provider writes and is used in conjunction with the -matchanykw option.

This bitmask is optional. If the event’s keyword meets the condition specified in the —matchanykw option, the provider will write the event only if all of the bits in this mask exist in the event’s keyword. This mask is not used if -matchanykw is zero.

Tracelog passes the value n in the MatchAllKeyWord parameter of the EnableTraceEx2 function call. See the Windows SDK for more information.

-matchanykw n
Specifies the MatchAnyKeyword bitmask that determines the category of events the provider writes.

The provider writes the event if any of the event’s keyword bits match any of the bits set in this mask. Tracelog passes the value n in the MatchAnyKeyWord parameter of the EnableTraceEx2 function call. See the Windows SDK for more information.

-min NumberOfBuffers
Specifies the number of buffers initially allocated for storing trace messages. When the buffers are full, Tracelog allocates more buffers until it reaches the maximum. The default value is determined by the number of processors, the amount of physical memory, and the operating system in use.

-newfile MaxFileSize
Creates a new event trace log (.etl) file whenever the existing file reaches MaxFileSize. 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 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.

-nodisk
Disables tracing of physical disk I/O events. This parameter is valid only for an NT Kernel Logger trace session.

-nonet
Disables tracing of TCP/IP and User Datagram Protocol (UDP) events. This parameter is valid only for an NT Kernel Logger trace session.

-noprocess
Disables tracing of the start and end of each process. This parameter is valid only for an NT Kernel Logger trace session.

-nothread
Disables tracing of the start and end of each thread. This parameter is valid only for an NT Kernel Logger trace session.

-paged
Uses pageable memory for the trace message buffers. By default, event tracing uses nonpageable memory for buffers.

Providers that require nonpageable memory will not be able to log events to a session that uses pageable memory.

-pids #PIDs PID [PID. ]
Specifies the user-mode processes in which a heap memory or critical section trace session runs. Valid only with -heap or -critsec.

#PIDs specifies the number of process IDs listed with this parameter. PID represents a process identifier. You can specify up to ten PIDs with this parameter.

List multiple PIDs when the provider runs in more than one process, such as when a single program creates multiple processes.

-PidFilter n pid1 pid2 .
Specifies a Pid filter with n Pids (maximum 8 allowed). This option is available starting in Windows 8.1.

-pf
Enables tracing of all page faults. This parameter is valid only for an NT Kernel Logger trace session.

-PkgIdFilter Package Full Name [ **;**Package Full Name. ]
Specifies a package ID filter. You can specify a list of package files. Separate the names of the files using semi-colons.

-PkgAppIdFilter PRAID [**;**PRAID. ]
Specifies a package-relative app identifier (PRAID) filter. The PRAID is the unique identifier of the application within the package. You can specify more than one PRAID. Separate the IDs using semi-colons. This option is available for UWP apps starting in Windows 8.1.

-Pmc Ctr1,Ctr2. Name+Name+.
Configures performance monitor counter (PMC) sampling on the specified kernel events. This option is available starting in Windows 8.

Use -ProfileSource Help for a list of counters. Use -eflag Help for a list of kernel events.

-prealloc
Reserves space for the .etl file before starting the session.

This parameter requires -seq or -cir with MaxFileSize. It is not valid with -newfile.

-ProfileSource src
Configure profiling source to use. For list of sources, use the command tracelog -ProfileSource Help. This option is available starting in Windows 8.

This option is only available on Windows 8 and later versions of Windows.

-rt
Starts a real-time trace session. (A trace log session (-f) is the default.)

If you use -rt and -f, the trace messages are sent to the trace consumer and to an event trace log file. You cannot use -rt or -f with -buffering. For more information, see Trace Session.

-secure
Enables tracing in secure mode. This option selects the EVENT_TRACE_SECURE_MODE logging mode. Restricts who can log events to the session to those with TRACELOG_LOG_EVENT permission.

-sessionguid
Specifies the autologger session GUID registry value.

-SetProfInt n **** src

Changing the profiling interval is not recommended.

Configure the profiling interval (n) for the specified source, where n is in units of 100ns. The default is 10000 (which is equivalent to 1ms). This option is available starting in Windows 8.

-seq MaxFileSize
Specifies sequential logging (at end-of-file, stop recording events) to the event trace log (.etl) file. 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.

-sourceguid SourceGuid
Specifies the GUID passed as the SourceId parameter to the EnableTraceEx or EnableTraceEx2 functions. The SourceId identifies the session that enabled the provider.

-stackwalk [Events]
Specifies kernel events to collect stacks on. Use -eflag Help for a list of kernel events. This parameter is valid only for the NT Kernel Logger or system logger trace sessions.

-StackWalkFilter <-in|-out>nid1 id2 .
Specifies an event ID filter with n event IDs (maximum 64 event IDs allowed). This option is available starting in Windows 8.1.

-systemlogger
Logger can receive SystemTraceProvider events. See Configuring and Starting a SystemTraceProvider Session. This option is available starting in Windows 8.

-um
Specifies a private trace session This parameter is required for a private trace session.

-UseCPUCycle
Uses the processor frequency (also called «CPU ticks») to measure the time of each trace message.

This timer provides the highest possible resolution, but it is so sensitive that it is prone to error, especially on power-managed systems and multiprocessor computers. For example, if you specify this timer on computer that has an ARM processor, it might result in out-of-order events. Instead, -UsePerfCounter is recommended for high-resolution tracing.

-UsePerfCounter is the default timer for event tracing.

-UsePerfCounter
Records the value of the high-resolution performance counter clock, rather than lower-resolution system time, with each trace message.

Because the performance counter clock counts in approximately 100-nanosecond units, it provides a unique time stamp for each event.

-UsePerfCounter is the default timer for event tracing.

-UseSystemTime
Records the system time, rather than the high-resolution performance counter clock time, with each trace message. Because the system timer has a resolution of 10 milliseconds (compared to 100 nanoseconds for the performance counter clock), multiple events can have the same system time.

-UsePerfCounter is the default timer for event tracing.

-? | help | -?
Displays usage information.

Comments

The following comments apply to several of the Tracelog commands.

Syntax Errors

Tracelog does not display errors for all incorrect syntax combinations, such as when you try to update a setting that cannot be changed. Instead, it ignores the invalid parts of the command and displays a success message.

System Loggers

Windows uses trace sessions for many purposes, some of which are critical for proper operation. Do not stop any trace sessions that you did not start.

Enumguid

To determine whether a tracelog -start or tracelog -enable command was successful, use a tracelog -enumguid command to determine whether the providers were enabled, and then use a tracelog -l (List) command to examine the properties of the trace session.

Real-time and log sessions

A trace session can be both a real-time trace session and a trace log session. If you include the -rt (real-time) and -f (log session) parameters in the same command, the system sends the buffer contents both to the log and to a trace consumer. However, before you can add real-time message delivery to a trace log session, the buffers must be flushed by using the tracelog -flush command.

If you start a real-time session (-rt) and then update to a log session (-f), any new trace messages are sent only to the log file. To add a log file to a real-time session, use both -rt and -f in the tracelog -update command.

If you start a log session (-f), you can update to a real-time session (-rt), but messages continue to be sent to the log in addition to the trace consumer. You cannot eliminate the log from the session by updating.

To display or save trace messages from a real-time-only session, you can also use a trace consumer, such as Tracefmt, or use TraceView, which is both a trace controller (like Tracelog) and a trace consumer. When using Tracefmt, be sure to include the -rt parameter in the Tracefmt command.

Flags and levels

Most trace providers do not generate any trace messages unless the flag or level is set to a particular value. The providers use flags or levels to control what is being traced. If the event trace log file is empty, review the flags and levels in the trace provider.

To ensure that trace messages are always generated, complete the following steps:

Set the flags parameter to 0xFFFFFFFF to enable all flag settings.

Set the levels parameter to 255 to enable all level settings.

The -eflag parameter

Tracelog has an -eflag (extended flags) parameter that was designed to enable additional flags for the NT Kernel Logger trace session—most notably, the flags to enable tracing of DPC, ISR, and context switch events. Because the tracelog -start command now includes the -dpcisr parameter, use of the -eflag parameter is no longer necessary and is not recommended.

Outdated parameters

In previous versions of Tracelog, the tracelog -start command supported the -rt b parameter combination. This combination has been replaced by the -buffering parameter and it is no longer valid.

The -x parameter has been removed because stopping all trace sessions can cause system instability.

The -disableex parameter has been removed. Use -disable instead.

NT Kernel Logger

To start a trace session with the NT Kernel Logger, omit the session name from the tracelog -start command and do not use the -guid parameter to specify a provider GUID file. «NT Kernel Logger» is the default session name.

If the session name is omitted or is «NT Kernel Logger», the system starts an NT Kernel Logger trace session, even if you use a -guid parameter to specify a GUID other than SystemTraceControlGUID, the control GUID for the NT Kernel Logger trace session. If you specify a different GUID, the system returns an error, («System Logger does not accept application guids»), but still starts an NT Kernel Logger trace session.

By default, when Tracelog starts an NT Kernel Logger trace session, it enables traces of process, thread, physical disk I/O, and TCP/IP events, but you can use the parameters to disable tracing of these events and enable tracing of other events.

DPC/ISR events

Because Tracerpt expects a system performance counter clock time as the time stamp, use the Tracelog -UsePerfCounter parameter when you start the trace session.

Because DPC and ISR events are collected by special instrumentation, they do not appear in the Enabled tracing row of the table that Tracelog displays to confirm a command.