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 | 提供子層級說明信息的清單。 |
| -配置 檔 | 列舉配置檔中的配置檔名稱和描述。 |
| -purgecache | 清除動態符號快取。 |
| -開始 | 啟動一或多個配置檔。 |
| -標記 | 引發事件標記。 |
| -markerflush | （過時）引發事件標記並排清工作集。 |
| -地位 | 顯示使用中錄製的狀態（如果有的話）。 |
| -profiledetails | 引發事件標記並排清工作集。 |
| -exportprofile | 將內建配置檔匯出至檔案。 |
| -供應商 | 顯示提供者的詳細資訊。 |
| -cancel | 取消 WPR 起始的錄製（如果有的話）。 |
| -停 | 取消並儲存 WPR 起始的錄製內容（如果有的話）。 |
| -合併 | 將 etl 檔案合併至指定的檔案。 |
| -沖洗 | 排清 WPR 所起始的記錄會話（如果有的話）。 |
| -log | 設定儲存至事件記錄檔的偵錯資訊。 |
| -disablepagingexecutive | 變更 [ 停用分頁主管] 設定。 |
| -heaptracingconfig | 變更進程的堆積追蹤設定。 |
| -snapshotconfig | 變更進程的快照集設定。 |
| -capturestateondemand | 擷取目前錄製中已設定提供者的狀態。 |
| -pmcsources | 查詢系統上可用的 PMU 事件清單。 |
| -pmcsessions | 使用 PMU 事件查詢會話清單。 |
| -setprofint | 設定取樣的配置檔間隔。 |
| -profint | 查詢目前的配置檔間隔。 |
| -resetprofint | 還原預設配置檔間隔值。 |
| -boottrace | 設定自動記錄器/全域記錄器會話的登錄專案。 |
| -enableperiodicsnapshot | 針對指定的間隔和指定的進程標識碼啟用 定期快照 集。 |
| -disableperiodicsnapshot | 停用 所有進程的定期快照 集。 |
| -singlesnapshot | 取得指定進程的隨選快照集。 |
設定檔
[ 設定檔] 選項會列出錄製所使用的 WPR 設定檔。
語法
wpr -profiles [<path>]
下表描述您可以套用至此選項的可用自變數。 若要查看內建配置檔，請省略 自變數。
| Argument | 描述 |
|---|---|
| <path> | 指定包含設定檔定義的檔案路徑和名稱。 例如：wpr -profiles “c:\Users\User1\Documents\WPR Files\Custom Profiles\CustomProfile1.wprp” |
啟動
[ 開始] 選項會使用一或多個設定檔啟動錄製。
語法
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>]
下表描述您可以套用至此選項的可用參數。
| Switch | 描述 |
|---|---|
| <配置檔> [-start< profilen>]... | 指定內建配置檔或使用者定義配置檔的路徑。 您可以在單一指令列上指定最多 64 個設定檔，並指定每個設定檔，如下所示： <profile> ：= [<filename.wprp>！]<配置檔名稱>[.{淺|色詳細資訊}] 每個配置檔都可以定義淺色或詳細資訊版本，或兩個版本。 如果未指定這兩個選項，除非配置檔只包含淺色版本，否則會使用詳細資訊版本。 |
| -shutdown [<KSR>] | 指定工作階段資訊和錄製將會在重新啟動期間保存。 關機選項僅適用於檔案模式追蹤，因為 KSR 僅適用於記憶體模式。 在下一次開機時呼叫 -stop 命令以合併追蹤。 |
| -filemode | 指定錄製是在檔案模式中完成。 （預設模式為記憶體。）藉由使用此選項，數據會記錄到未系結的檔案，其大小可能會成長，直到它填滿磁碟為止。 |
| -recordtempto <temp 資料夾路徑> | 指定錄製的暫存資料夾路徑。 |
| -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)
停止
[ 停止 ] 選項會停止目前的錄製，並將它儲存至 自變數所指定的檔案。
語法
wpr -stop <file> <problem description> -[skipPdbGen] [-force] [-compress]
下表描述您可以套用至此選項的可用自變數。
| Argument | 描述 |
|---|---|
| <file name> | 指定 WPR 儲存錄製到的事件追蹤記錄檔 （ETL） 檔案。 此引數為必要項目。 |
| <問題描述> | 指定問題描述。 雖然這個自變數是選擇性的，但建議您使用它。 |
| -skipPdbGen | 停用 .NET 模組的 ngen 和內嵌 pdbs 動態產生。 此選項可減少停止作業時間。 |
| -force | 當目標擴展名不是 .etl 時，停用警告。 |
| -壓縮 | 壓縮輸出追蹤檔案。 |
合併
[ 合併 ] 選項會將 etl 檔案合併至指定的檔案。
語法
wpr -merge <trace files ...> <merged file> -[skipPdbGen] [-compress] [-supresspii] [-mergeonly] [-injectonly]
下表描述您可以套用至此選項的可用自變數。
| Argument | 描述 |
|---|---|
| <追蹤檔案...> | 指定一或多個未合併的事件追蹤記錄檔 （ETL） 檔案。 此引數為必要項目。 |
| <合併的檔案> | 指定 WPR 合併 ETL 檔案的輸出檔案。 |
| -skipPdbGen | 停用 .NET 模組的 ngen 和內嵌 pdbs 動態產生。 此選項可減少停止作業時間。 |
| -壓縮 | 壓縮輸出追蹤檔案。 |
| -supresspii | 隱藏個人標識號（PII） 資訊。 |
| -mergeonly | 合併追蹤，而不新增電腦特定資訊或映射標識符事件。 無法搭配 -injectonly 使用。 |
| -injectonly | 只產生機器特定的和/或映射標識符事件，而不複製合併檔案中的原始事件。 |
取消
[ 取消] 選項會取消目前的錄製，而不儲存錄製的數據。 如果目前沒有任何實例作用中，Cancel 選項會傳回錯誤。
語法
wpr -cancel
此選項不接受任何自變數。
狀態
[ 狀態] 選項會顯示目前 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 選項，上述資訊會與該選項特定的數據一起顯示。 下表描述您可以套用至此選項的可用自變數。
| Argument | 描述和範例輸出 |
|---|---|
| profiles | 此自變數會列出目前 WPR 錄製中使用的每個配置檔。
範例： 使用下列一組設定檔來記錄系統活動： |
| 收藏家 | 列出收集器資訊。 如果緩衝區已遺失，則會列出這些緩衝區。
範例： 主動錄製收集器： |
| 詳 | 列出每個收集器的其他資訊。 |
Profiledetails
[ Profiledetails ] 選項會顯示設定檔或設定檔集的詳細資訊。 若要指定多個配置檔，請使用下列語法，其中 <profilen> 參考每個配置檔的名稱。
語法
wpr -profiledetails <profile1>+<profile2>+...+<profilen> [-filemode] -onoffscenario <OnOff Transition Type>
下表描述您可以套用至此選項的可用參數。
| Switch | 描述 |
|---|---|
| -filemode | 指定錄製是在檔案模式中完成的。 （預設模式為記憶體。） |
| -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
提供者
[ 提供者] 選項會顯示提供者的詳細資訊。 提供者會參考向 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]
| Argument | 描述 |
|---|---|
| -沖洗 | 排清工作集。 相當於 -MarkerFlush。 |
MarkerFlush （過時）
MarkerFlush 選項會使用指定的文字引發事件標記，並排清工作集。 此命令在目前的 WPR 中已過時。
語法
wpr -markerflush <text>
清除
Flush 選項會將記錄會話排清至透過 WPR 起始的檔案。
語法
wpr -flush
此選項不接受任何自變數。
HeapTracingConfig
HeapTracingConfig 選項會啟用或停用特定進程或存放區的堆積追蹤。
Syntax
wpr -HeapTracingConfig <process name> [<package full name> <package relative app ID>] [{enable|disable}]
注意
- 如果省略 {enable|disable} 參數，則會顯示進程或應用程式的目前堆積追蹤組態。 例如：
wpr -HeapTracingConfig Heaptest.exe enable - 此命令不會立即啟動追蹤，而且應該在擷取堆積追蹤之前執行。 如需詳細資訊，請參閱 錄製堆積分析 。
- 追蹤完成後，請一律停用 進程的 HeapTracingConfig ，因為它可能會影響程式的效能。
Disablepagingexecutive
Disablepagingexecutive 選項會指定驅動程式和內核模式系統程式代碼是否可以分頁到磁碟。 將此選項設定為 ， 可防止分頁。 此選項會在登錄中設定 DisablePagingExecutive 的值。
Syntax
wpr -disablepagingexecutive {on | off}
注意
若要在執行 Windows 7 的 64 位系統上正確擷取事件堆疊， 應該將 disablepagingexecutive 設定為 [開啟]，而且必須在開始效能錄製之前重新啟動系統。 針對執行 Windows 7 的 32 位系統，以及執行 Windows 8 或更高版本的所有系統，您可以操作效能錄製，而不需要將 disablepagingexecutive 設定為 [開啟]。
記錄
[ 記錄] 選項會將偵錯記錄附加並設定至事件記錄檔。
語法
wpr -log {enabled | disabled | remove}
下表描述您可以套用至此選項的可用關鍵詞。
| 關鍵字 | 描述 |
|---|---|
| 「已啟用」 | 啟用對事件記錄檔的偵錯記錄 |
| 禁用 | 停用事件記錄檔的偵錯記錄 |
| remove | 從系統卸載 WPR 偵錯記錄提供者指令清單 |
Purgecache
Purgecache 選項會清除 Managed 符號快取。
語法
wpr -purgecache
此選項不接受任何自變數。
說明
使用這個選項可在 [命令提示字元] 視窗中顯示線上說明。
語法
wpr -help [start | stop | status | profiles | providers | tracing | boottrace | heap | hardwarecounter | advanced]
下表描述您可以套用至此選項的可用關鍵詞。
| 關鍵字 | 描述 |
|---|---|
| 無關鍵詞 | 顯示選項和簡短描述的清單。 若要取得特定選項的進一步協助，請使用 關鍵詞。 例如： wpr -help start 。 |
| start | 描述 –start 命令行自變數。 如需詳細資訊，請參閱 啟動。 |
| 停止 | 描述 -stop、 -merge 和 -cancel 命令行自變數。 |
| status | 描述 -status 命令行自變數。 如需詳細資訊，請參閱狀態。 |
| profiles | 描述 -profiles、-profiledetails 和 -exportprofile 命令行自變數。 |
| 提供者 | 描述 -providers 命令行自變數。 如需詳細資訊，請參閱 提供者。 |
| tracing | 描述 –marker、 -flush 和 -capturestateondemand 命令行自變數。 |
| boottrace | 描述 -addboot、 -stopboot 和 -cancelboot 命令行自變數。 |
| heap | 描述 -heaptracingconfig、-snapshotconfig、-enableperiodicsnapshot、-disableperiodicsnapshot 和 -singlesnapshot 命令行自變數。 |
| hardwarecounter | 描述 -pmcsources、-pmcsessions、-setprofint、-profint 和 -resetprofint 命令行自變數。 |
| 高深 | 描述 -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
此範例使用 snapshotconfig 命令搭配 PID：
wpr -snapshotconfig heap -pid 8048 enable //enable snapshot config
注意
如果程式與 OS 架構不相符（例如，64 位作業系統上的 win32 應用程式），請使用映像名稱選項。
下表描述您可以套用至此選項的可用參數。
| Switch | 描述 |
|---|---|
| <快照集選項> | 指定其中一個快照集選項類型。 目前只能使用堆積。 |
| -名字 | 指定進程的名稱。 這個參數不能與 -Pid 參數搭配使用。 如果這個參數用來啟用快照集，則組態會套用至指定進程名稱的所有新實例。 測試完成時，請務必將其停用。 |
| -pid | 指定程序識別碼。這個參數不能與 -name 參數搭配使用。 如果這個參數用來啟用快照集，則會立即套用設定，並在程式的存留期內套用設定。 |
SingleSnapshot
SingleSnapshot 選項會針對指定的進程標識碼觸發快照集選項>的<隨選快照集。
Syntax
wpr -SnapshotConfig <snapshot option> <pid 1> [pid 2] ... [up to pid 8]
注意
呼叫 SingleSnapshot 之前，必須先啟用進程標識碼 （或名稱） 的快照集功能。
例如：wpr -singlesnapshot heap <pid for foo.exe>
如需詳細資訊， 請參閱 SnapshotConfig 命令。
下表描述您可以套用至此選項的可用參數。
| Switch | 描述 |
|---|---|
| <快照集選項> | 指定其中一個快照集選項類型。 |
| <pid> | 指定程序識別碼。 |
EnablePeriodicSnapshot
EnablePeriodicSnapshot 選項會以指定的間隔和指定的進程標識碼觸發定期快照集
Syntax
wpr -enableperiodicsnapshot <snapshot option> <interval (in seconds)> <pid 1> [pid 2] ... [up to pid 8]
注意
呼叫 SingleSnapshot 之前，必須先啟用進程標識碼 （或名稱） 的快照集功能。
例如：wpr -enableperiodicsnapshot heap 60 <pid for foo.exe>
如需詳細資訊，請參閱 SnapshotConfig 命令。
下表描述您可以套用至此選項的可用參數。
| Switch | 描述 |
|---|---|
| <快照集選項> | 指定其中一個快照集選項類型。 |
| <interval> | 指定以秒為單位的間隔。 請注意，最小有效間隔為 5。 |
| <pid> | 指定程序識別碼。 |
DisablePeriodicSnapshot
DisablePeriodicSnapshot 選項會停用 enableperiodicsnapshot 選項所指定之所有進程的定期快照集。
語法
wpr -disableperiodicsnapshot <snapshot option>
範例
wpr -disableperiodicsnapshot heap
下表描述您可以套用至此選項的可用參數。
| Switch | 描述 |
|---|---|
| <快照集選項> | 指定其中一個快照集選項類型。 |
PMCSources
PMCSources 選項會查詢系統上的 PMU （效能監視器 Unit） 事件清單，以及計數器溢位的預設間隔值。 間隔是事件數目。
Syntax
wpr -pmcsources
注意
效能監視器 單位事件可用來測量 CPU 效能，並瞭解工作負載 CPU 特徵。 Windows HAL 中只會實作 Arm/intel 參考檔中的 PMU 事件子集。 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 會設定預設會話名稱。
Syntax
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 儲存在系統上執行 Managed 應用程式時所擷取的追蹤時，WPR 就會儲存追蹤檔案旁的 Managed 符號。 此功能可讓您對受控應用程式進行效能分析。
產生受控符號是一項資源且耗時的作業。 WPR 會自動建立受控符號快取，以加速產生受控符號。 當 WPR 需要 Managed 符號時，它會先檢查此快取，並使用任何可用且適當的符號，而不是重新產生它們。
默認受控符號快取位置為 C：\ProgramData\WindowsPerformanceRecorder\NGenPdbs_Cache。