Debugging Tool Tracy

Tracy

← Debugging Tools and Commands

Tracy is an optional frame-oriented profiler for deliberately instrumented xemu builds. It can place CPU zones, frame boundaries, locks, context switches, allocations, plots, screenshots, and supported GPU zones in one capture.

Property	Details
Supported OS	Profiler and client support vary by platform/API; this page focuses on Linux/Steam Deck investigation.
Download	Official Tracy repository and releases
Verify	Record the exact Tracy revision, build the profiler/client from that revision, and connect to a small instrumented test.
Primary output	Tracy capture file viewed in the Tracy profiler.
Current xemu status	Proposed optional diagnostic configuration; not a dependency of ordinary fork builds.

Why Tracy is optional

perf, scheduler tracing, and Perfetto can observe an ordinary optimized xemu binary. Tracy requires xemu integration and an instrumented build. That makes it valuable after system tracing identifies a broad region but cannot express emulator-specific phases.

Good candidate zones include:

guest frame / display write
vCPU guest execution
PFIFO/PGRAPH service
texture or surface synchronization
pipeline/shader preparation
Vulkan submission and present
audio frame and worker dispatch

Do not begin by zoning every helper. Each zone, plot, lock annotation, screenshot, and allocation hook has cost and can change thread timing.

Integration contract

A production-quality optional Tracy configuration should satisfy all of these:

1. Tracy client code is compiled only for an explicit profiling configuration.
2. Normal Release builds contain no active Tracy connection, zone, allocation, lock, or screenshot work.
3. Frame markers correspond to a documented xemu/guest boundary, not an arbitrary frontend present.
4. Vulkan/OpenGL GPU zones follow the renderer's actual command-buffer/context lifetime.
5. Capture metadata identifies source, executable, symbols, configuration, renderer, GPU, driver, and workload.
6. Acceptance results come from a matching uninstrumented Release build.

Before merging any integration, inspect the disabled binary or add a build-level check proving the client is absent when the profiling option is off.

Start with a narrow diagnostic build

The first useful capture needs only a few stable zones:

Frame
├─ vCPU
├─ PFIFO/PGRAPH
├─ Renderer CPU
├─ Submit/present
└─ Audio

After a slow interval is identified, add temporary child zones around the unresolved owner. This preserves readable captures and keeps the diagnostic question explicit.

Build or obtain the profiler from one exact release tag, following that release's manual rather than an unversioned third-party package recipe. Keep the Tracy client sources from the same tag in the diagnostic branch. The profiler and instrumented xemu client should report compatible protocol versions before a capture is accepted.

Use descriptive names tied to ownership rather than conclusions. wait_for_renderer is useful; bad_gpu_stall asserts a cause the trace may not prove.

Linux and Steam Deck workflow

Run the profiler UI on a workstation when possible and connect to the instrumented Deck build over the trusted test network. Record the profiler/client version and capture endpoint. Do not expose Tracy's listener on an untrusted network.

The checked Deck did not have Tracy installed. That is expected: Tracy should travel with an explicit diagnostic build/tool bundle rather than become a SteamOS system dependency.

When comparing with perf or Perfetto:

• use the same source and executable identity;
• use the same game/snapshot/cache state;
• align a guest-progress marker or explicit timestamp;
• keep the Tracy run diagnostic rather than comparing its frame time directly with an uninstrumented control.

What Tracy can and cannot establish

Tracy observation	Establishes	Does not establish
Long CPU zone	Instrumented region took longer in this run	Why it was slow without child/scheduler evidence
Lock wait	Annotated lock delayed the thread	That removing synchronization is correct
GPU zone	Submitted GPU work occupied an interval	That the CPU was blocked on it
Slow frame marker	Instrumented frame exceeded its peers	That monitor FPS or guest cadence fell identically
Allocation activity	Instrumented allocator events occurred	That allocations dominate the frame without measured cost

Boundaries and common mistakes

• Tracy is not a zero-overhead release profiler.
• Screenshots and allocation tracing can materially increase capture size and cost.
• A frame boundary must be named precisely: guest flip, display write, host present, and monitor refresh are different.
• Network collection can drop or delay data; retain warnings and capture statistics.
• Do not keep broad temporary zones after the investigation merely because they are convenient.
• Do not require Tracy for routine Steam Deck performance tests.

Evidence to retain

• Tracy revision/version and profiler/client build options;
• xemu source/executable/symbol hashes and profiling defines;
• capture file and selected frame/zone IDs;
• definition of every frame boundary and important custom zone;
• connection/drop warnings and capture size;
• a later uninstrumented Release validation result.

Official references

• Tracy repository
• Tracy manual

Related xemu guides

• Perfetto
• Linux perf
• xemu cause counters
• Performance Methodology