Rust
Supported platforms#
| Linux | macOS | Windows | Docker |
|---|---|---|---|
| ✅ | ✅ | ✅ |
Profiling Rust applications#
Add the pyroscope and pyroscope_pprofrs crates to your Cargo.toml:
cargo add pyroscopecargo add pyroscope_pprofrsMinimal 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 backendlet pprof_config = PprofConfig::new().sample_rate(100);let pprof_backend = Pprof::new(pprof_config);
// Configure Pyroscope Agentlet agent =PyroscopeAgent::builder("http://localhost:4040", "myapp").backend(pprof_backend).build()?;You can start profiling by invoking
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();Tags#
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 (Running state), 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 Profilinglet agent_running = agent.start().unwrap();
// Generate Tag Wrapper functionslet (add_tag, remove_tag) = agent_running.tag_wrapper();
// Profiled code (with no tags)
// Add tags to the agentadd_tag("key".to_string(), "value".to_string());
// This portion will be profiled with the specified tag.
// Remove tags from the agentremove_tag("key".to_string(), "value".to_string());
// Stop the agent let agent_ready = running_agent.stop();Full Configuration#
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 backendlet pprof_config = PprofConfig::new().sample_rate(100);let pprof_backend = Pprof::new(pprof_config);
// Configure Pyroscope Agentlet 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
shutdownfunction before dropping the Agent. - Relevant Links
Examples#
Library Examples#
Several examples are available that can showcase how the library can be used. These examples could be run from the library repository.
For example, to run the tags example.
cargo run --example tags Usage Examples
- basic: Minimal configuration example.
- tags: Example using Tags.
- async: Example using Async code with Tokio.
- multi-thread: Example using multiple threads.
- with-logger: Example with logging to stdout.
- error: Example with an invalid server address.