WPR Command-Line Options

  • Article

Applies To: Windows 8, Windows 8.1

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

WPR requires Windows® 7 or later version operating system.

Syntax:

wpr {-profiles [<path> [ …]] | -start*<arguments>* | -stop*<arguments>* | -cancel | -status*<arguments>* | -log*<argument>* | -purgecache | -help*<arguments>* | -profiledetails | -disablepagingexecutive}

The following sections describe the command-line options:

  • Profiles

  • Start

  • Stop

  • Cancel

  • Status

  • Profiledetails

  • Disablepagingexecutive

  • Log

  • Purgecache

  • Remarks

Note

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:
The event collector was already running.
In this case, you must cancel the other recording before you can start a new recording by using WPR.

Profiles

Use this option to list 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.

Argument Description

<path>

To see built-in profiles, omit the argument.

To list the profiles that are defined in a profile definition file, specify the path and name of that file.

Example:
wpr -profiles
wpr -profiles “c:\Users\User1\Documents\WPR Files\Custom Profiles\CustomProfile1.wprp”

Start

Use this option to start 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 arguments that you can apply to this option.

Argument Description

<profile> or <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. Each profile is specified in the following way:

<profile> :=<profile_name>[.{light|verbose}]

<profile_name>

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. For proper syntax, see the preceding code sample for <profile> or <profilen>.

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

-onoffresultspath

Path to which the trace files are saved.

-onoffproblemdescription

Description of the scenario.

-onoffscenario

Specifies one of the on/off transition types. These are: Boot, FastStartup, Shutdown, RebootCycle, Standby, or Hibernate.

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

Stop

Use this option to stop the current recording and save it to the file that is specified by the argument.

Syntax:

wpr-stop*<file><problem description*>

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

Argument Description

<file>

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.

Cancel

Use this option to cancel the current recording without saving the recorded data. If no instance is currently active, an error is returned.

Syntax:

wpr-cancel

This option takes no arguments.

Status

Use this option to display 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:

Profile : CPU.Verbose.Memory

collectors

Lists collector information. If buffers have been lost, those buffers are listed.

Example:

Actively recording collectors:
Collector Name          : NT Kernel Logger
Buffer Size (KB)        : 1024
Events Lost             : 0
System Keywords
        CSwitch
        ProcessThread
        SampledProfile
System Stacks
        CSwitch
        SampledProfile
Collector Name          : WPR_initiated_WPR Event Collector
Buffer Size (KB)        : 1024
Events Lost             : 0
Providers
        Microsoft-Windows-Shell-Core: 0x1000000000000: 0x04
        Microsoft-Windows-Win32k: 0x1000000402000: 0xff : Stack
CaptureState Providers on Save
        Microsoft-Windows-Win32k: 0x80000: 0xff

details

Lists additional information about each collector.

Profiledetails

Use this option to display 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>

Disablepagingexecutive

Use this option to turn Disable Paging Executive settings On or Off.

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, you can operate performance recording without setting disablepagingexecutive to On.

Log

Use this option to append and configure debug logging to the event log.

Syntax:

wpr-log {enabled|disabled|remove}

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

Argument 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

Use this option to purge 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.

wpr-help [{log|profiles|profiledetails\disablepagingexecutive\start|status|stop}]

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

Argument Description

cancel

Describes –cancel command-line arguments. For more information, see Cancel.

disablepagingexecutive

Describes –disablepagingexecutive command-line argument. For more information, see Disablepagingexecutive.

log

Describes -log command-line arguments. For more information, see Log.

profiledetails

Describes –profiledetails command-line argument. For more information, see Profiledetails.

profiles

Describes -profiles command-line arguments. For more information, see Profiles.

purgecache

Describes –purgecache command-line arguments. For more information, see Purgecache.

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

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.

See Also

Other Resources

WPR Reference