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 8.1 or later version operating system.
Syntax
wpr FirstLevelOption [<arguments>] [Additional options [<arguments>]]
You can get additional help with:
wpr -help [start | stop | status | profiles | providers | tracing | boottrace | heap | hardwarecounter | advanced]
The following FirstLevelOptions are available:
| Option | Description |
|---|---|
| -help | Provide the list of sub-level 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 | (Obsolete) 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). |
| -merge | Merges etl files into the given file. |
| -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 PMU events available on the system. |
| -pmcsessions | Query the list of sessions using PMU events. |
| -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. |
Profiles
The Profiles option lists the WPR profiles that the recording uses.
Syntax
wpr -profiles [<path>]
The following table describes the available arguments that you can apply to this option. To see built-in profiles, omit the argument.
| Argument | Description |
|---|---|
| <path> | 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
wpr -start <profile> [-start <profilen>]... [-filemode] [-recordtempto <temp folder path>] [-onoffscenario <OnOff Transition Type>] [-onoffresultspath <path to which the trace files are saved>] [-onoffproblemdescription <description of the scenario>] [-numiterations <number of iterations for OnOff tracing>]
The following table describes the available switches that you can apply to this option.
| Switch | Description |
|---|---|
| <profile> [-start <profilen>]... | 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: <profile> := [<filename.wprp>!]<profile name>[.{light|verbose}] 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. |
| -shutdown [<KSR>] | Specifies that session info and recordings will persist over the reboot. Shutdown option works only with the file mode trace where as KSR only works only with the memory mode. Call -stop command at the next boot to merge the trace. |
| -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 <temp folder path> | Specifies the temporary folder path that the recording is saved to. |
| -onoffscenario <OnOff Transition Type> | Specifies one of the on/off transition types. These are: Boot, FastStartup, Shutdown, RebootCycle, Standby, or Hibernate. |
| -onoffresultspath <path to which the trace files are saved> | Specifies the path to which the trace files are saved. |
| -onoffproblemdescription <description of the scenario> | Specifies the description of the scenario. |
| -numiterations <number of iterations for OnOff tracing> | Sets the number of iterations for OnOff recording. By default, the settings from the built-in or custom profile file are used by default. |
Example
wpr -start CPU (Starts verbose CPU profile in memory mode)
wpr -start CPU.light -filemode (Starts light CPU profile in file mode)
wpr -start filename.wprp!ProfileName.Verbose (Starts verbose ProfileName profile defined in filename.wprp)
Stop
The Stop option stops the current recording and saves it to the file that is specified by the argument.
Syntax
wpr -stop <file> <problem description> -[skipPdbGen] [-force] [-compress]
The following table describes the available arguments that you can apply to this option.
| Argument | Description |
|---|---|
| <file name> | Specifies the event trace log (ETL) file to which WPR saves the recording. This argument is required. |
| <problem description> | 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. |
| -force | Disables the warning when the target file extension is not .etl. |
| -compress | Compresses output trace file. |
Merge
The Merge option merges etl files into the given file.
Syntax
wpr -merge <trace files ...> <merged file> -[skipPdbGen] [-compress] [-supresspii] [-mergeonly] [-injectonly]
The following table describes the available arguments that you can apply to this option.
| Argument | Description |
|---|---|
| <trace files ...> | Specifies one or more un-merged event trace log (ETL) files. This argument is required. |
| <merged file> | Specifies the output file into which WPR merges ETL file(s). |
| -skipPdbGen | Disables dynamic generation of ngen and embedded pdbs for .NET modules. This option can reduce the stop operation time. |
| -compress | Compresses output trace file. |
| -supresspii | Suppresses personally identifiable(PII) information. |
| -mergeonly | Merges the traces without adding machine-specific information or image ID events. Cannot be used with -injectonly. |
| -injectonly | Generates only machine-specific and/or image id events without copying original events in the merged file. |
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
wpr -cancel
This option takes no arguments.
Status
The Status option displays status information about the current WPR recording.
Syntax
wpr -status [profiles] [collectors [-details]]
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:
WPR recording is in progress...
Time since start : 00:04:27
Dropped event : 0
Logging mode : Memory
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: Recording system activity using the following set of profiles: |
| collectors | Lists collector information. If buffers have been lost, those buffers are listed.
Example: Actively recording collectors: |
| 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 <profilen> refers to the name of each profile.
Syntax
wpr -profiledetails <profile1>+<profile2>+...+<profilen> [-filemode] -onoffscenario <OnOff Transition Type>
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 <OnOff Transition Type> | 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 <profilen> 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 <profile name>[.{light|verbose}].
Syntax
wpr -exportprofile <profile1>+<profile2>+...+<profilen> <ExportedFileName.wprp> [-filemode]
This example exports the filemode verbose GeneralProfile profile into GeneralProfileVerboseFile.wprp file.
Example
wpr -exportprofile GeneralProfile d:\profiles\GeneralProfileVerboseFile.wprp -filemode
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
wpr -providers
This option takes no arguments.
Boottrace
The Boottrace option configures the registry entries for autologger/globallogger sessions for the given profile.
Syntax
wpr -boottrace {-addboot [<filename.wprp>!]<profile> [-addboot <profile> ...] [-filemode] [-recordtempto <temp folder path>] | -stopboot <recording filename> <Problem description> | -cancelboot}
The following table describes the available keywords that you can apply to this option.
| Argument | Description |
|---|---|
| -boottrace | Specifies the following argument is to set up the autologger. In current WPR, this argument is optional. |
| -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
wpr-capturestateondemand
Below is an example of EventProvider:
<EventProvider Id="EventProvider_Microsoft-Windows-Win32k" Name="Microsoft-Windows-Win32k" NonPagedMemory="true" CaptureStateOnly="true">
<CaptureStateOnDemand Timeout="5">
<Keyword Value="0x0"/>
</CaptureStateOnDemand>
</EventProvider>
Marker
The Marker option fires an event marker with the given text in the current system logging session.
Syntax
wpr -marker <text> [-flush]
| Argument | Description |
|---|---|
| -flush | Flushes the working set. Equivalent to -MarkerFlush. |
MarkerFlush (Obsolete)
The MarkerFlush option fires an event marker with the given text and flushes the working set. This command is obsolete in current WPR.
Syntax
wpr -markerflush <text>
Flush
The Flush option flushes logging sessions to files initiated through WPR.
Syntax
wpr -flush
This option takes no arguments.
HeapTracingConfig
The HeapTracingConfig option enables or disables heap tracing for a specific process or store application.
Syntax
wpr -HeapTracingConfig <process name> [<package full name> <package relative app ID>] [{enable|disable}]
Note
- 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
wpr -disablepagingexecutive {on | off}
Note
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.
Log
The Log option appends and configures debug logging to the event log.
Syntax
wpr -log {enabled | disabled | remove}
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
wpr -purgecache
This option takes no arguments.
Help
Use this option to display on-line help in the Command Prompt window.
Syntax
wpr -help [start | stop | status | profiles | providers | tracing | boottrace | heap | hardwarecounter | advanced]
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. |
| start | Describes the –start command-line argument. For more information, see Start. |
| stop | Describes the -stop, -merge, and -cancel command-line argument. |
| status | Describes -status command-line arguments. For more information, see Status. |
| profiles | Describes -profiles, -profiledetails, and -exportprofile command-line arguments. |
| providers | Describes the -providers command-line argument. For more information, see Providers. |
| tracing | Describes the –marker, -flush, and -capturestateondemand command-line argument. |
| boottrace | Describes the -addboot, -stopboot, and -cancelboot command-line arguments. |
| heap | Describes -heaptracingconfig, -snapshotconfig, -enableperiodicsnapshot, -disableperiodicsnapshot, and -singlesnapshot command-line arguments. |
| hardwarecounter | Describes -pmcsources, -pmcsessions, -setprofint, -profint, and -resetprofint command-line arguments. |
| advanced | Describes -purgecache, -log, -disablepagingexecutive, -instancename, and -container command-line arguments. |
SnapshotConfig
The SnapshotConfig option enables or disables the ability to capture one-time or periodic snapshots of <snapshot option>\ for a specific process or processes. Currently you can take take snapshots of the heap.
Syntax
wpr -SnapshotConfig <snapshot option> {-name <process name> | -pid <pid 1> [pid 2] ...} [{enable|disable}]
If the {enable|disable} 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:
wpr -snapshotconfig heap -name Win32Project1.exe //query snapshot config
wpr -snapshotconfig heap -name Win32Project1.exe enable //enable snapshot config
wpr -snapshotconfig heap -name Win32Project1.exe disable //disable snapshot config
This example uses the snapshotconfig command with a PID:
wpr -snapshotconfig heap -pid 8048 enable //enable snapshot config
Note
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 |
|---|---|
| <snapshot option> | 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 <snapshot option> for specified process ID.
Syntax
wpr -SnapshotConfig <snapshot option> <pid 1> [pid 2] ... [up to pid 8]
Note
The snapshot feature needs to be enabled for the process id (or name) before calling SingleSnapshot.
For example: wpr -singlesnapshot heap <pid for foo.exe>
Please refer to SnapshotConfig command for more information.
The following table describes the available switches that you can apply to this option.
| Switch | Description |
|---|---|
| <snapshot option> | Specifies one of the snapshot option type. |
| <pid> | Specifies the process id. |
EnablePeriodicSnapshot
The EnablePeriodicSnapshot option triggers periodic snapshots at specified intervals and given process IDs
Syntax
wpr -enableperiodicsnapshot <snapshot option> <interval (in seconds)> <pid 1> [pid 2] ... [up to pid 8]
Note
The snapshot feature needs to be enabled for the process id (or name) before calling SingleSnapshot.
For example: wpr -enableperiodicsnapshot heap 60 <pid for foo.exe>
Please refer to SnapshotConfig command for more information.
The following table describes the available switches that you can apply to this option.
| Switch | Description |
|---|---|
| <snapshot option> | Specifies one of the snapshot option type. |
| <interval> | Specifies the interval in seconds. Note that the minimum valid interval is 5. |
| <pid> | Specifies the process id. |
DisablePeriodicSnapshot
The DisablePeriodicSnapshot option disables periodic snapshots for all processes specified by the enableperiodicsnapshot option.
Syntax
wpr -disableperiodicsnapshot <snapshot option>
Example
wpr -disableperiodicsnapshot heap
The following table describes the available switches that you can apply to this option.
| Switch | Description |
|---|---|
| <snapshot option> | Specifies one of the snapshot option types. |
PMCSources
The PMCSources option queries the list of PMU (Performance Monitoring Unit) events on the system and their default interval value for the counter overflow. The interval is the number of events.
Syntax
wpr -pmcsources
Note
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:
C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit>wpr -pmcsources
Id Name Interval Min Max
--------------------------------------------------------------
0 Timer 10000 1221 1000000
2 TotalIssues 698400 4096 2147483647
6 BranchInstructions 65536 4096 2147483647
10 CacheMisses 65536 4096 2147483647
11 BranchMispredictions 65536 4096 2147483647
19 TotalCycles 65536 4096 2147483647
25 UnhaltedCoreCycles 65536 4096 2147483647
26 InstructionRetired 65536 4096 2147483647
27 UnhaltedReferenceCycles 65536 4096 2147483647
28 LLCReference 65536 4096 2147483647
29 LLCMisses 65536 4096 2147483647
30 BranchInstructionRetired 65536 4096 2147483647
31 BranchMispredictsRetired 65536 4096 2147483647
32 LbrInserts 65536 4096 2147483647
PMCSessions
The PMCSessions options query the list of sessions using hardware counters. This option is only available on Windows 11 or later.
Syntax
wpr -pmcsessions
ProfInt
The ProfInt option queries the “profiling” interval.
Syntax
wpr -profint
Example
C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit>wpr -profint
Current Profile Interval = 10000 [1.0000ms]
SetProfInt
The SetProfInt option sets the sampling profile interval for PMU events. If PMU event name is omitted, the default is Timer.
Syntax
wpr -setprofint [PMU event name] 1221...10000000
Example
C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit>wpr -setprofint 100000
New Profile Interval = 100000 [10.0000ms]
C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit>wpr -setprofint TotalIssues 1000000
New Profile Interval = 100000 [Counter: TotalIssues]
ResetProfInt
The ResetProfInt option resets the profile interval to the default value.
Syntax
wpr -resetprofint [Profile Source Name]
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
wpr –{option <arguments>} -instancename <text>
Note
-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:
C:\wpt>wpr -start cpu -instancename CpuSession
C:\wpt>wpr -status -instancename CpuSession
WPR recording is in progress...
...
Time since start : 00:00:05
Dropped event : 0
Logging mode : Memory
C:\wpt>wpr -stop cpu.etl -> omitting instancename option would not find CpuSession
There are no trace profiles running.
Error code: 0xc5583000
C:\wpt>wpr -stop cpu.etl -instancename CpuSession -> trace will be saved
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.