This is documentation for the next version of Pyroscope. For the latest stable release, go to the latest version.

Documentation Grafana Pyroscope Configure the client to send profiles

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 Grafana Alloy.

This document explains these two techniques and guide you when to choose each one.

About auto-instrumentation with Grafana Alloy or Agent collectors

You can send data from your application using Grafana Alloy (preferred) or Grafana Agent (legacy) collectors. Both collectors support profiling with eBPF, Java, and Golang in pull mode.

Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. Alloy uniquely combines the very best OSS observability signals in the community. Grafana Alloy uses configuration file written using River.

Alloy is the recommended collector instead of Grafana Agent. New installations should use Alloy.

Alloy 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 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:

1. Install and configure the collector on the same machine or container where your application is running.
2. The collector periodically retrieves 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 a collector 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:

1. Install the relevant Pyroscope SDK for your application’s programming language (for example, pip package, npm package, Ruby gem).
2. Instrument your application’s code using the SDK to capture the necessary profiling data.
3. SDK automatically periodically pushes 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 Alloy or Pyroscope SDK to send profiles

You can use Grafana Alloy 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: Grafana Alloy is an ideal choice for a quick and straightforward setup without modifying your application’s code. eBPF profiling supports some languages (for example, Golang, Python) better than others. More robust support for Java and other languages is 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:

Grafana Alloy Documentation Examples	Golang Documentation Examples	Java Documentation Examples	eBPF Documentation Examples	Python Documentation Examples
Dotnet Documentation Examples	Ruby Documentation Examples	Node.js Documentation Examples	Rust Documentation Examples

Enriching profile data

You can add tags to your profiles to help correlate them with your other telemetry signals. Commonly used tags include version, region, environment, and request types. You have the ability to add tags using both the SDK and Alloy.

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 (.) isn’t a valid character inside of tags and labels.

Assistance with Pyroscope

If you have more questions, feel free to reach out in the community Slack channel or create an issue on GitHub.