Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Configure the Client

Language SDKs

Rust

Open source

Rust

How to add Rust profiling to your application

Add the pyroscope and pyroscope_pprofrs crates to your Cargo.toml:

cargo add pyroscope
cargo add pyroscope_pprofrs

Rust client configuration

At a minimum, you need to provide the URL of the Pyroscope server and the name of your application. You also need to configure a profiling backend. For Rust, you can use pprof-rs.

// Configure profiling backend
let pprof_config = PprofConfig::new().sample_rate(100);
let pprof_backend = Pprof::new(pprof_config);

// Configure Pyroscope Agent
let agent = PyroscopeAgent::builder("http://localhost:4040", "myapp")
    .backend(pprof_backend)
    .build()?;

Users of a secured backend will need to provide authentication details. Grafana Cloud uses Basic authentication. Your username is a numeric value which you can get from the “Details Page” for Pyroscope from your stack on grafana.com. On this same page, create a token and use it as the Basic authentication password. The configuration then would look similar to:

fn  main() ->  Result<()> {
std::env::set_var("RUST_LOG", "debug");
pretty_env_logger::init_timed();
let user = std::env::var("USER").unwrap();
let password = std::env::var("PASSWORD").unwrap();
let url = std::env::var("PYROSCOPE_URL").unwrap();
let samplerate = std::env::var("SAMPLE_RATE").unwrap().to_string().parse().unwrap();
let application_name = "example.basic";

let agent = PyroscopeAgent::builder(url, application_name.to_string())
    .basic_auth(user, password).backend(pprof_backend(PprofConfig::new().sample_rate(samplerate)))
    .tags([("app", "Rust"), ("TagB", "ValueB")].to_vec())
    .build()?;

You can start profiling by invoking the following code:

let agent_running = agent.start().unwrap();

The agent can be stopped at any point, and it’ll send a last report to the server. The agent can be restarted at a later point.

let agent_ready = agent.stop().unwrap();

It’s recommended to shutdown the agent before exiting the application. A last request to the server might be missed if the agent is not shutdown properly.

agent_ready.shutdown();

How to add profiling labels to Rust applications

Tags can be added or removed after the agent is started. As of 0.5.0, the Pyroscope Agent supports tagging within threads. Check the tags and multi-thread examples for detailed usage.

After the agent is started, the tag_wrapper function becomes available. tag_wrapper returns a tuple of functions to add and remove tags to the agent across thread boundaries. This function is available as long as the agent is running and can be called multiple times.

// Start Profiling
let agent_running = agent.start().unwrap();

// Generate Tag Wrapper functions
let (add_tag, remove_tag) = agent_running.tag_wrapper();

// Profiled code (with no tags)

// Add tags to the agent
add_tag("key".to_string(), "value".to_string());

// This portion will be profiled with the specified tag.

// Remove tags from the agent
remove_tag("key".to_string(), "value".to_string());

// Stop the agent
let agent_ready = running_agent.stop();

Rust client configuration options

The agent accepts additional initial parameters:

Backend: Profiling backend. For Rust, it’s pprof-rs
Sample Rate: Sampling Frequency in Hertz. Default is 100.
Tags: Initial tags.

// Configure Profiling backend
let pprof_config = PprofConfig::new().sample_rate(100);
let pprof_backend = Pprof::new(pprof_config);

// Configure Pyroscope Agent
let agent =
PyroscopeAgent::builder("http://localhost:4040", "myapp")
// Profiling backend
.backend(pprof_backend)
// Sample rate
.sample_rate(100)
// Tags
.tags(vec![("env", "dev")])
// Create the agent
.build()?;

Technical Details

Backend: The Pyroscope Agent uses pprof-rs as a backend. As a result, the limitations for pprof-rs also applies. As of 0.5.0, the Pyroscope Agent supports tagging within threads. Check the tags and multi-thread examples for usage.
Timer: epoll (for Linux) and kqueue (for macOS) are required for a more precise timer.
Shutdown: The Pyroscope Agent might take some time (usually less than 10 seconds) to shutdown properly and drop its threads. For a proper shutdown, it’s recommended that you run the shutdown function before dropping the agent.
Relevant Links