Investigate puffin traces

Analyze a .puffin recording from an application instrumented with Puffin. Use the recording path supplied by the user. Or use the capture_profile_trace message if using the rerun MCP.

Setup

Requires the rerun CLI (Rerun 0.38 or later), Python 3.10 or later, and jq. The Python helpers use only the standard library. Set PUFFIN_SKILL_DIR to the absolute directory containing this SKILL.md. In Claude Code, you can use export PUFFIN_SKILL_DIR="${CLAUDE_SKILL_DIR}"; in other agents, resolve the directory from the installed skill location.

Dump the trace to a file and check scope registration:

rerun dump-puffin <path> > /tmp/puffin.json
jq '.scopes | length' /tmp/puffin.json

If no (recent enough) rerun binary is on the path but you are in a Rerun checkout, run the sub-command from source instead:

cargo run --quiet -p rerun-cli --no-default-features -- dump-puffin <path> > /tmp/puffin.json

Always dump to a file. .puffin traces can produce many MB of JSON, so query the saved JSON instead of reading it all into context.

If .scopes | length is 0, names fall back to scope#<id> and source locations are missing. Ask for a new capture that includes scope registration if names are needed for the investigation. If another capture is not feasible, proceed with dynamic data labels and explain the limits. Check the registration table after exporting: do not assume that every capture tool or version preserves it.

How traces are captured

Use the application's Puffin capture or export support to save a .puffin file. For applications serving profiling data through puffin_http, connect a compatible puffin_viewer and export the recording. The dumper uses Puffin 0.20; captures from incompatible format versions may require a matching parser.

Rerun-specific examples: