Contract
| Field | Bound contract |
|---|---|
| Trigger | Profiling Rust performance, reducing binary size, measuring monomorphization bloat, writing Criterion benchmarks, or interpreting flamegraphs and perf output. |
| Authority | Read-only. Emits a guidance report and command transcripts to chat. No source or remote mutation. |
| Side effect | Emits a structured guidance report with profiling commands, benchmark setup, and interpretation. No source files are modified. |
| Done | A report is emitted that names the hot path, bloat source, size contributor, or benchmark result and the next action to take. |
Inputs
- Target binary or benchmark (required): the program, test, or Criterion benchmark to measure.
- Build profile (required if not inferrable): a release profile with debug symbols (
release-with-debugorCARGO_PROFILE_RELEASE_DEBUG=true). - Profiling tool (required):
cargo-flamegraph,cargo-bloat,cargo-llvm-lines, Criterion,perf,heaptrack, orvalgrind --tool=dhat. - Optional inputs: a saved baseline for comparison, or a specific function to annotate.
Procedure
- Build for profiling. Use a release profile with
debug = trueor setCARGO_PROFILE_RELEASE_DEBUG=true. For line-level attribution with faster builds, usedebug = 1. For better call graphs, setRUSTFLAGS="-C force-frame-pointers=yes". Done when: the binary has debug symbols and frame pointers are configured as needed. - Generate a flamegraph. Run
cargo flamegraph --bin <name> -- <args>, or useperf record -gfollowed bystackcollapse-perf.plandflamegraph.pl. Look for wide top frames, unexpected standard-library and allocator frames, and thin closure frames. Done when: a flamegraph SVG identifies hot leaves. - Measure binary size with cargo-bloat. Run
cargo bloat --release -n 20,cargo bloat --release --crates, orcargo bloat --release --filter <crate>. Compare before and after with saved output. Done when: the largest size contributors are listed. - Measure monomorphization bloat with cargo-llvm-lines. Run
cargo llvm-lines --release | head -40. A highCopiescount usually means generic monomorphization; confirm by reading the function and its type parameters. Reduce it with a thin generic wrapper plus a concrete inner function. Done when: the functions with the most LLVM IR and copies are named. - Write Criterion benchmarks. Add
criteriontodev-dependencies, createbenches/<name>.rswithcriterion_group!andcriterion_main!, useblack_boxto prevent optimization, and compare with saved baselines. Done when: a benchmark file runs and produces a report. - Profile with perf on Linux. Record with
perf record -g -F 999 <binary>, report withperf reportorperf annotate, and gather quick counters withperf stat. Done when: the hot function and call graph are visible. - Profile allocations with heaptrack or DHAT. Run
heaptrack <binary>and inspect withheaptrack_print, or runvalgrind --tool=dhat <binary>and viewdhat-out.*withdh_view.html. Done when: allocation hotspots and lifetimes are identified.
Failure and recovery
| Failure class | Behavior |
|---|---|
| No debug symbols | Rebuild with debug = true or debug = 1. |
| Incomplete call graph | Set RUSTFLAGS="-C force-frame-pointers=yes" and disable ASLR with setarch $(uname -m) -R. |
| Flamegraph permission denied | Lower perf_event_paranoid to 1 or run with sudo/DTrace on macOS. |
| Benchmark results are noisy | Increase measurement_time, sample_size, and warm_up_time in Criterion. |
| Allocation profile is too large | Filter to a smaller workload or reduce profiling duration. |
Output
- A structured guidance report with the chosen tool, measured result, and interpretation.
- A recommended next action: a code change, a new benchmark, or a further profiling pass.
- Commands to reproduce the measurement.