rust-profiling

Profile Rust binaries to find CPU bottlenecks and allocation pressure using samply, then use OS-level memory evidence when RSS or fragmentation is the symptom.

Quick Start

# 1. Ensure profiling profile exists in Cargo.toml (see reference.md)
# 2. Build with debug symbols
cargo build --profile profiling

# 3. Profile (opens Firefox Profiler UI)
samply record ./target/profiling/<binary> [args...]

# 4. Or save for CLI analysis
samply record --save-only -o profile.json ./target/profiling/<binary>
python3 ~/.agents/skills/rust-profiling/scripts/analyze_profile.py profile.json

Skill Files

| File | Purpose | |------|---------| | reference.md | Cargo.toml setup, samply options, troubleshooting | | examples.md | Common profiling scenarios and analysis patterns | | optimization.md | Post-profiling fixes: source patterns, release-profile tuning, PGO, BOLT, what doesn't work | | scripts/analyze_profile.py | CLI tool to analyze saved profile.json files |

When to Use

• Performance is slower than expected
• RSS or heap usage grows unexpectedly under load
• Before optimizing (measure first!)
• After optimization (verify improvement)
• Investigating CPU-bound operations or allocation-heavy hot paths

When NOT to Use

• The task is a Rust correctness bug, API design question, or refactor without a performance symptom.
• The user already has a narrow benchmark request that does not need profiling guidance.
• The issue is build time, binary size, or dependency hygiene rather than runtime CPU, memory, or contention.

What to Look For

| Pattern | Meaning | Action | |---------|---------|--------| | High self-time | Function itself is slow | Direct optimization target | | High total-time | Called often or slow callees | Check call frequency | | malloc/alloc in hot path | Allocation overhead | Preallocate, reuse, pool, or use bounded/shared buffers | | RSS grows then plateaus while profiles show allocation churn | Possible allocator fragmentation, not necessarily a leak | Compare allocators, then reduce high-rate small allocations | | pthread_mutex/parking_lot | Lock contention | Reduce lock scope or use lock-free |