Windows Performance Toolkit

https://learn.microsoft.com/en-us/windows-hardware/test/wpt/
Admin
The Windows Performance Toolkit consists of performance monitoring tools that produce in-depth...
Tokens:214,293
Snippets:2,217
Trust Score:10
Update:6 days ago
Show doc for...
Tokens:
Raw
### wpr -start examples

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/wpr-command-line-options

Examples of the -start option. The first starts the verbose CPU profile in memory mode. The second starts the light CPU profile in file mode. The third starts a verbose profile defined in a .wprp file.

```dos
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)
```

--------------------------------

### CaptureStateOnStart Usage Example

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/capturestateonstart-in-systemprovider

Example XML showing how to use CaptureStateOnStart within a SystemProvider element to trigger rundown of the Pool keyword at trace start.

```XML
    <SystemProvider Id="SystemProvider_CaptureStateOnDemand">
        <Keywords>
            <Keyword Value="MemoryInfo" />
        </Keywords>
        <CaptureStateOnStart>
            <Keyword Value="Pool" RundownFlag="Start"/>
        </CaptureStateOnStart>
    </SystemProvider>
</SystemProvider>
```

--------------------------------

### wpr -instancename example workflow

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/wpr-command-line-options

Example showing how to start, check status, and stop a tracing session using the same instancename. Omitting the instancename on stop fails with error 0xc5583000.

```text
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

```

--------------------------------

### CaptureStateOnStart Usage Example

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/capturestateonstart

Example of using CaptureStateOnStart within an EventProvider element, showing how to specify keywords for tracing start, along with CaptureStateOnSave.

```XML
<EventProvider Id="sample-provider" Name="SampleProvider" NonPagedMemory="true" Level="5">
  <Keywords>
    <Keyword Value="0x98"/> <!-- Provider is enabled with these keywords throughout tracing session -->
  </Keywords>
  <CaptureStateOnStart>
    <Keyword Value="0xff4"/> <!-- Provider is  enabled with these keywords when tracing is started. -->
  </CaptureStateOnStart>
  <CaptureStateOnSave>
    <Keyword Value="0x118"/> <!-- Provider is enabled with these keywords when tracing is saved. -->
  </CaptureStateOnSave>
</EventProvider>
```

--------------------------------

### Start

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/icontrolmanager

Starts a recording session.

```APIDOC
## Start

### Description
Starts a recording.

### Method
Start

### Parameters
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### xperf dumper example with providers

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/dumper

Example command that runs the dumper action on trace.etl, writes output to trace.etl.csv, and specifies two provider GUIDs to filter events.

```plaintext
xperf -i trace.etl -o trace.etl.csv -a dumper -provider {315a8872-923e-4ea2-9889-33cd4754bf64} {7dd42a49-5329-4832-8dfd-43d979153a88}

```

--------------------------------

### OnOffTransitionConfiguration Example

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/onofftransitionconfiguration

Example configuration for an OnOffTransitionConfiguration element with Id, Name, Type, and child elements. This example sets PrepareSystem to true, NumberOfRuns to 3, PostBootDelay to 120, WakeupDelay to 60, and TransitionTag to Boot.

```XML
<OnOffTransitionConfiguration
  Id="OnOffTransitionConfiguration_Default_Boot"
  Name="OnOffTransitionConfiguration_Default_Boot"
  Type="On/Off - Boot">
  <PrepareSystem Value="true"/>
  <NumberOfRuns Value="3"/>
  <PostBootDelay Value="120"/>
  <WakeupDelay Value="60"/>
  <TransitionTag Value="Boot"/>
</OnOffTransitionConfiguration>
```

--------------------------------

### wpr -setprofint example output

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/wpr-command-line-options

Example commands and outputs for setting the profile interval, including with a counter name.

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

```

--------------------------------

### wpr -profint example output

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/wpr-command-line-options

Example command and output showing the current profile interval as 10000 [1.0000ms].

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

```

--------------------------------

### Open ETW trace in MXA with example path

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/optimizing-windows-devices-for-multimedia-experiences-exercise-2

Example of opening a trace file located at C:\Performance\Media\Media.etl in MXA.

```plaintext
xa -i C:\Performance\Media\Media.etl
```

--------------------------------

### Open trace file with xa.exe -i (example path)

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/optimizing-windows-devices-for-multimedia-experiences-exercise-4

Example command using a specific file path to open the AudioGlitches_ThreadsAtDispatchLevel.etl trace file in MXA.

```command line
xa.exe -i C:\Performance\Media\AudioGlitches_ThreadsAtDispatchLevel.etl
```

--------------------------------

### GetProviderNameFromGuid

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/icontrolmanager

Gets the provider name of the specified GUID.

```APIDOC
## GetProviderNameFromGuid

### Description
Gets the provider name of the specified GUID.

### Method
GetProviderNameFromGuid

### Parameters
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### GetProviderGuidFromName

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/getproviderguidfromname

Gets the provider GUID associated with the specified name.

```APIDOC
## GetProviderGuidFromName

### Description
Gets the provider GUID associated with the specified name.

### Syntax
```
HRESULT GetProviderGuidFromName
  ([out] GUID* ProviderId,
  [in] BSTR bstrProViderName)
;
```

### Parameters
- **ProviderId** (GUID*) - [out] A GUID that indicates the provider identifier.
- **bstrProViderName** (BSTR) - [in] A string that indicates the provider name.

### Return Value
The following table describes possible return values.

| Return Value | Description |
|--------------|-------------|
| E_WPRC_FAILED_TO_TRANSLATE_EVENT_PROVIDER_NAME_TO_GUID | WPR was unable to translate the event provider name to a GUID. |
| S_OK | The function successfully returned the GUID. |

### Related Topics
- IControlManager

```

--------------------------------

### SystemProvider XML Example

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/systemprovider

Example configuration for a SystemProvider with Id 'system-provider', enabling ProcessThread, Loader, and CSwitch keywords; ThreadCreate, ReadyThread, and CSwitch stacks; and pool tags matching a*, b*, c*, and d*.

```XML
<SystemProvider Id="system-provider">
  <Keywords>
    <Keyword Value="ProcessThread"/>
    <Keyword Value="Loader"/>
    <Keyword Value="CSwitch"/>
  </Keywords>
  <Stacks>
    <Stack Value="ThreadCreate"/>
    <Stack Value="ReadyThread"/>
    <Stack Value="CSwitch"/>
  </Stacks>
  <PoolTags>
    <PoolTag Value="a*"/>
    <PoolTag Value="b*"/> 
    <PoolTag Value="c*"/> 
    <PoolTag Value="d*"/> 
  </PoolTags>
</SystemProvider>

```

--------------------------------

### Start an InSequentialFile trace profile with xperf -start

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/using-xperf-profiles

Starts the perf!GeneralProfiles.InSequentialFile trace profile. If a problem occurs, an error is reported; for example, starting the same profile twice results in an error that the session is already running.

```plaintext
xperf -start perf!GeneralProfiles.InSequentialFile

```

--------------------------------

### Complete Regions of Interest XML file example

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/creating-a-regions-of-interest-file

A complete example of a Regions of Interest file that defines a simple region. It includes the required XML nodes and a Region with Start and Stop events. The version attribute in the XML declaration is optional.

```XML
<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<?Copyright (c) Microsoft Corporation. All rights reserved.?>
<InstrumentationManifest>
   <Instrumentation>
      <Regions>
         <RegionRoot Guid="{EFA7A927-BAE3-48F6-92E1-000000000000}"
                     Name="Sample Region File Root"
                     FriendlyName="Root">
            <Region Guid="{d8d639a0-cf4c-45fb-976a-000111000100}"
                    Name="FastStartup-Suspend-UserSession-Shutdown"
                    FriendlyName="User Session Shutdown">
               <Start>
                  <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="301" Version="0" />
               </Start>
               <Stop>
                  <Event Provider="{331c3b3a-2005-44c2-ac5e-77220c37d6b4}" Id="22" Version="0" />
               </Stop>
            </Region>
         </RegionRoot>
      </Regions>
   </Instrumentation>
</InstrumentationManifest>

```

--------------------------------

### HardwareCounter example with counters, events, and sampled counters

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/hardwarecounter

Complete example from the Example section of the HardwareCounter reference. Shows a HardwareCounter with Id 'PerfWorkloads', two Counters (TotalCycles and InstructionRetired), one Event (CSwitch), and one SampledCounter (CacheMisses with Interval=65536). Use as a template for enabling hardware counters in a WPR profile.

```XML
<HardwareCounter Id="PerfWorkloads">
    <Counters>
        <Counter Value="TotalCycles"/>
        <Counter Value="InstructionRetired" />
    </Counters>
    <Events>
       <Event Value="CSwitch"/>
    </Events>
    <SampledCounters>
        <SampledCounter Value="CacheMisses" Interval="65536" />
    </SampledCounters>
</HardwareCounter>

```

--------------------------------

### FileMax usage in EventCollector definition

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/filemax

Example of FileMax used in an EventCollector definition. With this autologger setup, ETW creates trace files with different names at each boot (e.g., <sessionname>.etl.0001) and keeps a maximum of five instances.

```XML
<EventCollector Id="EventCollector_MultimediaEx" Name="WPDiet MultimediaEx">
  <BufferSize Value="128"/>
  <Buffers Value="40"/>
  <MaximumFileSize Value="100" FileMode="Circular"/>
  <FileMax Value="5"/>
</EventCollector>

```

--------------------------------

### Start WPR trace with Media.wprp profile

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/optimizing-windows-devices-for-multimedia-experiences-exercise-2

Starts a WPR trace using the Media.wprp profile in file mode. Run this before reproducing the media scenario.

```plaintext
wpr -start Media.wprp -filemode
```

--------------------------------

### Xperf start command syntax

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/start

Displays the command-line syntax for Xperf logger start options holistically, covering -start, -update, -flush, -save, and -on. Use this as the full overview of all available parameters before drilling into individual options.

```plaintext
xperf [-start [LoggerName] [ProfileFileName!ProfileName|SessionName]|-update [LoggerName]|[ProfileFileName!ProfileName|SessionName]] -flush [LoggerName] -save ProfileFileName!ProfileName|SessionName merged.etl -setprofint [<n>] [cached] -seteresourcesample <n1> <n2> <n3> -setspinlocksample <n1> <n2> <n3> -pooltag <P1>+<P2>+<P3>+<P4> -on (GUID|KnownProviderName)[:Flags[:Level[<:0xnnnnnnnn|’stack|[,]sid[,]tsid’]]]
```

--------------------------------

### XML Region Definition with PayloadIdentifier Nodes

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/creating-a-regions-of-interest-file

Example region definition that uses PayloadIdentifier nodes to specify payload fields for both the starting and stopping points. Payload fields are case-sensitive and must fully match the payload value. The FieldValueRelationship attribute defaults to IsEqual if not specified.

```XML
<Region Guid="{AB719FB1-D863-4305-AE8E-F21281899A85}"
        Name="FastStartup-ConsoleSessionDisconnect"
        FriendlyName="Console Session Disconnect">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="801" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="8" />
      <PayloadIdentifier FieldName="Key" FieldValue="00000" />
   </Start>
   <Stop>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="802" Version="0" />
      <PayloadIdentifier FieldName="Event"
                         FieldValue="20"
                         FieldValueRelationship="DoesNotContain" />
   </Stop>
</Region>

```

--------------------------------

### Collect PMU events with Xperf.exe -pmc option

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/recording-pmu-events

Starts a system session that collects InstructionRetired and TotalCycles on CSWITCH events, along with another event session. The -pmc option requires counters and events, and the optional 'strict' flag is used. The example uses specific tracing flags and a GUID-based event session.

```dos
Xperf.exe -on <tracing_flags> -pmc counters events [strict]
Ex>
xperf.exe -on BASE+CSWITCH+POWER+PROC_THREAD+LOADER+MEMINFO+MEMINFO_WS -pmc InstructionRetired,TotalCycles CSWITCH strict -start PMUPerfLogger -on ca92de02-0d94-43a3-9694-d60eb94f2f7d+Microsoft-Windows-Kernel-Pep+Microsoft-Windows-Kernel-Processor-Power:0xC2:4 -BufferSize 1024 -MinBuffers 32 -MaxBuffers 512
```

--------------------------------

### Enable heap tracing for a desktop app using WPRUI.exe

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/recording-for-heap-analysis

Add a registry entry for the process to be traced using the IFEO registry key. Run this command from an elevated command prompt, replacing <process_name> with the actual process name.

```command
reg add "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ <process_name>" /v TracingFlags /t REG_DWORD /d 1 /f
```

--------------------------------

### Enable data capture when a process is started

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/enabling-heap-data-capture

Use these commands from an elevated command prompt to start the NT Kernel Logger with the Base flag, start a heap tracing session for a new process (e.g., Windows Sidebar), and then stop the session and merge traces into HeapTrace.etl. The -d HeapTrace.etl command merges traces produced in the session into the HeapTrace.etl file.

```command line
xperf -on Base -BufferSize 1024 -MinBuffers 10 -MaxBuffers 16
```

```command line
xperf -start HeapSession -heap -PidNewProcess "C:\Program Files\Windows Sidebar\sidebar.exe" -BufferSize 1024 -MinBuffers 128 -MaxBuffers 128 -stackwalk HeapAlloc+HeapRealloc
```

```command line
xperf -stop -stop HeapSession -d HeapTrace.etl
```

--------------------------------

### Parent region matching example with payload fields

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/creating-a-regions-of-interest-file

Defines a parent region with matching thread ID and payload field criteria. The child must have a payload value for 'SubscriberName' that matches the parent's 'Client' field. The parent must have a start time earlier or equal to the child and a stop time later or equal.

```XML
<Region Guid="{A75D8F5D-E8F8-40b8-B453-5CC70DEAC06F}"
        Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers"
        FriendlyName="Subscribers for Create Session">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="805" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Start>
   <Stop>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="806" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Stop>
   <Match>
      <Event TID="true">
         <Payload FieldName="SubscriberName" TargetFieldName="Client" />
      </Event>
      <Parent TID="true">
         <Payload FieldName="SubscriberName" TargetFieldName="Client" />
      </Parent>
   </Match>
</Region>
```

--------------------------------

### Region with Match node for payload field matching

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/creating-a-regions-of-interest-file

Defines a region that requires matching thread IDs and that the starting event's SubscriberName payload field matches the stopping event's Client payload field. The example uses a Match node with an Event child that has TID="true" and a Payload node with FieldName and TargetFieldName attributes.

```XML
<Region Guid="{A75D8F5D-E8F8-40b8-B453-5CCC70DEAC06F}"
        Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers"
        FriendlyName="Subscribers for Create Session">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="805" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Start>
   <Stop>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="806" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Stop>
   <Match>
      <Event TID="true">
         <Payload FieldName="SubscriberName" TargetFieldName="Client" />
      </Event>
   </Match>
</Region>

```

--------------------------------

### StartKernelTrace

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/functions-wpa

Registers and starts a kernel event tracing session.

```APIDOC
## StartKernelTrace

### Description
Registers and starts a kernel event tracing session.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Response Example
N/A
```

--------------------------------

### ControlProgressHandler (get)

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/icontrolmanager

Gets the pointer to the client-side implementation of the IControlProgressHandler interface.

```APIDOC
## ControlProgressHandler (get)

### Description
Gets the pointer to the client-side implementation of the IControlProgressHandler interface.

### Method
propget

### Parameters
#### Output Parameters
- **ppControlProgressHandler** (pointer) - Required - Pointer to the client-side implementation of the IControlProgressHandler interface.

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### TraceMergeProperties example with TraceMergeProperty

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/tracemergeproperties

Example XML defining a TraceMergeProperties element with a TraceMergeProperty child that sets DeletePreMergedTraceFiles to true and includes several CustomEvent values. This is the full example from the page.

```xml
<TraceMergeProperties>
  <TraceMergeProperty
    Id="TraceMerge_Default"
    Name="TraceMerge_Default">
    <DeletePreMergedTraceFiles
      Value="true"/>
    <CustomEvents>
      <CustomEvent
        Value="ImageId"/>
      <CustomEvent
        Value="BuildInfo"/>
      <CustomEvent
        Value="VolumeMapping"/>
      <CustomEvent
        Value="EventMetadata"/>
      <CustomEvent
        Value="PerfTrackMetadata"/>
      <CustomEvent
        Value="WinSAT"/>
      <CustomEvent
        Value="NetworkInterface"/>
    </CustomEvents>
  </TraceMergeProperty>
</TraceMergeProperties>
```
Tokens:
Raw