start

  • Article

Applies To: Windows 8, Windows 8.1

Displays logger start options.

xperf [-start [LoggerName] [ProfileFileName!ProfileName|SessionName]|-update [LoggerName]|[ProfileFileName!ProfileName|SessionName]] -flush [LoggerName] -save ProfileFileName!ProfileName|SessionName merged.etl -setprofint [<n>] [cached] -seteresourcesample <n1> <n2> <n3> -setspinlocksample <n1> <n2> <n3> -pooltag <P1>+<P2>+<P3>+<P4> -on (GUID|KnownProviderName)[:Flags[:Level[<:0xnnnnnnnn|’stack|[,]sid[,]tsid’]]]

Parameters

Command Description

-start[LoggerName]|[ProfileFileName!ProfileName|SessionName]]

Starts a logging session for LoggerName, starts loggers in profile ProfileName defined in the ProfileFileName file, or starts logger SessionName defined in the ProfileFileName file.

-update[LoggerName]|[ProfileFileName!ProfileName|SessionName]]

Updates a logging session for LoggerName, updates loggers in profile ProfileName defined in the ProfileFileName file, or updates logger SessionName defined in the ProfileFileName file.

-flushLoggerName

Flushes a logging session for LoggerName. This parameter is required to save a buffer mode trace (see -buffering parameter, below). To save a buffer mode trace, you must issue the -flush parameter.

-capturestateLoggerName Flags

Captures state to non-kernel logging session from providers specified in Flags. The accepted provider format is the same as for -on. If flags and level are specified, they are enabled while capturing state.

This is called for tracing started with the –buffering option. It must be followed by –stop to stop tracing.

-onFlags|Groups

For kernel logging sessions, the sequence of kernel flags and groups to be enabled, separated by plus signs (+). For user logging sessions, the sequence of providers to be enabled, separated by plus signs (+). The accepted provider format is (GUID|KnownProviderName)[:Flags[:Level]]. See providers for a list of valid flags.

-ffilename

Logs events to the specified file. The default is \Kernel.etl for kernel traces and \User.etl for user traces.

-buffersizeSize

Sets trace buffer size to Size, in KB. Possible values are 4 to 1024. The default is 64.

-minbuffersn

Sets the minimum number of trace buffers to n. The default is 64.

-maxbuffersn

Sets the maximum number of trace buffers to n. The default is 320.

-maxfileSize

Sets maximum file size to Size MB.

-flushtimern

Sets the flush timer to n seconds.

-boottraceFlags|Groups|off

Configures the Event Tracing for Windows® logger to trace boot. Set flags to "off" to turn off boot tracing. All logging control can be used in conjunction with this. Use in conjunction with -f to log to a file other than \Perf.etl.

-realtime

Enables real-time tracing.

-buffering

Enables buffering mode tracing. To save, use -flush. The -stop option does not save the trace.

-filemodeMode

Sets the file mode. The default is "Sequential". Possible modes: "Sequential", "Circular", "Append", and "NewFile".

-clocktypeClockType

Sets the clock type. The default is "PerfCounter". Possible types: "Cycle", "PerfCounter", and "SystemTime".

-stackwalkflags|@file

Enables stack walking for the events specified as Flag+..., or parses the file File for flags. For more information, see stackwalk.

-pidspid [...]

Applies flags to processes pid [...]. Used in conjunction with private loggers.

-pidnewprocess<command-line>

Applies flags to a new process that Xperf will start with <command-line>. Used in conjunction with private loggers.

-waitfornewprocess

Waits for a new process created using -pidNewProcess to return before exiting.

-heap

Enables heap tracing in processes specified by Pids and PidNewProcess.

-critsec

Enables critical section tracing in processes specified by Pids and PidNewProcess.

-setprofint[<n>] [cached]

Sets sampled profile interval to <n> [1221..10000000]. If cached is specified, intervals are cached in ETW and reapplied whenever new ETW kernel loggers with sampled profile are started. The units are 100ns. The default value for n is 10000; that is, 1ms: not cached.

-saveProfileFileName!ProfileName|SessionName merged.etl

Flushes the loggers in profile ProfileName defined in file ProfileFileName and merges the ETL files to merged.etl; or flushes logger SessionName defined in file ProfileFileName and merges the ETL file to Merged.etl.

-seteresourcesample<n1> <n2> <n3>

Sets ERESOURCE sampling, where n1 release sampling rate is greater than or equal to 1000, n2 contention sampling rate is greater than or equal to 1, and n3 number of excessive timeouts is greater than or equal to 1. The contention sample rate is the rate at which spinlock events are acquired when collisions occur. For example, if this value is 100, one spinlock event is acquired for each one hundred Spin Lock collisions.

-setspinlocksample<n1> <n2> <n3>

Sets the spinlock spin threshold to <n1> [ >=1]. Sets the spinlock acquire sample rate to <n2> [ >= 1000]. Sets the spinlock contention sample rate to <n3> [ >= 1]. Only 64-bit Windows 7, Windows Server® 2008 R2, and newer versions of the operating system support spinlock instrumentation.

-pooltag<P1>+<P2>+<P3>+<P4>

Sets the pool tag filters (Pn) separated by plus signs (+) or semicolons (;). Use a question mark (?) for a single-character wildcard or an asterisk (*) for a multiple-character wildcard. A maximum of four filters can be specified.

Remarks

Multiple loggers can be started using multiple start options, each followed by the options to be applied to that logger. If LoggerName or -start LoggerName is omitted, the kernel logger is implied. Only a single instance of the kernel logger can exist at any time. If one of the loggers fails to start, all the loggers that are already started are stopped.

See Also

Other Resources

Xperf Options