Debugging Tool WPR

Windows Performance Recorder (WPR)

← Debugging Tools and Commands

WPR records Event Tracing for Windows data into an ETL file. Use it to capture CPU sampling, scheduler activity, image/process events, and optional GPU events around a bounded xemu workload.

Property	Details
Supported OS	Windows 8 or later; administrator access is commonly required for kernel collectors.
Install	Install the Windows Performance Toolkit feature from the Windows ADK. Windows also includes a command-line WPR on supported systems.
Verify	wpr -help
Primary output	See the workflow below.

When to use it

WPR is our primary capture tool on Windows. It records ETW events into an .etl trace for later inspection.

Official reference: https://learn.microsoft.com/windows-hardware/test/wpt/wpr-command-line-options

Discover available profiles

wpr -profiles

For our broad performance captures, the important classes are general CPU/scheduling data and GPU data.

Start a file-backed capture

A typical built-in-profile form is:

wpr -start GeneralProfile -start GPU -filemode

When a dedicated temporary trace directory is needed:

wpr -start GeneralProfile -start GPU -filemode -recordtempto C:\xemu-trace-temp

The exact retained Vulkan investigation used the equivalent verbose general/GPU file profiles from WPR 10.0.26100.

Check recorder state

wpr -status
wpr -status profiles
wpr -status collectors -details

Read the output

Look for:

• the expected profiles being active;
• recording duration;
• logging mode;
• dropped/lost events = 0;
• expected kernel collectors such as sampled profile/context switch data.

If buffers/events were lost, timing partitions and sample totals may be incomplete. Preserve that failure instead of silently treating the trace as clean.

Stop and save

wpr -stop C:\traces\xemu-lag.etl

Abort a bad capture

wpr -cancel

Use -cancel when setup failed before the intended measurement began. Do not turn a failed admission into a gameplay sample just because an ETL exists.

Practical capture rule

Start the recorder before the controlled workload, but analyze only the explicitly recorded measurement window. Startup and cleanup events can remain in the ETL without being included in the reported workload.

The retained Vulkan investigation, for example, contained startup/cleanup outside its 20.0090458-second analysis interval. Whole-trace totals were therefore not valid workload totals.

---

Boundaries and common mistakes

Keep captures short and file-backed. Start before the controlled action, stop promptly afterward, and report only the selected workload interval. Check recorder state and lost events before accepting the ETL.

An ETL file existing does not prove the intended profile started, the workload ran, or all events were retained.

Evidence to retain

• Tool name and exact version.
• Source commit/tree and executable SHA-256.
• The complete command or saved profile used.
• Input artifact hashes and the explicitly selected time or address range.
• Raw output plus any derived report; do not retain only a screenshot or conclusion.
• Admission failures, warnings, dropped events, incomplete rows, or unsupported operations.

Official references

• Download and install the Windows ADK
• WPR command-line options
• Windows Performance Toolkit

Related xemu guides

• Debugging Tools and Commands
• Debugging Lag and Hot Paths
• Performance Methodology