Pyroscope Rust SDK

Profiling data is organized into Reports and ReportBatches.

Report

A Report contains a collection of StackTraces and their associated hit counts (HashMap<StackTrace, usize>), along with shared Metadata.

ReportBatch

A ReportBatch groups reports by a specific profile_type (e.g., "process_cpu" or "memory"). The data field in a batch can be one of two types via the ReportData enum:

• Reports(Vec<Report>): Structured stack-trace reports that require pprof encoding before transmission.
• RawPprof(Vec<u8>): Pre-encoded pprof bytes (e.g., from a backend like jemalloc) that may already be gzipped.

The profiling data is structured into two main types:

1. UnresolvedFrames: Represents a raw sample. It contains a SmallVec of frames (up to MAX_DEPTH), the thread_id, a sample_timestamp, and the thread_name stored as a fixed-size byte array.

2. Frames: Represents a resolved sample. It contains a Vec<Vec<Symbol>> where each inner vector represents the symbols associated with a specific stack frame, a String for the thread_name, the thread_id, and the sample_timestamp.

Metadata in Pyroscope is used to attach searchable information to StackTrace or Report objects. Metadata is composed of a set of Tag objects.

• Tag: A simple key-value pair (key=value).
• Metadata: A collection of Tags. You can retrieve a unique identifier for metadata using get_id(), which returns a hash of the metadata content.

To add information to a report or stack trace, create a Tag and use Metadata::add_tag().

let mut metadata = Metadata::default();
metadata.add_tag(Tag::new("service".to_string(), "api-gateway".to_string()));
let id = metadata.get_id();

The PyroscopeAgent uses a type-state pattern to ensure methods are only called when the agent is in a valid state. The lifecycle transitions are:

1. PyroscopeAgentBare: The initial state before construction.
2. PyroscopeAgentReady: Created after calling .build() on the builder. The agent is initialized but not yet profiling.
3. PyroscopeAgentRunning: Created after calling .start() on a Ready agent. The agent is actively profiling and uploading data.

Transitions:

• Builder $\rightarrow$ .build() $\rightarrow$ Ready $\rightarrow$ .start() $\rightarrow$ Running $\rightarrow$ .stop() $\rightarrow$ Ready.

To use the profiler, use the PyroscopeAgentBuilder to construct an agent with a specific backend, then call .build() to initialize it, and .start() to begin profiling. The agent runs in a background thread and periodically uploads data based on the configured upload_interval.

use pyroscope::pyroscope::PyroscopeAgentBuilder;
use pyroscope::backend::{pprof_backend, PprofConfig, BackendConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent = PyroscopeAgentBuilder::new(
        "http://localhost:8080", 
        "my-app", 
        100, 
        "pyroscope-rs", 
        "0.1.0",
        pprof_backend(PprofConfig::default(), BackendConfig::default()),
    )
    .build()?;

    let agent_running = agent.start()?;
    
    // Agent is now profiling in the background...
    
    Ok(())
}

Use PyroscopeAgentBuilder to configure a new agent. You must provide the Pyroscope server URL, the application name, a sample rate, the agent name, the application version, and a backend configuration (such as pprof_backend).

use pyroscope::pyroscope::PyroscopeAgentBuilder;
use pyroscope::backend::{pprof_backend, PprofConfig, BackendConfig};

// Example configuration
let agent = PyroscopeAgentBuilder::new(
    "http://localhost:4040",
    "myapp",
    100, // sample rate
    "pyroscope-rs",
    env!("CARGO_PKG_VERSION"),
    pprof_backend(PprofConfig::default(), BackendConfig::default()),
)
.build()?;

To use the Pyroscope Rust integration with the pprof-rs backend, add the following dependency to your Cargo.toml file. Ensure you enable the backend-pprof-rs feature.

[dependencies]
pyroscope = { version = "2.0.0", features = ["backend-pprof-rs"] }

Once an agent is built, you can control the profiling lifecycle using the following methods:

1. Start profiling: Call .start()? on the agent to begin collecting data and sending it to the server. This returns a running agent handle.
2. Stop profiling: Call .stop()? on the running agent handle to pause profiling. This returns a handle representing the stopped state.
3. Shutdown: Call .shutdown() on the stopped agent handle to clean up resources. It is important to call this before the variable is dropped.

// Start profiling
let agent_running = agent.start()?;

// Stop profiling
let agent_ready = agent_running.stop()?;

// Shutdown the agent
agent_ready.shutdown();

The BackendConfig struct allows you to specify which metadata should be included in the profiling reports. Use these boolean flags to enable or disable specific identifiers:

• report_thread_id: Whether to include the thread ID.
• report_thread_name: Whether to include the thread name.
• report_pid: Whether to include the process ID (PID).

pub struct BackendConfig {
    pub report_thread_id: bool,
    pub report_thread_name: bool,
    pub report_pid: bool,
}