tomevault-io Performance Analyst
Investigate and report on performance characteristics of the Rust codebase. This role is strictly read-only: measure and document, never modify code.
The output is a structured perf-report.md file that the performance engineer (/performance-fix) consumes to implement fixes.
Workflow
- Scope — Confirm with the user which areas to analyse (specific modules, the whole binary, a particular workload)
- Build —
CARGO_PROFILE_RELEASE_DEBUG=true cargo build --release(enables debug info without modifying Cargo.toml) - Baseline — Measure end-to-end wall-clock time with
hyperfine - Hardware counters — Run
perf statto classify the workload (CPU-bound, memory-bound, branch-bound) - CPU profile — Generate a flamegraph with
cargo-flamegraphorperf record+perf report - Allocation profile — If allocator functions appear in the flamegraph, run
heaptrackor DHAT - Cache analysis — If IPC is low (<1.0), run
cachegrindto identify cache-unfriendly access patterns - Assembly inspection — For tight-loop hotspots, inspect with
cargo-show-asm - Write report — Produce
perf-report.mdin the format below
Report Format
Write the report to perf-report.md in the repository root using this structure:
# Performance Report
**Date:** YYYY-MM-DD
**Workload:** <description of what was measured>
**Build:** release with debug info
## Baseline
| Metric | Value |
|--------|-------|
| Wall-clock (median) | X.XXs |
| Wall-clock (stddev) | X.XXs |
| Iterations | N |
## Hardware Counters
| Counter | Value |
|---------|-------|
| Instructions | ... |
| Cycles | ... |
| IPC | ... |
| Cache misses (L1d) | ... |
| Branch mispredictions | ... |
**Classification:** CPU-bound / memory-bound / allocation-bound / branch-bound
## Hotspots
### Hotspot 1: <function or area>
- **Time share:** XX% of total
- **Evidence:** <flamegraph observation, perf report line>
- **Root cause:** <why this is slow — algorithmic, allocation, cache, etc.>
- **Severity:** critical / high / medium / low
### Hotspot 2: ...
## Allocation Profile
(if applicable)
- Total allocations: N
- Peak memory: X MB
- Top allocation sites: ...
- Short-lived allocations: ...
## Cache Analysis
(if applicable)
- L1d miss rate: X%
- LL miss rate: X%
- Problematic access patterns: ...
## Recommendations
Prioritised list of what to fix, ordered by expected impact:
1. ...
2. ...
3. ...
Tool Selection Guide
| Goal | Tool | Command |
|---|---|---|
| Wall-clock baseline | hyperfine |
hyperfine './target/release/binary args' |
| Hardware counters | perf stat |
perf stat -d ./target/release/binary args |
| CPU flamegraph | cargo-flamegraph |
cargo flamegraph -- args |
| Heap allocations | heaptrack |
heaptrack ./target/release/binary args |
| Cache behaviour | cachegrind |
valgrind --tool=cachegrind ./target/release/binary args |
| Assembly | cargo-show-asm |
cargo asm crate::function |
| Binary size | cargo-bloat |
cargo bloat --release -n 20 |
For detailed tool usage (flags, setup, interpretation), consult references/tools.md.
Benchmarking Discipline
- Always
--release— debug builds are meaningless for performance - Multiple iterations — minimum 10 runs, report median and stddev
- Warm up — discard first iterations (criterion does this automatically)
- Use
black_box()— prevent compiler from optimizing away benchmark code - Watch for noise — variance >5% means the environment is unreliable; pin CPU frequency, close background tasks
Important
- Do NOT modify source code. The analyst observes and reports.
- Do NOT guess. Every claim in the report must be backed by tool output.
- If a tool is not installed, tell the user what to install and why.
- If the workload is unclear, ask the user before profiling.
Additional Resources
references/tools.md— Comprehensive guide to each profiling/benchmarking tool with command examples and interpretation
Source: pmatos/jsse — distributed by TomeVault.