Configure the client to send profiles
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 explains these two techniques and guide you when to choose each one.
About auto-instrumentation with Grafana Agent
Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
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 simplified with the eBPF profiling option that doesn’t necessitate pull or push mechanisms.
Here’s how it works:
- Install and configure Grafana Agent on the same machine or container where your application is running
- The Agent periodically retrieves your application’s performance profiling data, regardless of the language or technology stack your application is using
- The captured profiles are then sent to the Pyroscope server for storage and analysis
Using 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.
About instrumentation with Pyroscope SDKs
Alternatively, Pyroscope SDKs offer you the ability to instrument your application directly for more precise profiling. Use the SDKs when you want complete control over the profiling process or when the application you are profiling is written in a language supported by the SDKs (for example, Java, Python, .NET, and others).
Here’s how to use Pyroscope SDKs:
- Install the relevant Pyroscope SDK for your application’s programming language (for example, pip package, npm package, Ruby gem).
- Instrument your application’s code using the SDK to capture the necessary profiling data
- SDK 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.
Choose Grafana Agent or Pyroscope SDK to send profiles
You can use Grafana Agent for auto-instrumentation or the Pyroscope instrumentation SDKs. The method you choose 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 (for example, Golang) better than others. More robust support for Python, Java, and other languages are in development.
- Language support: If you want more control over the profiling process and your application is written in a language supported by the Pyroscope SDKs, consider using the SDKs.
- 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:
Enriching profile data
You can add tags to your profiles to help correlate them with your other telemetry signals. Some common tags that are used are version, region, environment, request types, etc. You have the ability to add tags using both the SDK and the agent.
Valid tag formats may contain ASCII letters and digits, as well as underscores. It must match the regex [a-zA-Z_][a-zA-Z0-9_]
.
In Pyroscope, a period (.
) is not a valid character inside of tags and labels.
Assistance with Pyroscope
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!
Was this page helpful?
Related resources from Grafana Labs
![Getting started with continuous profiling with Grafana Cloud Profiles](/media/webinar/cont-profiling-meta-2.png?w=200 200w, /media/webinar/cont-profiling-meta-2.png?w=400 400w)
![Continuous profiling with Grafana Pyroscope: developer experience, flame graphs, and more](/media/events/grafanacon/2023/meta-no-dates/GrafanaCON-2023-Session-Continuous-profiling.png?w=200 200w, /media/events/grafanacon/2023/meta-no-dates/GrafanaCON-2023-Session-Continuous-profiling.png?w=400 400w)
![Building scalable OSS observability with Mimir, Loki, Tempo, and Pyroscope](/media/events/obscon/2023/meta/obscon23-session-mi-10-Building-scalable-OSS-observability-with-Mimir,-Loki,-Tempo,-and-Pyroscope.png?w=200 200w, /media/events/obscon/2023/meta/obscon23-session-mi-10-Building-scalable-OSS-observability-with-Mimir,-Loki,-Tempo,-and-Pyroscope.png?w=400 400w)