Rust Profiling with Samply

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