Expand description
rpprof is a modern CPU, wall-clock, and heap profiler for Rust programs.
It provides low-overhead, async-signal-safe profiling designed for both production services and local benchmarking.
§Features & Highlights
- Zero-Configuration Unwinding: Fast, allocation-free DWARF stack unwinding via
framehopenabled by default—no-Cforce-frame-pointers=yesor special compiler flags required. - CPU & Wall-Clock Profiling: Choose between CPU time (
ClockType::Cpu) and real wall-clock time (ClockType::Wall) to capture both compute bottlenecks and off-CPU latency (async I/O, database queries, lock contention). - Sampled Heap Profiling:
alloc::AllocProfilerwraps your global allocator to track live in-use memory and cumulative allocation churn with<1%overhead. - Multiple Output Formats: Export directly to SVG flamegraphs (
Report::flamegraph), Speedscope JSON (Report::write_speedscope), raw folded stacks (Report::write_folded), and Google pprof protobuf (Report::pprof).
§Quick Start: One-Liner CPU Profiling
use std::time::Duration;
use std::fs::File;
// Profile CPU for 10 seconds
let report = rpprof::profile(Duration::from_secs(10)).unwrap();
// Save an interactive SVG flamegraph
let file = File::create("flamegraph.svg").unwrap();
report.flamegraph(file).unwrap();§Guard-Based Profiling
For scoped profiling over specific operations or custom configurations:
let guard = rpprof::ProfilerGuardBuilder::default()
.frequency(100)
.blocklist(&["libc", "libgcc", "pthread", "vdso"])
.build()
.unwrap();
// Run workload...
if let Ok(report) = guard.report().build() {
println!("Total samples: {}", report.total_samples());
println!("Missed ticks: {}", guard.missed_samples());
// Write folded stacks
let mut output = Vec::new();
report.write_folded(&mut output).unwrap();
};§Wall-Clock (Off-CPU) Profiling
To capture time spent waiting on async tasks, I/O, locks, or network calls:
let guard = rpprof::ProfilerGuardBuilder::default()
.frequency(100)
.clock_type(rpprof::ClockType::Wall)
.build()
.unwrap();§Sampled Heap / Memory Profiling
Configure alloc::AllocProfiler as your #[global_allocator]:
use std::fs::File;
#[global_allocator]
static ALLOC: rpprof::alloc::AllocProfiler = rpprof::alloc::AllocProfiler::system();
fn main() {
rpprof::alloc::start();
// Run allocation-heavy workload...
let heap = rpprof::alloc::heap_report().unwrap();
let inuse_report = heap.to_inuse_report();
let mut flame = File::create("heap_inuse.svg").unwrap();
inuse_report.flamegraph(&mut flame).unwrap();
rpprof::alloc::stop();
}Modules§
- alloc
- criterion
- flamegraph
- Tools for producing flame graphs from folded stack traces.
- protos
Structs§
- Collector
- Frames
- A representation of a backtrace.
thread_nameandthread_idwas got frompthread_getname_npandpthread_self. frames is a vector of symbols. - Hash
Counter - Profiler
Guard - RAII structure used to stop profiling when dropped. It is the only interface to access profiler.
- Profiler
Guard Builder - Report
- The final presentation of a report which is actually an
HashMapfromFramesto isize (count). - Report
Builder - A builder of
ReportandUnresolvedReport. It builds report from a runningProfiler. - Symbol
- Symbol is a representation of a function symbol. It contains name and addr of it. If built with debug message, it can also provide line number and filename. The name in it is not demangled.
- Unresolved
Report - The presentation of an unsymbolicated report which is actually an
HashMapfromUnresolvedFramesto isize (count).
Enums§
Constants§
- MAX_
DEPTH - Define the MAX supported stack depth. TODO: make this variable mutable.
- MAX_
THREAD_ NAME - Define the MAX supported thread name length. TODO: make this variable mutable.
Functions§
- profile
- Collects a CPU profile at 99Hz for the specified duration and returns the resulting report.
- profile_
wall - Collects a real Wall-clock profile at 99Hz for the specified duration.
- profile_
with_ frequency - Collects a CPU profile with a custom frequency in Hz for the specified duration.
- validate