WPR 命令行选项

项目
06/19/2023

Windows Performance Recorder (WPR) 提供了一个简单的命令行界面。 WPR 的全部复杂性嵌入在记录配置文件中。

常规选项

WPR 需要Windows 8.1或更高版本的操作系统。

语法

wpr FirstLevelOption [<arguments>] [Additional options [<arguments>]]

可以通过以下方式获得额外的帮助：

wpr -help [start | stop | status | profiles | providers | tracing | boottrace | heap | hardwarecounter | advanced]

可以使用以下 FirstLevelOptions：

选项	描述
-help	提供子级别帮助信息的列表。
-profiles	枚举配置文件中的配置文件名称和说明。
-purgecache	清除动态符号缓存。
-start	启动一个或多个配置文件。
-marker	触发事件标记。
-markerflush	(已过时) 触发事件标记并刷新工作集。
-status	显示活动记录的状态（如果有）。
-profiledetails	触发事件标记并刷新工作集。
-exportprofile	将内置配置文件导出到文件。
-providers	显示有关提供程序的详细信息。
-cancel	取消由 WPR 发起的记录（如果有）。
-stop	取消并保存由 WPR 发起的记录（如果有）。
-合并	将 etl 文件合并到给定文件中。
-flush	刷新由 WPR 发起的日志记录会话（如果有）。
-log	配置保存到事件日志的调试信息。
-disablepagingexecutive	更改 “禁用分页执行人员 ”设置。
-heaptracingconfig	更改进程的堆跟踪设置。
-snapshotconfig	更改进程的快照设置。
-capturestateondemand	捕获当前记录中已配置的提供程序的状态。
-pmcsources	查询系统上可用的 PMU 事件列表。
-pmcsessions	使用 PMU 事件查询会话列表。
-setprofint	设置采样的配置文件间隔。
-profint	查询当前配置文件间隔。
-resetprofint	还原默认配置文件间隔值。
-boottrace	为 autologger/globallogger 会话配置注册表项。
-enableperiodicsnapshot	为指定的间隔和给定的进程 ID 启用“定期快照”。
-disableperiodicsnapshot	为所有进程禁用定期快照。
-singlesnapshot	为指定进程获取按需快照。

配置文件

Profiles 选项列出了记录使用的 WPR 配置文件。

语法

wpr -profiles [<path>]

下表描述了可应用于此选项的可用参数。若要查看内置配置文件，请省略参数。

参数	说明
<path>	指定包含配置文件定义的文件的路径和名称。例如： `wpr -profiles “c:\Users\User1\Documents\WPR Files\Custom Profiles\CustomProfile1.wprp”`

开始

Start 选项使用一个或多个配置文件启动记录。

语法

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

下表描述了可应用于此选项的可用开关。

开关	说明
<profile> [-start<profilen>]...	指定内置配置文件或用户定义配置文件的路径。在单个命令行上最多可以指定 64 个配置文件，按以下方式指定每个配置文件： <profile> ：= [<filename.wprp>！]<配置文件名称>[.{light\|verbose}] 每个配置文件可以定义精简版本或详细版本，也可以同时定义这两个版本。如果未指定任何选项，则使用详细版本，除非配置文件仅包含精简版本。
-shutdown [<KSR>]	指定会话信息和录制在重新启动后将保留。关闭选项仅适用于文件模式跟踪，其中 KSR 仅适用于内存模式。在下一次启动时调用 -stop 命令以合并跟踪。
-filemode	指定在文件模式下完成记录。 (默认模式为 memory。) 通过使用此选项，数据将记录到未绑定的文件中，该文件的大小可能会增大，直到它填满磁盘。
-recordtempto<临时文件夹路径>	指定记录保存到的临时文件夹路径。
-onoffscenario<OnOff 转换类型>	指定开/关转换类型之一。包括：“Boot”、“FastStartup”、“Shutdown”、“RebootCycle”、“Standby”或“Hibernate”。
将跟踪文件保存到>的 -onoffresultspath<路径	指定用于保存跟踪文件的路径。
-onoffproblemdescription<方案>说明	指定场景的描述。
-numiterations<OnOff 跟踪>的迭代次数	设置 OnOff 记录的迭代次数。默认情况下会使用内置配置文件或自定义配置文件中的设置。

示例

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 选项停止当前记录，并将其保存到参数指定的文件中。

语法

wpr -stop <file> <problem description> -[skipPdbGen] [-force] [-compress]

下表描述了可应用于此选项的可用参数。

参数	说明
<文件名>	指定 WPR 向其保存记录的事件跟踪日志 (ETL) 文件。此参数是必需的参数。
<问题说明>	指定问题说明。尽管此参数是可选的，但建议使用它。
-skipPdbGen	禁用 .NET 模块的 ngen 和嵌入的 pdb 的动态生成。此选项可以减少停止操作时间。
-force	当目标文件扩展名不是 .etl 时禁用警告。
-压缩	压缩输出跟踪文件。

合并

“ 合并” 选项将 etl 文件合并到给定文件中。

语法

wpr -merge <trace files ...> <merged file> -[skipPdbGen] [-compress] [-supresspii] [-mergeonly] [-injectonly]

下表描述了可应用于此选项的可用参数。

参数	说明
<跟踪文件...>	指定一个或多个未合并的事件跟踪日志 (ETL) 文件。此参数是必需的参数。
<合并文件>	指定 WPR 将 ETL 文件 () 合并到的输出文件。
-skipPdbGen	禁用 .NET 模块的 ngen 和嵌入的 pdb 的动态生成。此选项可以减少停止操作时间。
-压缩	压缩输出跟踪文件。
-supresspii	禁止显示个人身份 (PII) 信息。
-mergeonly	合并跟踪，而不添加特定于计算机的信息或图像 ID 事件。不能与 -injectonly 一起使用。
-injectonly	仅生成特定于计算机的和/或图像 ID 事件，而不复制合并文件中的原始事件。

取消

Cancel 选项取消当前记录，不保存记录的数据。如果当前没有任何实例处于活动状态，“取消”选项将返回错误。

语法

wpr -cancel

此选项不采用任何参数。

状态

Status 选项显示有关当前 WPR 记录的状态信息。

语法

wpr -status [profiles] [collectors [-details]]

如果当前没有任何记录处于活动状态，则会显示一条消息，指出 WPR 未记录。如果记录当前处于活动状态，并且没有使用参数，则会显示以下状态信息：

WPR recording is in progress...

Time since start        : 00:04:27

Dropped event           : 0

Logging mode            : Memory

如果将参数与 –status 选项一起提供，上面列出的信息会与特定于该选项的数据一起显示。下表描述了可应用于此选项的可用参数。

参数	说明和示例输出
profiles	此参数列出当前 WPR 记录中使用的每个配置文件。示例： Recording system activity using the following set of profiles: Profile : CPU.Verbose.Memory
collectors	列出收集器信息。如果缓冲区已丢失，则会列出这些缓冲区。示例： Actively recording collectors: 收集器名称： NT 内核记录器缓冲区大小 (KB) ： 1024 事件丢失： 0 系统关键字 CSwitch ProcessThread SampledProfile 系统堆栈 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	列出有关每个收集器的其他信息。

profiles

此参数列出当前 WPR 记录中使用的每个配置文件。

示例：

Recording system activity using the following set of profiles:

Profile : CPU.Verbose.Memory

collectors

列出收集器信息。如果缓冲区已丢失，则会列出这些缓冲区。

示例：

Actively recording collectors:

收集器名称： NT 内核记录器缓冲区大小 (KB) ： 1024 事件丢失： 0 系统关键字 CSwitch ProcessThread SampledProfile 系统堆栈 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

列出有关每个收集器的其他信息。

Profiledetails

Profiledetails 选项显示有关一个或一组配置文件的详细信息。若要指定多个配置文件，请使用以下语法，其中 <profilen> 引用每个配置文件的名称。

语法

wpr -profiledetails <profile1>+<profile2>+...+<profilen> [-filemode] -onoffscenario <OnOff Transition Type>

下表描述了可应用于此选项的可用开关。

开关	说明
-filemode	指定在文件模式下完成记录。（默认模式为“memory”。）
-onoffscenario<OnOff 转换类型>	指定开/关转换类型之一。包括：“Boot”、“FastStartup”、“Shutdown”、“RebootCycle”、“Standby”或“Hibernate”。

ExportProfile

ExportProfile 选项将内置配置文件导出到给定文件。使用 wpr -Profiles 命令枚举可用的内置配置文件。若要指定多个配置文件，请使用以下语法，其中 <profilen> 指的是每个配置文件的名称。配置文件的命名约定与 wpr -start 中使用的命名约定完全相同。配置文件被指定为 <profile name>[.{light|verbose}]。

语法

wpr -exportprofile <profile1>+<profile2>+...+<profilen> <ExportedFileName.wprp> [-filemode]

此示例将 filemode verbose GeneralProfile 配置文件导出到 GeneralProfileVerboseFile.wprp 文件中。

示例

wpr -exportprofile GeneralProfile d:\profiles\GeneralProfileVerboseFile.wprp -filemode

提供程序

Providers 选项显示有关提供程序的详细信息。提供程序指的是将事件公开到 Windows Performance Recorder (WPR) 的 Windows 事件跟踪 (ETW) 组件。若要显示有关提供程序的信息，请使用以下语法，其中 -providers 指的是所有已安装/已知且已注册的提供程序。

语法

wpr -providers

此选项不采用任何参数。

Boottrace

Boottrace 选项为给定配置文件的自动记录器/全局记录器会话配置注册表项。

语法

wpr -boottrace {-addboot [<filename.wprp>!]<profile> [-addboot <profile> ...] [-filemode] [-recordtempto <temp folder path>] | -stopboot <recording filename> <Problem description> | -cancelboot}

下表描述了可应用于此选项的可用关键字。

参数	说明
-boottrace	指定以下参数用于设置自动记录器。在当前 WPR 中，此参数是可选的。
-addboot	为给定配置文件设置自动记录器注册表项。 `wpr -addboot` 命令采用与 `wpr -start` 命令相同的选项。请注意，此选项不会立即启动跟踪。重新启动后，自动记录器将由操作系统启动。
-stopboot	删除 addboot 配置的自动记录器，停止启动记录，并将所有记录合并到给定文件中。请注意，仅当自动记录器会话正在运行时（例如，重新启动后），此选项才会保存跟踪。否则，此选项将仅删除自动记录器配置。
-cancelboot	删除 addboot 配置的自动记录器，并取消由 WPR 发起的启动记录。

CaptureStateOnDemand

CaptureStateOnDemand 选项捕获当前记录中已配置的提供程序的状态。在会话运行过程中，应为配置文件中的 capturestateondemand 配置事件提供程序。

语法

wpr-capturestateondemand

下面是 EventProvider 的一个示例：

<EventProvider Id="EventProvider_Microsoft-Windows-Win32k" Name="Microsoft-Windows-Win32k" NonPagedMemory="true" CaptureStateOnly="true">
      <CaptureStateOnDemand Timeout="5">
         <Keyword Value="0x0"/>
      </CaptureStateOnDemand>
    </EventProvider>

记号笔

Marker 选项在当前系统日志记录会话中触发具有给定文本的事件标记。

语法

wpr -marker <text> [-flush]

参数	说明
-冲洗	刷新工作集。等效于 -MarkerFlush。

MarkerFlush (已过时)

MarkerFlush 选项触发具有给定文本的事件标记并刷新工作集。此命令在当前 WPR 中已过时。

语法

wpr -markerflush <text>

刷新

Flush 选项刷新通过 WPR 发起的文件的日志记录会话。

语法

wpr -flush

此选项不采用任何参数。

HeapTracingConfig

HeapTracingConfig 选项启用或禁用特定进程或存储应用程序的堆跟踪。

语法

wpr -HeapTracingConfig <process name> [<package full name> <package relative app ID>] [{enable|disable}]

注意

如果省略 {enable|disable} 参数，将显示进程或应用的当前堆跟踪配置。例如：wpr -HeapTracingConfig Heaptest.exe enable
此命令不会立即启动跟踪，应在使用堆跟踪之前执行。有关更多详细信息，请参阅记录以进行堆分析。
跟踪完成后，一定要禁用进程的 HeapTracingConfig，因为它会影响进程的性能。

Disablepagingexecutive

Disablepagingexecutive 选项指定是否可以将驱动程序和内核模式系统代码分页到磁盘。将此选项设置为“On”会阻止分页。此选项设置注册表中 DisablePagingExecutive 的值。

语法

wpr -disablepagingexecutive {on | off}

注意

若要在运行 Windows 7 的 64 位系统上正确捕获事件堆栈，应将 disablepagingexecutive 设置为“On”，并且必须先重新启动系统，再启动性能记录。对于运行 Windows 7 的 32 位系统以及运行 Windows 8 或更高版本的所有系统，可以在不将 disablepagingexecutive 设置为“On”的情况下操作性能记录。

日志

Log 选项为事件日志追加和配置调试日志记录。

语法

wpr -log {enabled | disabled | remove}

下表描述了可应用于此选项的可用关键字。

关键字	说明
enabled	为事件日志启用调试日志记录
disabled	为事件日志禁用调试日志记录
remove	从系统中卸载 WPR 调试日志记录提供程序清单

Purgecache

Purgecache 选项清除托管符号缓存。

语法

wpr -purgecache

此选项不采用任何参数。

帮助

使用此选项可在“命令提示符”窗口中显示联机帮助。

语法

wpr -help [start | stop | status | profiles | providers | tracing | boottrace | heap | hardwarecounter | advanced]

下表描述了可应用于此选项的可用关键字。

关键字	说明
No keyword	显示选项列表和简短说明。若要获取有关特定选项的更多帮助，请使用关键字。例如：`wpr -help start`。
start	描述 –start 命令行参数。有关详细信息，请参阅 Start。
stop	描述 -stop、 -merge 和 -cancel 命令行参数。
status	描述 -status 命令行参数。有关详细信息，请参阅 Status。
profiles	描述 -profiles、 -profiledetails 和 -exportprofile 命令行参数。
providers	描述 -providers 命令行参数。有关详细信息，请参阅 Providers。
tracing	描述 –marker、 -flush 和 -capturestateondemand 命令行参数。
boottrace	描述 -addboot、 -stopboot 和 -cancelboot 命令行参数。
heap	介绍 -heaptracingconfig、 -snapshotconfig、 -enableperiodicsnapshot、 -disableperiodicsnapshot 和 -singlesnapshot 命令行参数。
hardwarecounter	介绍 -pmcsources、 -pmcsessions、 -setprofint、 -profint 和 -resetprofint 命令行参数。
advanced	介绍 -purgecache、 -log、 -disablepagingexecutive、 -instancename 和 -container 命令行参数。

SnapshotConfig

SnapshotConfig 选项启用或禁用为特定进程捕获快照选项>\ 的<一次性或定期快照的功能。目前，你可以拍摄堆的快照。

语法

wpr -SnapshotConfig <snapshot option> {-name <process name> | -pid <pid 1> [pid 2] ...} [{enable|disable}]

{enable|disable}如果省略参数，则进程的当前快照配置将显示在 (，即仅) -name 选项。

下面的示例使用带有映像名称的 snapshotconfig 命令：

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

下面的示例使用带有 PID 的 snapshotconfig 命令：

wpr -snapshotconfig heap -pid 8048 enable                //enable snapshot config

注意

如果进程和 OS 体系结构不匹配（例如，64 位操作系统上的 win32 应用），请使用映像名称选项。

下表描述了可应用于此选项的可用开关。

开关	说明
<快照选项>	指定快照选项类型之一。目前只有堆可用。
-name	指定进程的名称。此开关不能与 -Pid 开关一起使用。如果此开关用于启用快照，则配置将应用于指定进程名称的所有新实例。请确保在测试完成后禁用它。
-pid	指定进程 ID。此开关不能与 -name 开关一起使用。如果此开关用于启用快照，将立即应用配置并在进程生存期内应用。

SingleSnapshot

SingleSnapshot 选项触发指定进程 ID 的<按需快照快照选项>。

语法

wpr -SnapshotConfig <snapshot option> <pid 1> [pid 2] ... [up to pid 8]

注意

在调用“SingleSnapshot”之前，需要为进程 ID（或名称）启用快照功能。

例如：wpr -singlesnapshot heap <pid for foo.exe>

有关详细信息，请参阅 SnapshotConfig 命令。

下表描述了可应用于此选项的可用开关。

开关	说明
<快照选项>	指定快照选项类型之一。
pid<>	指定进程 ID。

EnablePeriodicSnapshot

EnablePeriodicSnapshot 选项按指定间隔为给定进程 ID 触发定期快照

语法

wpr -enableperiodicsnapshot <snapshot option> <interval (in seconds)> <pid 1> [pid 2] ... [up to pid 8]

注意

在调用“SingleSnapshot”之前，需要为进程 ID（或名称）启用快照功能。

例如：wpr -enableperiodicsnapshot heap 60 <pid for foo.exe>

有关详细信息，请参阅 SnapshotConfig 命令。

下表描述了可应用于此选项的可用开关。

开关	说明
<快照选项>	指定快照选项类型之一。
<interval>	指定间隔（以秒为单位）。请注意，最小有效间隔为 5。
pid<>	指定进程 ID。

DisablePeriodicSnapshot

DisablePeriodicSnapshot 选项为“enableperiodicsnapshot”选项指定的所有进程禁用定期快照。

语法

wpr -disableperiodicsnapshot <snapshot option>

示例

wpr -disableperiodicsnapshot heap

下表描述了可应用于此选项的可用开关。

开关	说明
<快照选项>	指定快照选项类型之一。

PMCSources

PMCSources 选项查询系统上的 PMU (性能监视单元) 事件的列表及其计数器溢出的默认间隔值。间隔是事件数。

语法

wpr -pmcsources

注意

性能监视器单元事件用于衡量 CPU 性能并了解工作负载 CPU 特征。 Arm/intel 参考文档中只有一部分 PMU 事件在 Windows HAL 中实现。 Intel CPU 设备上此选项的示例输出如下：

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

PMCSessions 选项使用硬件计数器查询会话列表。此选项仅适用于 Windows 11 或更高版本。

语法

wpr -pmcsessions

ProfInt

ProfInt 选项查询“分析”间隔。

语法

wpr -profint

示例

C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit>wpr -profint
Current Profile Interval = 10000 [1.0000ms]

SetProfInt

SetProfInt 选项设置 PMU 事件的采样配置文件间隔。如果省略 PMU 事件名称，则默认值为 Timer。

语法

wpr -setprofint [PMU event name] 1221...10000000

示例

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

ResetProfInt 选项将配置文件间隔重置为默认值。

语法

wpr -resetprofint [Profile Source Name]

请注意，如果未提供“[配置文件源名称]”，所有配置文件源将被重置为默认值。

Instancename

Instancename 选项指定用于唯一标识跟踪实例的名称。

此选项可应用于任何操作日志记录会话的命令，并指定用户提供的日志记录会话名称。如果省略此选项，WPR 将设置默认会话名称。

语法

wpr –{option <arguments>} -instancename <text>

注意

-instancename 必须是最后一个参数。如果使用此选项启动了日志记录会话，则所有后续命令都应使用相同的 instancename 选项。例如：

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

备注

每次 WPR 保存托管应用程序在系统上运行时捕获的跟踪时，WPR 都会将托管符号保存在跟踪文件的旁边。这个功能可以对托管应用程序进行性能分析。

生成托管符号是一项占用资源且耗时的操作。 WPR 会自动创建托管符号缓存，以加快托管符号的生成。当 WPR 需要托管符号时，首先会检查此缓存，并使用任何可用的适当符号，而不是重新生成它们。

默认的托管符号缓存位置是 C:\ProgramData\WindowsPerformanceRecorder\NGenPdbs_Cache。

WPR 参考

WPR 命令行选项

常规选项

语法

配置文件

语法

开始

语法

示例

停止

语法

合并

语法

取消

语法

状态

语法

Profiledetails

语法

ExportProfile

语法

示例

提供程序

语法

Boottrace

语法

CaptureStateOnDemand

语法

记号笔

语法

MarkerFlush (已过时)

语法

刷新

语法

HeapTracingConfig

语法

Disablepagingexecutive

语法

日志

语法

Purgecache

语法

帮助

语法

SnapshotConfig

语法

SingleSnapshot

语法

EnablePeriodicSnapshot

语法

DisablePeriodicSnapshot

语法

示例

PMCSources

语法

PMCSessions

语法

ProfInt

语法

示例

SetProfInt

语法

示例

ResetProfInt

语法

Instancename

语法

备注

相关主题

其他资源