full-stack-skills Rust Performance
Optimize from evidence. Define the user-visible metric, reproduce the workload, establish a stable baseline, profile the dominant cost, change one cause, and prove both correctness and improvement.
Scope and Routing
Use this skill for microbenchmarks, end-to-end load tests, CPU profiles, allocation and heap analysis, binary size, compile time, cache behavior, and regression budgets.
Route concurrency semantics to rust-concurrency, telemetry pipelines to rust-observability, general test architecture to rust-testing, release profiles and features to rust-cargo-build, and semantic review to rust-code-review.
Workflow
1. Define the performance contract
Record the workload, dataset, inputs, concurrency, platform, CPU and memory limits, toolchain, target, features, allocator, build profile, warm-up, cache state, and success metrics. Distinguish throughput from p50/p95/p99 latency and steady-state from startup or shutdown.
Do not optimize debug builds or synthetic inputs unless they represent the actual problem.
2. Establish a reproducible baseline
- Verify correctness before benchmarking.
- Use release-like optimization, codegen units, LTO, panic strategy, and target CPU settings intentionally.
- Isolate background load, power management, thermal throttling, and noisy shared runners.
- Record raw samples and uncertainty, not only one average.
- Compare the same commit, toolchain, dependency graph, and hardware when enforcing small regressions.
Read Benchmarking and Regression Gates.
3. Choose the measurement layer
| Question | Tool or evidence |
|---|---|
| Is a pure operation faster? | Criterion or Divan microbenchmark |
| Did instruction-level cost change? | iai-callgrind on supported systems |
| Where is CPU time spent? | samply, cargo-flamegraph, Instruments, perf, pprof |
| Where are allocations retained? | DHAT, heap profiler, allocator metrics |
| Why is the binary large? | cargo-bloat and feature inspection |
| What drives compile time? | Cargo build timings and cargo-llvm-lines |
| Does the service meet its SLO? | Representative load test plus observability |
A microbenchmark does not prove end-to-end latency, overload behavior, or memory bounds.
4. Profile before editing
Capture a profile under the failing workload. Preserve symbols and use the same optimized artifact intended for comparison. Separate on-CPU work, waiting, lock contention, I/O, allocation, page faults, and scheduler overhead. Read CPU and Latency Profiling.
5. Optimize the dominant cause
Common changes include algorithmic complexity, fewer passes, better batching, avoiding repeated parsing or allocation, borrowing instead of cloning, data-layout improvements, reduced synchronization, bounded queues, streaming, feature reduction, and moving CPU work off async workers.
Do not use unsafe, custom allocators, SIMD, lock-free structures, or caching until simpler changes are insufficient and invariants plus fallback behavior are tested.
6. Measure memory, size, and build cost
Track peak RSS, retained heap, allocation rate, fragmentation, cache growth, buffer bounds, binary sections, monomorphization, debug information, enabled features, macro expansion, and incremental versus clean compile time. Read Memory, Binary Size, and Compile Time.
7. Prove the result
Rerun correctness tests and the exact baseline protocol. Report absolute and relative results, variance, hardware and software context, tradeoffs, and regressions in secondary metrics. Add a durable benchmark or budget only when the environment can detect the intended threshold reliably.
Completion Criteria
- Define a representative workload and user-visible metric.
- Record reproducible baseline evidence before optimization.
- Profile and identify the dominant cost rather than guessing.
- Preserve correctness and safety through targeted tests.
- Re-measure under the same protocol and report uncertainty plus tradeoffs.
- Add a stable regression check or explain why the environment is too noisy.
Resources
- Benchmarking and Regression Gates
- CPU and Latency Profiling
- Memory, Binary Size, and Compile Time
- Optimization Workflow
- Execution Scenarios
examples/golden-performance/: a compiled Criterion benchmark target.
Upstream Sources
Data Privacy
This skill does not collect, store, or transmit user data. Profiles, heap dumps, command lines, symbols, and benchmark datasets may contain sensitive information; confirm storage and upload policy before sharing them.