rpprof 0.16.2

An updated, maintained CPU and memory profiling tool for Rust programs.
Documentation

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.

Crates.io Documentation License

Key Changes and Improvements

  • Dependency and Security Updates: Refreshed dependency trees to resolve security advisories flagged by cargo-deny (including memmap2, quick-xml, anyhow, bytes, rand, adler, and crossbeam-epoch).
  • 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_IGN when 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_t fields in signal handlers to prevent debug assertions on macOS.
  • Async-Signal-Safe Address Validation: Uses direct libc system calls in addr_validate without 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, and criterion.
  • Dual Licensed: MIT OR Apache-2.0.

Usage

Add rpprof to your Cargo.toml:

[dependencies]
rpprof = { version = "0.16", features = ["flamegraph", "prost-codec"] }

Basic Profiling

use std::fs::File;

fn main() {
    let guard = rpprof::ProfilerGuardBuilder::default()
        .frequency(100)
        .blocklist(&["libc", "libgcc", "pthread", "vdso"])
        .build()
        .unwrap();

    // Your workload here...
    do_work();

    if let Ok(report) = guard.report().build() {
        println!("Missed samples: {}", guard.missed_samples());

        // Generate a flamegraph
        let file = File::create("flamegraph.svg").unwrap();
        report.flamegraph(file).unwrap();
    }
}

fn do_work() {
    // ...
}

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(report) = guard.report().build() {
    let file = std::fs::File::create("flamegraph.svg").unwrap();
    report.flamegraph(file).unwrap();
}

Custom options (e.g. image width):

if let Ok(report) = guard.report().build() {
    let file = std::fs::File::create("flamegraph.svg").unwrap();
    let mut options = rpprof::flamegraph::Options::default();
    options.image_width = Some(2500);
    report.flamegraph_with_options(file, &mut options).unwrap();
}

Google pprof Protobuf Output

With prost-codec enabled, rpprof outputs standard profile.proto protobuf profiles:

use std::fs::File;
use std::io::Write;
use rpprof::protos::Message;

if let Ok(report) = guard.report().build() {
    let mut file = File::create("profile.pb").unwrap();
    let profile = report.pprof().unwrap();

    let mut content = Vec::new();
    profile.encode(&mut content).unwrap();
    file.write_all(&content).unwrap();
}

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(report) = guard
    .report()
    .frames_post_processor(|frames| {
        if frames.thread_name.starts_with("worker-") {
            frames.thread_name = "worker".to_string();
        }
    })
    .build()
{
    let file = std::fs::File::create("flamegraph.svg").unwrap();
    report.flamegraph(file).unwrap();
}

Criterion Integration

With the criterion and flamegraph features enabled:

use criterion::{criterion_group, criterion_main, Criterion};
use rpprof::criterion::{Output, PProfProfiler};

fn bench(c: &mut Criterion) {
    c.bench_function("my_benchmark", |b| b.iter(|| {
        // benchmark code...
    }));
}

criterion_group! {
    name = benches;
    config = Criterion::default().with_profiler(PProfProfiler::new(100, Output::Flamegraph(None)));
    targets = bench
}
criterion_main!(benches);

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:

at your option.