Menu

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.

Grafana Pyroscope Configure the client
Open source

Sending profiles from your application

Pyroscope is a continuous profiling database that allows you to analyze the performance of your applications. When sending profiles to Pyroscope, you can choose between two primary methods: SDK Instrumentation and Auto-Instrumentation using the Grafana agent. This document will explain these two techniques and guide you when to choose each one.

Pyroscope agent server diagram

Grafana Agent (Auto-Instrumentation)

The Grafana agent is a component that runs alongside your application and periodically gathers profiling data from it. This method is suitable when you want to collect profiles from existing applications without modifying their source code. This approach is made even simpler with the eBPF profiling option that doesn’t necessitate pull or push mechanisms. Here’s how it works:

  1. Install and configure the Grafana agent on the same machine or container where your application is running
  2. The agent will periodically retrieve your application’s performance profiling data, regardless of the language or technology stack your application is using
  3. The captured profiles are then sent to the Pyroscope server for storage and analysis

Using the Grafana agent provides a hassle-free option, especially when dealing with multiple applications or microservices, allowing you to centralize the profiling process without changing your application’s codebase.

Pyroscope SDKs (SDK Instrumentation)

Alternatively, Pyroscope SDKs offer you the ability to instrument your application directly for more precise profiling. This mode is suitable when you wish to have complete control over the profiling process or when the application you are profiling is written in a language supported by the SDKs (e.g. Java, Python, .NET, etc.). Here’s how to use Pyroscope SDKs:

  1. Install the relevant Pyroscope SDK for your application’s programming language (e.g. pip package, npm package, Ruby gem, etc.)
  2. Instrument your application’s code using the SDK to capture the necessary profiling data
  3. SDK will automatically periodically push the captured profiles to the Pyroscope server for storage and analysis

By using the Pyroscope SDKs, you have the flexibility to customize the profiling process according to your application’s specific requirements. You can selectively profile specific sections of code or send profiles at different intervals, depending on your needs.

Choosing the Grafana agent or Pyroscope SDK to send profiles

The choice between using Grafana Agent (Auto-Instrumentation) or Pyroscope SDKs (SDK Instrumentation) depends on your specific use case and requirements. Here are some factors to consider when making the choice:

  • Ease of setup: The Grafana agent is an ideal choice for a quick and straightforward setup without modifying your application’s code. Note that eBPF profiling supports some languages (i.e. Golang) better than others, but more robust support for Python, Java, and other languages is coming soon!
  • Language support: If your application is written in a language supported by the Pyroscope SDKs, and you want more control over the profiling process, using the SDKs is recommended.
  • Flexibility: The Pyroscope SDKs offer greater flexibility in terms of customizing the profiling process and capturing specific sections of code with labels. If you have particular profiling needs or want to fine-tune the data collection process, the SDKs would be your best bet.

To get started choose one of the integrations below:


Grafana Agent

Documentation
Examples

Golang

Documentation
Examples

Java

Documentation
Examples

eBPF

Documentation
Examples

Python

Documentation
Examples

Dotnet

Documentation
Examples

Ruby

Documentation
Examples

NodeJS

Documentation
Examples

Rust

Documentation
Examples

If you have more questions feel free to reach out in our Slack channel or create an issue on GitHub and the Pyroscope team will help!