通过

WPR 命令行选项

  • 项目

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 为自动记录器/全局记录器会话配置注册表项。
-enableperiodicsnapshot 为指定的间隔和给定的进程 ID 启用“定期快照”。
-disableperiodicsnapshot 为所有进程禁用定期快照。
-singlesnapshot 为指定进程获取按需快照。

档案

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

语法

wpr -profiles [<path>]

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

Argument 说明
<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>!]<profile name>[.{light|verbose}]

每个配置文件可以定义精简版本或详细版本，也可以同时定义这两个版本。 如果未指定任何选项，则使用详细版本，除非配置文件仅包含精简版本。
-shutdown [<KSR>] 指定会话信息和记录将在重新启动后持续存在。 “关闭”选项仅适用于文件模式跟踪，而 KSR 仅适用于内存模式。 在下一次启动时调用 -stop 命令以合并跟踪。
-filemode 指定在文件模式下完成记录。 （默认模式为内存。）通过使用此选项，数据将记录到一个无界的文件中，该文件的大小可能会增大，直到填满磁盘。
-recordtempto <临时文件夹路径> 指定记录保存到的临时文件夹路径。
-onoffscenario <开/关转换类型> 指定开/关转换类型之一。 包括：“Boot”、“FastStartup”、“Shutdown”、“RebootCycle”、“Standby”或“Hibernate”。
-onoffresultspath <用于保存跟踪文件的路径> 指定用于保存跟踪文件的路径。
-onoffproblemdescription <方案的说明> 指定场景的描述。
-numiterations <开/关跟踪的迭代次数> 设置 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]

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

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

合并

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

语法

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

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

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

Cancel

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

语法

wpr -cancel

此选项不采用任何参数。

Status

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 选项一起提供，上面列出的信息会与特定于该选项的数据一起显示。 下表描述了可应用于此选项的可用参数。

参数 说明和示例输出
配置文件 此参数列出当前 WPR 记录中使用的每个配置文件。

示例：

使用以下一组配置文件记录系统活动：
Profile                 : CPU.Verbose.Memory
collectors 列出收集器信息。 如果缓冲区已丢失，则会列出这些缓冲区。

示例：

主动记录收集器：
Collector Name : NT Kernel LoggerBuffer Size (KB) : 1024Events Lost : 0System KeywordsCSwitchProcessThreadSampledProfileSystem StacksCSwitchSampledProfile


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
详细信息 列出有关每个收集器的其他信息。

Profiledetails

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

语法

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

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

开关 说明
-filemode 指定在文件模式下完成记录。 （默认模式为“memory”。）
-onoffscenario <开/关转换类型> 指定开/关转换类型之一。 包括：“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}

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

Argument 说明
-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

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

语法

wpr -marker <text> [-flush]
参数 说明
-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、-profiledetails 和 -exportprofile 命令行参数。
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 命令。

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

开关 说明
<快照选项> 指定快照选项类型之一。
<间隔> 指定间隔（以秒为单位）。 请注意，最小有效间隔为 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 事件名称，则默认值为计时器。

语法

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 参考