WPR Command-Line Options

Windows Performance Recorder (WPR) offers a simple command line interface. The full complexity of WPR is embedded in the recording profiles.

General options

WPR requires Windows 7 or later version operating system.

Syntax

You can get additional help with:

The following FirstLevelOptions are available:

Option	Description
-help	Provide command line help information
-profiles	Enumerates the profile names and descriptions from a profile
-purgecache	Purges the dynamic symbols cache
-start	Starts one or more profiles.
-marker	Fires an event marker
-markerflush	Fires an event marker and flushes the working set.
-status	Displays the status of an active recording (if any).
-profiledetails	Fires an event marker and flushes the working set.
-exportprofile	export built-in profile to a file
-providers	Displays detailed information about providers.
-cancel	Cancels the recording initiated by WPR (if any).
-stop	Cancels and saves the recording initiated by WPR (if any).
-flush	Flushes the logging sessions initiated by WPR (if any).
-log	Configures the debug information saved to the event log.
-disablepagingexecutive	Changes the Disable Paging Executive settings
-heaptracingconfig	Changes a processes’ heap tracing settings
-snapshotconfig	Change snapshot settings for a process
-capturestateondemand	Captures the states of the configured providers in the current recording.
-pmcsources	Queries the list of hardware counters available on the system.
-setprofint	Sets the sampled profile interval.
-profint	Queries the current profile interval.
-resetprofint	Restores the default profile interval values.
-boottrace	Configures the registry entries for autologger/globallogger sessions
-enableperiodicsnapshot	Enables Periodic Snapshot for the specified interval and given process id.
-disableperiodicsnapshot	Disables Periodic Snapshot for all process
-singlesnapshot	Gets an on-demand Snapshot for the specified process.

If you start WPR from the command line while another application is recording (such as Xperf or an application that uses NT Kernel Logger, such as logman or PerfTrace), WPR fails to start recording and returns the following error. In this case, you must cancel the other recording before you can start a new recording by using WPR:

The event collector was already running.

Profiles

The Profiles option lists the WPR profiles that the recording uses.

Syntax

The following table describes the available arguments that you can apply to this option. To see built-in profiles, omit the argument.

Argument	Description
	Specifies the path and the name of the file that contains the profile definitions. For example: wpr -profiles “c:\Users\User1\Documents\WPR Files\Custom Profiles\CustomProfile1.wprp”

Start

The Start option starts a recording by using one or more profiles.

Syntax

The following table describes the available switches that you can apply to this option.

Switch	Description
].	Specifies either a built-in profile or the path to a user-defined profile. You can specify up to 64 profiles on a single command line, with each profile specified as follows: Each profile can define either light or verbose versions, or both versions. If neither option is specified, the verbose version is used unless the profile includes only a light version.
-filemode	Specifies that recording is done in file mode. (The default mode is memory.) By using this option, the data is recorded to an unbounded file, which can grow in size until it fills the disk.
-recordtempto	Specifies the temporary folder path that the recording is saved to.
-onoffscenario	Specifies one of the on/off transition types. These are: Boot, FastStartup, Shutdown, RebootCycle, Standby, or Hibernate.
-onoffresultspath	Specifies the path to which the trace files are saved.
-onoffproblemdescription	Specifies the description of the scenario.
-numiterations	Sets the number of iterations for OnOff recording. By default, the settings from the built-in or custom profile file are used by default.

The Stop option stops the current recording and saves it to the file that is specified by the argument.

Syntax

The following table describes the available arguments that you can apply to this option.

Argument	Description
Specifies the event trace log (ETL) file to which WPR saves the recording. This argument is required.
	Specifies the problem description. Although this argument is optional, we recommended that you use it.
-skipPdbGen	Disables dynamic generation of ngen and embedded pdbs for .NET modules. This option can reduce the stop operation time.

Cancel

The Cancel option cancels the current recording without saving the recorded data. If no instance is currently active, the Cancel option returns an error.

Syntax

This option takes no arguments.

Status

The Status option displays status information about the current WPR recording.

Syntax

If no recording is currently active, a message displays that WPR is not recording. If a recording is currently active and no arguments are used, the following status information displays:

If you supply arguments together with the –status option, the information listed above displays together with data that is specific to that option. The following table describes the available arguments that you can apply to this option.

Argument	Description and Example Output
profiles	This argument lists each profile that is being used in the current WPR recording. Example:
collectors	Lists collector information. If buffers have been lost, those buffers are listed. Example:
details	Lists additional information about each collector.

Profiledetails

The Profiledetails option displays detailed information about a profile or set of profiles. To specify multiple profiles, use the following syntax where

refers to the name of each profile.

Syntax

The following table describes the available switches that you can apply to this option.

Switch	Description
-filemode	Specifies that recording was done in file mode. (The default mode is memory.)
-onoffscenario	Specifies one of the on/off transition types. These are: Boot, FastStartup, Shutdown, RebootCycle, Standby, or Hibernate.

ExportProfile

The ExportProfile option exports the built-in profile(s) to the given file. Use wpr -Profiles command to enumerate available built-in profiles. To specify multiple profiles, use the following syntax where

refers to the name of each profile. The naming convention of the profiles is exactly the same as used in wpr -start . A profile is specified as

Syntax

This example exports the filemode verbose GeneralProfile profile into GeneralProfileVerboseFile.wprp file.

Example

Providers

The Providers option displays detailed information about providers. Providers refer to the Event Tracing for Windows (ETW) components that expose events to Windows Performance Recorder (WPR). To display information about providers, use the following syntax, where -providers refers to all installed/known and registered providers.

Syntax

This option takes no arguments.

Boottrace

The Boottrace option configures the registry entries for autologger/globallogger sessions for the given profile.

Syntax

The following table describes the available keywords that you can apply to this option.

Keyword	Description
-addboot	Sets the autologger registry entries for the given profile. The wpr -addboot command takes the same options as the wpr -start command. Note that this options does not immediately start the trace. After reboot, the autologger will be started by the operating system.
-stopboot	Removes the autologger configured by addboot, stops the boot recording and merges all the recording into the given file. Note that this option saves the trace only if the autologger session is running (i.e. after reboot). Otherwise, this option will remove only the autologger configuration.
-cancelboot	Removes the autologger configured by addboot and cancels the boot recording initiated by WPR.

CaptureStateOnDemand

The CaptureStateOnDemand option captures states for the configured providers in the current recording. The event provider should be configured for capturestateondemand within the profile file while the session is running.

Syntax

Below is an example of EventProvider:

Marker

The Marker option fires an event marker with the given text in the current system logging session.

Syntax

MarkerFlush

The MarkerFlush option fires an event marker with the given text and flushes the working set.

Syntax

Flush

The Flush option flushes logging sessions to files initiated through WPR.

Syntax

This option takes no arguments.

HeapTracingConfig

The HeapTracingConfig option enables or disables heap tracing for a specific process or store application.

Syntax

• If the <enable|disable> parameter is omitted, the current heap tracing configuration for the process or app will be displayed. For example: wpr -HeapTracingConfig Heaptest.exe enable
• This command doesn’t immediately start the trace, and should be executed before taking the heap trace. See Recording for Heap Analysis for more details.
• Always disable HeapTracingConfig for the process after tracing is done since it can impact the performance of the process.

Disablepagingexecutive

The Disablepagingexecutive option specifies whether drivers and kernel-mode system code can be paged to disk. Setting this option to on prevents paging. This option sets the value of DisablePagingExecutive in the registry.

Syntax

To correctly capture event stacks on 64-bit systems that are running Windows 7, disablepagingexecutive should be set to On, and the system must be rebooted before you start performance recording. For 32-bit systems that are running Windows 7 and for all systems that are running Windows 8 or higher, you can operate performance recording without setting disablepagingexecutive to On.

The Log option appends and configures debug logging to the event log.

Syntax

The following table describes the available keywords that you can apply to this option.

Keyword	Description
enabled	Enables debug logging to the event log
disabled	Disables debug logging to the event log
remove	Uninstalls the WPR debug logging provider manifest from the system

Purgecache

The Purgecache option purges the managed symbols cache.

Syntax

This option takes no arguments.

Use this option to display on-line help in the Command Prompt window.

Syntax

The following table describes the available keywords that you can apply to this option.

Keyword	Description
No keyword	Displays a list of options and short descriptions. To get further help for specific options, use a keyword. For example: wpr -help start .
cancel	Describes the –cancel command-line argument. For more information, see Cancel.
disablepagingexecutive	Describes the –disablepagingexecutive* command-line argument.
log	Describes -log command-line arguments. For more information, see Log.
profiledetails	Describes the –profiledetails command-line argument.
profiles	Describes -profiles command-line arguments. For more information, see Profiles.
providers	Describes the -providers command-line argument. For more information, see Providers.
purgecache	Describes the –purgecache command-line argument.
start	Presents descriptions of -start command-line arguments. For more information, see Start.
status	Presents descriptions of -status command-line arguments. For more information, see Status.
stop	Describes -stop command-line arguments. For more information, see Stop.

SnapshotConfig

The SnapshotConfig option enables or disables the ability to capture one-time or periodic snapshots of \ for a specific process or processes. Currently you can take take snapshots of the heap.

Syntax

If the parameter is omitted, the current snapshot configuration for the process will be displayed (i.e. only the -name option).

This example uses the snapshotconfig command with image names:

This example uses the snapshotconfig command with a PID:

If the process and OS architecture does not match match (for example, a win32 app on a 64bit Operating system), use the image name option.

The following table describes the available switches that you can apply to this option.

Switch	Description
Specifies one of the snapshot option types. Currently only the Heap is available.
-name	Specifies the name of process. This switch cannot be used with -Pid switch. If this switch is used to enable the snapshot, the config will apply to all new instances of the specified process name. Please be sure to disable it when the testing has finished.
-pid	Specifies the process id. This switch cannot be used with -name switch. If this switch is used to enable the snapshot, the configuration will be applied immediately and for the lifetime of the process.

SingleSnapshot

The SingleSnapshot option triggers an on-demand snapshot of for specified process ID.

Syntax

The snapshot feature needs to be enabled for the process id (or name) before calling SingleSnapshot.

For example: wpr -singlesnapshot heap

Please refer to SnapshotConfig command for more information.

The following table describes the available switches that you can apply to this option.

Switch	Description
Specifies one of the snapshot option type.
Specifies the process id.

EnablePeriodicSnapshot

The EnablePeriodicSnapshot option triggers periodic snapshots at specified intervals and given process IDs

Syntax

The snapshot feature needs to be enabled for the process id (or name) before calling SingleSnapshot.

For example: wpr -enableperiodicsnapshot heap 60

Please refer to SnapshotConfig command for more information.

The following table describes the available switches that you can apply to this option.

Switch	Description
Specifies one of the snapshot option type.
Specifies the interval in seconds. Note that the minimum valid interval is 5.
Specifies the process id.

DisablePeriodicSnapshot

The DisablePeriodicSnapshot option disables periodic snapshots for all processes specified by the enableperiodicsnapshot option.

Syntax

Example

The following table describes the available switches that you can apply to this option.

Switch	Description
Specifies one of the snapshot option types.

PMCSources

The PMCSources option queries the list of hardware counters on the system and their default sampling rates.

Syntax

Performance Monitor Unit events are used to measure CPU performance and understand workloads CPU characterization. Only a subset of PMU events in ARM/intel reference documents are implemented in Windows HAL. The example output of this option on Intel CPU device is below:

ProfInt

The ProfInt option queries the “profiling” interval.

Syntax

Example

SetProfInt

The SetProfInt option sets the sampled profile interval in 100 ns units.

Syntax

Example

ResetProfInt

The ResetProfInt option resets the profile interval to the default value.

Syntax

Note that if [Profile Source Name] is not provided, all profile sources will be reset to the default value.

Instancename

The Instancename option specifies a name to uniquely identify the tracing instance.

This option can be applied to any commands that manipulate the logging session and assigns a user supplied logging session name. WPR sets the default session name if this option is omitted.

Syntax

-instancename must be the last parameter. If the logging sessions were started with this option, all the subsequent commands should use the same instancename option. For example:

Remarks

Each time that WPR saves a trace that was captured when managed applications were running on the system, WPR saves managed symbols next to the trace file. This feature enables performance analysis of managed applications.

Generating managed symbols is a resource- and time-consuming operation. WPR automatically creates a managed symbol cache to expedite the generation of managed symbols. When WPR needs managed symbols, it first checks this cache and uses any available and appropriate symbols instead of regenerating them.

The default managed symbol cache location is C:\ProgramData\WindowsPerformanceRecorder\NGenPdbs_Cache.