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 three methods:

Auto-instrumentation using Grafana Alloy
SDK instrumentation
SDK instrumentation through Grafana Alloy

This document explains these 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.

{{< docs/shared source="pyroscope" lookup="supported-languages-ebpf.md" version="latest" >}}

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.

{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}

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:

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

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

About instrumentation with Pyroscope SDKs through Alloy

Pyroscope SDKs can be configured to send profiles to Grafana Alloy first, which then forwards them to the Pyroscope server. This method combines the flexibility of SDK instrumentation with Alloy's infrastructure benefits.

Here's how it works:

Your application is instrumented with Pyroscope SDKs
Instead of sending profiles directly to Pyroscope, the SDK sends them to Alloy's pyroscope.receive_http component
Alloy processes and forwards the profiles to the Pyroscope server

By sending profiles through Alloy, you benefit from lower latency as profiles are sent to a local Alloy instance instead of directly over the internet to Grafana Cloud. Your application code remains focused on instrumentation while infrastructure concerns like authentication and routing are handled by Alloy's configuration. This separation allows for centralized management of metadata, where you can enrich profiles with infrastructure labels such as Kubernetes metadata or environment tags without modifying application code.

Choose the right profiling method

You can use Grafana Alloy for auto-instrumentation, the Pyroscope instrumentation SDKs directly, or SDKs through Alloy. 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. Using SDKs through Alloy adds minimal setup complexity while providing infrastructure benefits.
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 - either directly or through Alloy depending on your infrastructure needs.
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. When used with Alloy, you gain additional infrastructure flexibility without compromising SDK capabilities.

To get started, choose one of the integrations below:

    <b>Grafana Alloy</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/go_pull/" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/grafana-alloy-auto-instrumentation" title="examples">Examples</a>
  </td>
  <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/go_push/">

    <b>Golang</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/go_push/" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/golang-push" title="golang-examples">Examples</a>
  </td>
  <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/java/">

    <b>Java</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/java/">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/java/rideshare" title="java-examples">Examples</a>
  </td>
  <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/ebpf">

    <b>eBPF</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/ebpf" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/grafana-alloy-auto-instrumentation/ebpf" title="examples">Examples</a>
  </td>
  <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/python/">

    <b>Python</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/python/" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/python" title="python-examples">Examples</a>
  </td>

</tr> <tr> <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/dotnet/">

    <b>.NET</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/dotnet/" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/dotnet" title="examples">Examples</a>
  </td>
  <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/ruby/">

    <b>Ruby</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/ruby/" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/ruby" title="ruby-examples">Examples</a>
  </td>
  <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/nodejs/">

    <b>Node.js</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/nodejs/" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/nodejs/express" title="examples">Examples</a>
  </td>
  <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/rust/">

    <b>Rust</b></a>

      <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/rust/" title="Documentation">Documentation</a>

      <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/rust/rideshare" title="examples">Examples</a>
  </td>

</tr> </table>

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.