Skip to main content

Crate rpprof

Crate rpprof 

Source
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 framehop enabled by default—no -Cforce-frame-pointers=yes or 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::AllocProfiler wraps 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_name and thread_id was got from pthread_getname_np and pthread_self. frames is a vector of symbols.
HashCounter
ProfilerGuard
RAII structure used to stop profiling when dropped. It is the only interface to access profiler.
ProfilerGuardBuilder
Report
The final presentation of a report which is actually an HashMap from Frames to isize (count).
ReportBuilder
A builder of Report and UnresolvedReport. It builds report from a running Profiler.
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.
UnresolvedReport
The presentation of an unsymbolicated report which is actually an HashMap from UnresolvedFrames to isize (count).

Enums§

ClockType
The clock type used for profiling.
Error

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

Type Aliases§

Result