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

```

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

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

```

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

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

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

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

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

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

```

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

### Start file-based trace profile (perf!RegistryProfiles.InSequentialFile)

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

Starts a file-based trace profile that writes trace data to a sequential file.

```bash
xperf -start perf!RegistryProfiles.InSequentialFile
```

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

### 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 memory-based trace profile (perf!GeneralProfiles.InBuffer)

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

Starts an in-memory repeated snapshots trace profile. Use this before running a scenario to capture.

```bash
xperf -start perf!GeneralProfiles.InBuffer
```

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

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

```

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

### Start trace profile with MaxBuffers override using xperf -start

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

Starts the InSequentialFile trace profile, overriding the _MaxBuffers_ values for all ETW sessions to 256 at start time. If a problem occurs, an error is reported.

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

```

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

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

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

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

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

### 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’]]]
```

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

### Stack-walking flag file example

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

Example contents of a stack-walking flag file. Flags can be separated by spaces, plus signs, or new lines.

```text
ThreadCreate ProcessCreate
DiskReadInit+DiskWriteInit+DiskFlushInit
CSwitch

```

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

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

```

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

### Start heap snapshot tracing with wpr

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/record-heap-snapshot

Starts tracing with the heapsnapshot profile in file mode. If the -name option was used to enable the heap snapshot, launch the process after the configuration is enabled.

```bash
wpr -start heapsnapshot -filemode                          

```

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

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

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

### Start Xperf CLR runtime session

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/using-clr-40-ngen-pdb-support

Start the CLR runtime session recording with specific buffer settings.

```cmd
xperf -start ClrSession -on ClrAll:0x98:5 -f clr.etl -buffersize 128 -minbuffers 256 -maxbuffers 512
```

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

### NumberOfRuns Example Configuration

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

Example XML configuration for an OnOffTransitionConfiguration element that includes NumberOfRuns set to 3, along with other transition settings.

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

```

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

### Example Profile with SystemProviderId

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

Example profile definition that includes a SystemProviderId element within a SystemCollectorId. The Value attribute is set to "system-provider".

```XML
<Profile
  Id="Example.Light.File"
  Name="Example"
  DetailLevel="Light"
  LoggingMode="File"
  Description="Example profile">
  <ProblemCategories> 
    <ProblemCategory
      Value="First Level Triage"/>
  </ProblemCategories> 
  <Collectors>
    <SystemCollectorId
      Value="WPRSystemCollector">
      <SystemProviderId
        Value="system-provider"/>
    </SystemCollectorId>
…
  </Collectors>
</Profile>
```

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

### Enable data capture on an existing process

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 an existing process (substitute the actual process ID for XXX), and then stop the session and merge traces into heapTrace.etl.

```command line
xperf -on BASE
```

```command line
xperf -start HeapSession -heap -Pid XXX -BufferSize 1024 -MinBuffers 128 -MaxBuffers 128 -stackwalk HeapAlloc+HeapRealloc
```

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

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

### PMCSources example output

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

Example output of the PMCSources option on an Intel CPU device, showing the list of PMU events with their IDs, names, intervals, and min/max values.

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

```

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

### Start Xperf kernel session

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/using-clr-40-ngen-pdb-support

Initiate the kernel session for Xperf recording.

```cmd
xperf -on Base -stackwalk Profile -f kernel.etl
```

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

### Example profile with HardwareCounterId

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

Example XML snippet from a profile definition showing the HardwareCounterId element used within a SystemCollectorId, with Value="PerfWorkloads".

```XML
<Profile Id="Example.Light.File" Name="Example" DetailLevel="Light" LoggingMode="File" Description="Example profile">
  <Collectors>
    <SystemCollectorId Value="WPRSystemCollector">
      <SystemProviderId Value="system-provider"/>
      <HardwareCounterId Value="PerfWorkloads"/>
    </SystemCollectorId>
…
  </Collectors>
</Profile>
```

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

### Profile definition example

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

Example profile definition that combines Name, DetailLevel, and LoggingMode into the Id attribute (Example.Light.File). It includes a ProblemCategories element and Collectors with system and event collector IDs.

```xml
<Profile
  Id="Example.Light.File"
  Name="Example"
  DetailLevel="Light"
  LoggingMode="File"
  Description="Example profile">
  <ProblemCategories>
    <ProblemCategory
      Value="First Level Triage"/>
  </ProblemCategories>
  <Collectors>
    <SystemCollectorId
      Value="WPRSystemCollector">
    <SystemProviderId
      Value="system-provider"/>
    </SystemCollectorId>
    <EventCollectorId
      Value="WPREventCollector">
      <EventProviders>
        <EventProviderId
          Value="Win32K-provider"/>
        <EventProviderId
          Value="Search-Core-provider"/>
      </EventProviders>
    </EventCollectorId>
  </Collectors>
</Profile>

```

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

### Example WPA MCP output: root cause call stack

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

This is an example output from WPA MCP showing the call stack that leads to the UI thread blocking. It illustrates that everything runs synchronously on the UI thread inside a single button-click handler.

```text
Program.Main
  -> WinForms message loop (Application.Run)
    -> Form1.button1_Click
      -> Form1.ExecuteWMICall   <- blocks the UI thread three ways

```

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

### xperf -merge example

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

Example of merging individual trace files into merged.etl. The merge adds image identification and event manifest information required for safe symbol decoding.

```plaintext
-merge trace1.etl trace2.etl … merged.etl

```

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

### Start Xperf session with -pmcprofile for InstructionRetired

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

Starts a system session using Xperf.exe that samples on the InstructionRetired PMU event. The -pmcprofile option enables PMC sampling, and -stackwalk pmcinterrupt captures stack walks on PMC interrupts. The command includes the required providers: proc_thread, loader, cswitch, dpc, interrupt, and pmc_profile.

```dos
xperf -on proc_thread+loader+cswitch+dpc+interrupt+pmc_profile -pmcprofile instructionretired -stackwalk pmcinterrupt

```

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

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

```

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

### System Provider Definition XML Example

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/2-system-and-event-provider-definitions

Shows the XML structure for a system provider definition. The only mandatory attribute is Id. Inner XML tags specify keywords, stacks, and pool tags to enable. This example enables 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>
```

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

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

```

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

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

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

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

```

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

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

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

### Xperf boot action command syntax

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

Command-line syntax for the Xperf boot action. Use this to generate an XML report summarizing boot metrics. Options include -minCPUToShow (range 0-100), -maxFilesToShow, -expectedProcessesFile (text file with expected process names), -minIntervalToShow (default 10 microseconds), and -userShellExecutable (default Explorer.exe).

```plaintext
-a boot [-minCPUToShow <n>] [-maxFilesToShow <n>] [-expectedProcessesFile <file name>] [-minIntervalToShow <n>] [-userShellExecutable]
```

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

### TemporaryTraceDirectory (get)

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

Gets the path of the directory where the pre-merged trace files are logged.

```APIDOC
## TemporaryTraceDirectory (get)

### Description
Gets the path of the directory where the pre-merged trace files are logged.

### Method
propget

### Parameters
#### Output Parameters
- **pbstrTemporaryTraceDirectory** (BSTR) - Required - Pointer to the path of the directory where the pre-merged trace files are logged. The default is the %temp% folder.

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

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

### DisablePeriodicSnapshot example

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

Example of using the DisablePeriodicSnapshot option with the heap snapshot type.

```plaintext
wpr -disableperiodicsnapshot heap

```

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

### Define Event Providers in XML

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

Example showing the definition of two event providers with optional keyword configurations.

```xml
<EventProvider
  Id="Win32K-provider"
  Name="Microsoft-Windows-Win32K"
  NonPagedMemory="true"
  Stack="true"> 
  <Keywords>
    <Keyword
      Value="0x240000"/>
  </Keywords>
</EventProvider>

<EventProvider
  Id="Search-Core-provider"
  Name="Microsoft-Windows-Search-Core"/>
```

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

### View buffer size and number of buffers for a profile using wpr -profiledetails

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

Use the WPR command-line interface to view the size and number of buffers that each provider uses. The example shows the output for the CPU profile.

```shell
wpr -profiledetails CPU

Microsoft Windows Performance Recorder Version 6.2.9200


Profile                 : CPU.Verbose.Memory


Collector Name          : NT Kernel Logger
Buffer Size (KB)        : 1024
Number of Buffers       : 613

```

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

### Define a container region

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

Defines a container region that contains other regions. The container starts when the first contained region starts and stops when the last contained region stops. The container region has no start or stop nodes.

```XML
<Region Guid="{A75D8F5D-E8F8-40b8-B453-5CC70DEAC06F}"
   Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers"
   FriendlyName="Subscribers for Create Session">
   <Region Guid="{93783B2C-A67F-49cb-89BC-BF305D7E2CEA}"
           Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers-Child"
           FriendlyName="Child of Subscribers for Create Session">
      <Start>
         <Region RegionGuid="{5E81D74C-0CCC-43f9-8119-953F827BCD12}" />
      </Start>
      <Stop>
         <Region RegionGuid="{7D6BA3F6-BC04-4776-8A7F-93CF7F4E2B6D}" 
                 Endpoint="Stop" />
      </Stop>
   </Region>
</Region>
```

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

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

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

Enable heap tracking by setting the IFEO registry, start the tracing session, test the scenario, stop the session, and disable heap tracking. Replace <process_name> and <file_name> with appropriate values.

```command
wpr.exe -HeapTracingConfig <process_name> enable
```

```command
wpr.exe -start Heap [-filemode]
```

```command
wpr.exe -stop <file_name>
```

```command
wpr.exe -HeapTracingConfig <process_name> disable
```

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

### TraceMergeTextHandler (get)

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

Gets the pointer to the text and some other merge time information in the trace injected by the ITraceMergeTextHandler interface.

```APIDOC
## TraceMergeTextHandler (get)

### Description
Gets the pointer to the text and some other merge time information in the trace injected by the ITraceMergeTextHandler interface.

### Method
propget

### Parameters
#### Output Parameters
- **ppTraceMergeTextHandler** (pointer) - Required - Pointer to the text and some other merge time information in the trace injected by the ITraceMergeTextHandler interface.

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

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

### Example output of wpr -status

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

Example output of the wpr -status command when a recording is active and no arguments are used.

```plaintext
WPR recording is in progress...

Time since start        : 00:04:27

Dropped event           : 0

Logging mode            : Memory

```

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

### wpr -snapshotconfig with image names

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

Examples of querying, enabling, and disabling heap snapshot configuration for a process by image name (Win32Project1.exe). The comments indicate the action for each command.

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

```

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

### Start Xperf CLR rundown session

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/using-clr-40-ngen-pdb-support

Start the CLR rundown session to capture necessary metadata for managed code.

```cmd
xperf -start ClrRundownSession -on ClrAll:0x118:5+a669021c-c450-4609-a035-5af59af4df18:0x118:5 -f clr_DCend.etl -buffersize 128 -minbuffers 256 -maxbuffers 512
```

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

### wpr -start syntax

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

Starts a recording using one or more profiles. Supports up to 64 profiles on a single command line. The -shutdown switch persists session info and recordings over reboot, but only works with file mode; KSR works only with memory mode. -filemode records to an unbounded file (default is memory).

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

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

### CaptureStateOnDemand Example

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

Example usage of CaptureStateOnDemand within a SystemProvider element, showing a Keyword with RundownFlag="Stop".

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

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

### xperf -providers command syntax

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

Displays available providers and groups. Options include Installed (I), Registered (R), KernelFlags (KF), KernelGroups (KG), and Kernel (K), which is a shortcut for 'KF KG'. If no options are specified, all providers are included.

```plaintext
xperf -providers [Installed|I] [Registered|R] [KernelFlags|KF] [KernelGroups|KG] [Kernel|K]

```

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

### EventProviderId Example

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

Example of an EventProviderId used within an EventCollectorId for managed scenarios. It defines an event provider identifier and an event provider.

```XML
<EventCollectorId Value ="WPAEventCollector">
  <EventProviders>
    <EventProviderId Value="EventProvider_DotNetProvider" />
    <EventProvider Name="Microsoft-Windows-WPA" Id="Microsoft-Windows-WPA" Stack="true">
    </EventProvider>
  </EventProviders>
</EventCollectorId>
```

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

### EventProviders Example for Managed Scenarios

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

Example of an EventProviders definition within an EventCollectorId for managed scenarios, using EventProviderId and EventProvider elements.

```XML
<EventCollectorId Value ="WPAEventCollector">
  <EventProviders>
    <EventProviderId Value="EventProvider_DotNetProvider" />
    <EventProvider Name="Microsoft-Windows-WPA" Id="Microsoft-Windows-WPA" Stack="true">
    </EventProvider>
  </EventProviders>
</EventCollectorId>

```

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

### heap command syntax

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

Shows the full command-line syntax for the heap action, including all options. Use with the -o option to specify the output file. Options include -pid, -stacks, -frames, -images, -range, -lifetime, -size, -cullframes, -requireframes, -cullLists, -top, and -totals.

```plaintext
-a heap [-pid <processId>] [-stacks] [-frames] [-images] [-range T1 T2] [-lifetime T1 T2] [-size S1 S2] [-cullframes Frame1 Frame2 ... FrameN] [-requireframes Frame1 Frame2 ... FrameN] [-cullLists cullfuncs.txt] [-top <n>] [-totals]

```

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

### Collect and process spinlock data with xperf

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

Xperf command examples for collecting and processing spinlock data. Use '-on PROC_THREAD+LOADER+SPINLOCK' to include symbols, or only 'SPINLOCK' (but then symbol information is unavailable for decoding). After collecting an ETL file, process it with '-i example.etl -symbols -o example.txt -a spinlock' to produce a spinlock report.

```console
xperf -on PROC_THREAD+LOADER+SPINLOCK

```

```console
xperf -on SPINLOCK

```

```console
xperf -i example.etl -symbols -o example.txt -a spinlock

```

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

### CustomEvents Usage Example in TraceMergeProperty

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

Example of using CustomEvents within a TraceMergeProperty to specify custom events such as ImageId, BuildInfo, and WinSAT.

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

```

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

### List all built-in Xperf profiles

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

Run this command to display all built-in Xperf profiles.

```bash
xperf -profiles
```

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

### Example output for wpr -status collectors

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

Example output for the collectors argument of wpr -status, listing collector information and any lost buffers.

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

```

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

### Example output for wpr -status profiles

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

Example output for the profiles argument of wpr -status, listing each profile used in the current recording.

```plaintext
Recording system activity using the following set of profiles:
Profile                 : CPU.Verbose.Memory

```

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

### HypervisorEventCollector example with BufferSize and BuffersPerCPU

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

Defines a HypervisorEventCollector with 4 buffers per CPU of 128 KB each. If there are 16 CPUs, total buffers would be 64.

```xml
<HypervisorEventCollector
  Id="WPREventCollector"
  Name="WPR Event Collector"> 
  <BufferSize
    Value="128"/> 
  <BuffersPerCPU
    Value="4"/>
</EventCollector>
```

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

### EventNameFilters Configuration Example

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

An example of an EventProvider configured with EventNameFilters to include specific events named Preset1 and Preset2 with a defined level and keyword.

```xml
    <EventProvider Id="EventProvider_TraceLogGen" Name="3970F9cf-2c0c-4f11-b1cc-e3a1e9958833">
      <EventNameFilters FilterIn="true" Level="5">
        <Keyword Value="0x10000000000000"/>
        <EventName Value="Preset1"/>
        <EventName Value="Preset2"/>
      </EventNameFilters>
    </EventProvider>
```

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

### bootprefetch command syntax

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

Shows the command-line syntax for bootprefetch. If no report type is selected, the default is to show the summary.

```plaintext
bootprefetch [-summary | -events [-pattern [-type name]] [-range T1 T2] | disktime]
```

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

### prefetch command syntax

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

Command-line syntax for the prefetch Xperf action. Use -summary to display prefetch scenarios, -timeunit to set time units (ns, us, ms, s) and optional precision, and -min to show only timings longer than or equal to the specified duration in microseconds.

```plaintext
-a prefetch [-summary] [-timeunit <unit> [<precision>]] [-min <duration>]

```

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

### Example1.wprp: Two profile definitions (Verbose.File and Verbose.Memory)

Source: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/3-profile-definitions

Shows a .wprp file with two profile definitions for the same Name attribute, covering Verbose detail level in both File and Memory logging modes. The ellipsis (...) represents the body of each profile.

```xml
<Profile
  Id="Example1.Verbose.File"
  Name="Example1"
  DetailLevel="Verbose"
  LoggingMode="File"
  Description="Example1 profile">
…
</Profile>
<Profile
  Id="Example1.Verbose.Memory"
  Name="Example1"
  DetailLevel="Verbose"
  LoggingMode="Memory"
  Description="Example1 profile">
…
</Profile>
```

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

### CaptureStateOnDemand Usage Example

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

Example of using CaptureStateOnDemand within an EventProvider to define keywords for on-demand state capture when the user runs wpr -capturestateondemand.

```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>
  <CaptureStateOnDemand>
    <Keyword Value="0xff4"/> <!-- Provider is  enabled with these keywords when user initiates wpr -capturestateondemand command. -->
  </CaptureStateOnDemand>
</EventProvider>
```