rpprof
rpprof is a CPU and memory profiler for Rust programs. It is a fork of tikv/pprof-rs, created to apply needed dependency updates and bug fixes after upstream development remained stale for nearly a year.
rpprof refreshes dependency trees to address known advisories, fixes signal handling and unwinding edge cases, and adds observability for dropped samples.
Key Changes and Improvements
- Dependency and Security Updates: Refreshed dependency trees to resolve security advisories flagged by
cargo-deny(includingmemmap2,quick-xml,anyhow,bytes,rand,adler, andcrossbeam-epoch). - Zero-Configuration Unwinding:
framehop-unwinderis enabled by default. Uses zero-copymmap-backed DWARF unwind tables and a 64-slot concurrent unwind cache for fast, allocation-free, async-signal-safe stack unwinding—no-Cforce-frame-pointers=yesor special release build flags required. - Sharded Concurrent Signal Collector: Unwinds concurrently across CPU cores under a shared read lock with a 16-shard collector and per-unwind page-cached stack validation, minimizing dropped ticks on high-core-count servers.
- Sampled Heap / Memory Profiling: Built-in
rpprof::alloc::AllocProfiler(GlobalAllocwrapper) with Poisson-sampled allocation tracking (512 KiB default rate), capturing both live in-use memory and cumulative allocation flamegraphs with <1% overhead. - CPU & Wall-Clock Profiling: Added
ClockTypesupporting both on-CPU profiling (ITIMER_PROF/SIGPROF) and real Wall-clock profiling (ITIMER_REAL/SIGALRM) for off-CPU / I/O latency bottlenecks. - Direct Folded Stack & Speedscope Export: Native
report.write_folded(&mut writer)andreport.write_speedscope(&mut writer, name)methods for direct compatibility with Speedscope and Brendan Gregg scripts. - One-Liner Profiling Helpers:
rpprof::profile(duration)andrpprof::profile_wall(duration)for effortless profiling in integration tests, CLI tools, and HTTP endpoints. - Allocation-Free Iterator & Bounded-Memory Report Building: Streams temporary spill files in 256 KiB chunks, pre-aggregates raw stacks before symbolization, memoizes
PC -> Arc<[Symbol]>per build, and supports directguard.report().build_pprof()export without materializing an intermediateReport. - Bounded
/tmpSpill Storage: OptionalProfilerGuardBuilder::max_spill_bytes()/max_spill_entries()caps temporary spill usage (including0for strictly in-memory capture) and tracks dropped spill samples viaguard.dropped_spill_samples(). - Thread Name Capture & Filtering: Fixed macOS and musl thread name detection, and added
thread_blocklistfor async-signal-safe thread filtering by name. - Missed Sample Observability: Built-in atomic counter (
guard.missed_samples()/Profiler::missed_samples()) tracking sampling ticks dropped due to lock contention in the signal handler. Missed sample counts are also embedded in generated pprof protobuf profiles. - Stray SIGPROF Protection: Sets
SIG_IGNwhen unregistering the signal handler if the previous disposition was default, preventing trailing timer signals from aborting the process. - macOS Context Alignment: Safe unaligned reads of
ucontext_tfields in signal handlers to prevent debug assertions on macOS. - Async-Signal-Safe Address Validation: Uses direct
libcsystem calls inaddr_validatewithout creating temporary slice references or relying on higher-level file descriptor abstractions. - Modern Ecosystem Support: Compatible with Rust 2024 Edition, with updated dependency ranges across
nix,prost,object,inferno, andcriterion. - Dual Licensed: MIT OR Apache-2.0.
Usage
Add rpprof to your Cargo.toml (all unwinding, flamegraph, and protobuf features work out-of-the-box):
[]
= "0.18"
Quick One-Liner CPU Profiling
use File;
use Duration;
Sampled Heap / Memory Profiling
Wrap your global allocator with AllocProfiler to enable low-overhead, Poisson-sampled heap profiling:
use File;
static ALLOC: AllocProfiler = system;
Basic CPU Profiler Guard
use File;
Wall-Clock (Off-CPU) Profiling
To profile wall-clock time (identifying threads blocked on async I/O, database queries, mutex contention, or network requests) instead of only on-CPU time:
let guard = default
.frequency
.clock_type
.build
.unwrap;
Folded Stacks & Speedscope Export
Export raw folded stack traces (usable with FlameGraph perl scripts, differential flame graphs, or speedscope):
if let Ok = guard.report.build
Features
| Feature | Description |
|---|---|
cpp (default) |
Enables C++ symbol demangling via symbolic-demangle. |
flamegraph |
Enables SVG flamegraph generation via inferno. |
prost-codec |
Enables Google pprof protobuf profile format generation via prost. |
protobuf-codec |
Enables Google pprof protobuf profile format generation via protobuf crate. |
framehop-unwinder |
Stack unwinding using framehop (fast, allocation-free unwinding). |
frame-pointer |
Stack unwinding using frame pointers (requires building std with frame pointers). |
criterion |
Custom profiler integration for criterion benchmarks. |
perfmaps |
Support for /tmp/perf-<pid>.map symbol resolution. |
Generating Flamegraphs
With the flamegraph feature enabled:
if let Ok = guard.report.build
Custom options (e.g. image width):
if let Ok = guard.report.build
Google pprof Protobuf Output
With prost-codec enabled, rpprof outputs standard profile.proto protobuf profiles. Use build_pprof() to emit protos::Profile directly without allocating an intermediate Report (or report.pprof() if you also export other formats from the same Report):
use File;
use Write;
use Message;
if let Ok = guard.report.build_pprof
You can then visualize or analyze the profile with go tool pprof:
pprof -http=:8080 profile.pb
Frame Post-Processor
Before report generation, a frames_post_processor can normalize or rewrite frame and thread names:
if let Ok = guard
.report
.frames_post_processor
.build
Criterion Integration
With the criterion and flamegraph features enabled:
use ;
use ;
criterion_group!
criterion_main!;
Minimum Supported Rust Version (MSRV)
Rust 1.88.0 (Rust 2024 Edition) or higher. Target/development toolchain is Rust 1.98.
License
This project is licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT License (LICENSE-MIT)
at your option.