Edge cases around recording

Recording under rr has real constraints. Most "it didn't work" cases are one of these.

The binary must be Linux + debug info

The program runs inside a Linux Docker container, so a natively-compiled macOS/Windows binary won't execute. On a Mac, build your binary inside the same recorder image first:

bash
docker run --rm -v "$PWD":/src -w /src rr-soft:latest cargo build
npx @brett_lamy/rion record -- ./target/debug/your-crate

Build with debug info and no optimization. Line-level hit counts and DWARF source mapping only work on -g -O0 builds (Rust's dev profile, C/C++ -g -O0, Go -gcflags='all=-N -l'). Optimized/release builds inline and reorder code, so the timeline can't map instructions back to source lines. This is a feature of the recording, not a bug to "fix" with --release.

Language detection

rion guesses the language from your project: Cargo.toml → Rust, go.mod → Go, otherwise by source file extensions. If your project mixes languages or has none of those markers, pass it explicitly:

bash
npx @brett_lamy/rion record --lang cpp -- ./prog

The program has to finish

rr records to completion, then replays the whole thing. A program that never exits (a server, an infinite loop) will record forever. Give it a finite workload, or a timeout, so it terminates on its own.

Apple Silicon uses Software Counters mode

On Apple-silicon Macs there's no usable hardware PMU inside the VM, so the recorder uses the rr.soft fork in Software Counters mode (rr record -W). It's transparent, but it's why the local image is rr-soft, not stock rr. Go additionally records with --scs=minimal to avoid a clash with the Go runtime's own signal handling.

Recordings made in the cloud Playground run on real Fly.io hardware with genuine perf counters (mainline rr), so they don't need -W. Same trace format either way.

Very large executions are sampled

The linetrace is capped (≈50k entries). Past the cap it's uniformly down-sampled, keeping the sampling anchors exact — so a huge run still opens, but the per-line timeline is a representative sample rather than every single firing. Watch values are sampled at every recorded firing.

Docker must be privileged

rr needs perf_event_open and ptrace, so the container runs --privileged. If your Docker setup forbids privileged containers (some locked-down corporate setups), recording will fail at startup. rion doctor flags an unreachable or misconfigured daemon.

Ownership & tokens

  • CLI uploads are attributed to your account and appear on your

    dashboard.

  • Playground recordings are anonymous (the playground is intentionally

    unauthenticated).

  • Your API token is shown once. Minting a new one on the dashboard

    revokes the old one, so any CLI still using it will need to rion login again.

Leftover artifacts

After a successful record, rion leaves the raw bundle + trace.tar.zst in a temp dir and prints the path. It's not auto-deleted so you can grab the full trace for offline replay; delete it yourself when you're done.