API tracing

wgpu-core can record an on-disk trace of every API call made against a device, then replay it later. The feature is the historical bridge between Mozilla's crash reports and the wgpu maintainers, and remains the only way to time-travel through a wgpu workload.

docs/testing.md notes that the trace capture path is currently broken and the player tests are soft-deprecated. Don't write new tests on top of it; do use it for ad-hoc debugging when you have an existing trace.

What's traced

Every method on wgpu_core::Global that mutates state is recorded into the trace directory:

• Device, queue, buffer, texture, sampler, bind-group, pipeline creation.
• Command-encoder recording, including pass setup and individual draw/dispatch calls.
• Queue submissions.
• Map / unmap operations.
• Resource destruction.

Resource state (buffer contents, shader source) is captured alongside the actions so the trace is self-contained.

Producing a trace

1. Build wgpu with the trace feature enabled (it propagates to wgpu-core and pulls in ron or bincode serde stacks).
2. Create the device with DeviceDescriptor::trace = Trace::Directory(path).
3. Run your application. The trace is appended to the directory as actions occur.

The file format is documented inline in wgpu-core/src/device/trace.rs and wgpu-core/src/device/trace/. The encoding is bincode for the action stream and a manifest file plus auxiliary blobs for resource state.

Replaying a trace

cargo run -p player -- /path/to/trace_dir

The player binary (player/src/) feeds the recorded actions back into a fresh wgpu_core::Global and reproduces the GPU work. Useful for:

• Bisecting a regression: run the same trace against multiple wgpu versions.
• Reproducing a crash report: Mozilla's process is to dump a trace from an affected user's session, then let maintainers replay it locally.
• Comparing backends: replay against Vulkan, then DX12, then Metal — same recorded behavior, different drivers.

Implementation map

Layer	Files
Trace types	wgpu-core/src/device/trace.rs (~9 KB)
Trace recording	wgpu-core/src/device/trace/
Replay	player/src/
Tests	tests/tests/wgpu_trace.rs (uses noop backend), player/tests/
Cargo features	trace and replay on wgpu-core, re-exported by wgpu

Trace tests

tests/tests/wgpu_trace.rs runs against the noop backend so it can exercise the trace recorder's serialization without a real GPU. It builds simple workloads, captures their traces, replays them, and asserts on the round-trip.

player/tests/ is the older harness — docs/testing.md calls these soft-deprecated.

What goes wrong

• Coverage gaps: every new method on Global needs a corresponding action variant in the trace recorder. Forgotten ones silently drop calls. Adding new actions is straightforward but easy to overlook.
• Resource state: capturing the contents of large buffers/textures slows the application down. The recorder tries to be lazy (only on first read) but isn't always perfect.
• Cross-backend drift: replaying a Vulkan-captured trace on DX12 may exercise different driver paths and produce slightly different results.

Useful for

• Reproducing a one-off bug from someone else's machine.
• Generating a regression test fixture (capture once, commit the trace alongside an assertion in tests/tests/wgpu_trace.rs).
• Debugging deterministic-replay issues in wgpu-core.

See also

• crates/player
• crates/wgpu-core — device/trace.rs is described under wgpu-core/src/device/.
• how-to-contribute/debugging