Debugging Tool Xperf

xperf

← Debugging Tools and Commands

xperf provides fast command-line inspection of ETL health, sampled profiles, process/thread inventory, and context-switch events.

Property	Details
Supported OS	Windows.
Install	Install the Windows Performance Toolkit feature from the Windows ADK.
Verify	xperf -help
Primary output	See the workflow below.

When to use it

xperf is useful for quick trace statistics, sampled-profile summaries, process information, and context-switch exports.

Official action reference: https://learn.microsoft.com/windows-hardware/test/wpt/xperf-actions

Trace health / event inventory

xperf -i .\xemu-lag.etl -a tracestats

Use this to inspect the trace/event inventory and help confirm whether expected event classes were captured.

Sampled CPU profile

xperf -i .\xemu-lag.etl -a profile -detail

Restrict to a measurement interval, where the range is in microseconds relative to the trace timeline:

xperf -i .\xemu-lag.etl -a profile -detail -range 21796062 41805107

Read the output

-detail groups profile samples by process/module, or by decoded function when symbol decoding is available.

Important trap from our investigations: Usage% in the profile report can use all logical CPUs as its denominator. It is not necessarily “percent of one xemu thread.”

Use the profile to identify hot regions, then move to thread-bounded analysis rather than treating a system-wide percentage as the final result.

Context switches

xperf -i .\xemu-lag.etl -a cswitch -range 21796062 41805107

Initial cswitch output is system-wide. It does not automatically isolate PFIFO or distinguish its waiting time from scheduling delay.

Process/thread inventory

xperf -i .\xemu-lag.etl -a process

Use PID/TID identity from the trace rather than assuming the same PID from a different run.

Unsupported action does not mean missing events

On the WPT version used in one investigation, xperf -a gpu was rejected as an unsupported action. That did not prove the ETL lacked GPU events; GPU data was later extracted with WPAExporter.

Separate “this CLI action is unavailable” from “the trace contains no data.”

---

Boundaries and common mistakes

Treat xperf as an interrogation tool, not an automatic causal analyzer. Initial output can be system-wide; apply the correct PID/TID and interval.

An unsupported xperf action does not prove the ETL lacks that event class. Use WPA/WPAExporter when xperf cannot decode a captured provider.

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

• Xperf command-line reference
• Xperf actions

Related xemu guides

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