Pyroscope language SDKs on Grafana Labs

Go (push mode)

Wed, 08 Apr 2026 14:38:28 +0000

Go (push mode)

Our Go Profiler is a cutting-edge tool designed to optimize Golang applications. By integrating with Pyroscope, the profiler offers developers an in-depth view of their Go codebase, enabling real-time performance analysis. This powerful tool is crucial for pinpointing inefficiencies, streamlining code execution, and ensuring peak performance in Go applications.

Pyroscope uses the standard runtime/pprof package to collect profiling data. Refer to the official documentation for details.

Note
Refer to Available profiling types for a list of profile types supported by Go.

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Configure the Go client

To start profiling a Go application, you need to include the Go module in your app:

go get github.com/grafana/pyroscope-go

Note
If you’d prefer to use Pull mode you can do so using Grafana Alloy.

Add the following code to your application:

package main

import "github.com/grafana/pyroscope-go"

func main() {
  // These 2 lines are only required if you're using mutex or block profiling
  // Read the explanation below for how to set these rates:
  runtime.SetMutexProfileFraction(5)
  runtime.SetBlockProfileRate(5)

  pyroscope.Start(pyroscope.Config{
    ApplicationName: "simple.golang.app",

    // replace this with the address of pyroscope server
    ServerAddress:   "http://pyroscope-server:4040",

    // you can disable logging by setting this to nil
    Logger:          pyroscope.StandardLogger,

    // you can provide static tags via a map:
    Tags:            map[string]string{"hostname": os.Getenv("HOSTNAME")},

    ProfileTypes: []pyroscope.ProfileType{
      // these profile types are enabled by default:
      pyroscope.ProfileCPU,
      pyroscope.ProfileAllocObjects,
      pyroscope.ProfileAllocSpace,
      pyroscope.ProfileInuseObjects,
      pyroscope.ProfileInuseSpace,

      // these profile types are optional:
      pyroscope.ProfileGoroutines,
      pyroscope.ProfileMutexCount,
      pyroscope.ProfileMutexDuration,
      pyroscope.ProfileBlockCount,
      pyroscope.ProfileBlockDuration,
    },
  })

  // your code goes here
}

Alternatively, if you want more control over the profiling process, you can manually handle the profiler initialization and termination:

  profiler, err := pyroscope.Start(pyroscope.Config{
    // omitted for brevity
  })
  if err != nil {
    // the only reason this would fail is if the configuration is not valid
    log.Fatalf("failed to start Pyroscope: %v", err)
  }
  defer profiler.Stop()

  // your code goes here
}

This approach may be necessary if you need to ensure that the last profile is sent before the application exits.

Add profiling labels to your application

You can add tags (labels) to the profiling data. These tags can be used to filter the data in the UI. There is a custom API that’s in line with the go-native pprof API:

// these two ways of adding tags are equivalent:
pyroscope.TagWrapper(context.Background(), pyroscope.Labels("controller", "slow_controller"), func(c context.Context) {
  slowCode()
})

pprof.Do(context.Background(), pprof.Labels("controller", "slow_controller"), func(c context.Context) {
  slowCode()
})

Mutex profiling

Mutex profiling is useful for finding sources of contention within your application. It helps you find out which mutexes are being held by which goroutines.

To enable mutex profiling, you need to add the following code to your application:

runtime.SetMutexProfileFraction(rate)

The rate parameter controls the fraction of mutex contention events that are reported in the mutex profile. On average, 1/rate events are reported.

Block profiling

Block profiling lets you analyze how much time your program spends waiting on the blocking operations such as:

select
channel send/receive
semacquire
notifyListWait

To enable block profiling, you need to add the following code to your application:

runtime.SetBlockProfileRate(rate)

The rate parameter controls the fraction of goroutine blocking events that are reported in the blocking profile. The profiler aims to sample an average of one blocking event per rate nanoseconds spent blocked.

Send data to Pyroscope OSS or Grafana Cloud Profiles

To configure the Golang SDK to send data to Pyroscope, replace the <URL> placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace <User> with your Grafana Cloud stack user and <Password> with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace <TenantID> with your Pyroscope tenant ID.

pyroscope.Start(pyroscope.Config{
  ApplicationName:   "example.golang.app",
  ServerAddress:     "<URL>",
  // Optional HTTP Basic authentication
  BasicAuthUser:     "<User>",
  BasicAuthPassword: "<Password>",
  // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
  // TenantID:          "<TenantID>",
  ProfileTypes: []pyroscope.ProfileType{
    pyroscope.ProfileCPU,
    pyroscope.ProfileInuseObjects,
    pyroscope.ProfileAllocObjects,
    pyroscope.ProfileInuseSpace,
    pyroscope.ProfileAllocSpace,
  },
})

Locate the URL, user, and password in Grafana Cloud Profiles

When you configure Alloy or your SDK, you need to provide the URL, user, and password for your Grafana Cloud stack. This information is located in the Pyroscope section of your Grafana Cloud stack.

Navigate to your Grafana Cloud stack.
Select Details next to your stack.
Locate the Pyroscope section and select Details.
Copy the URL, User, and Password values in the Configure the client and data source using Grafana credentials section.
Use these values to complete the configuration.

As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to Create a Cloud Access Policy.

Option: Use `DisableGCRuns` for handling increased memory usage

Pyroscope may require additional resources when tracking a lot of objects. For example, a Go service that indexes large amounts of data requires more memory. This tracking can lead to higher CPU usage and potential CPU throttling.

You can use DisableGCRuns in your Go configuration to disable automatic runtimes. If this flag is activated, there is less GC running and therefore less CPU resources spent. However, the heap profile may be less precise.

Background

In Go’s pprof heap profiling, forcing garbage collection (GC) ensures accurate memory usage snapshots by removing uncollected objects. Without this step, the heap profile may include memory that has been allocated but is no longer in use–objects that stay in memory simply because they haven’t been collected yet. This can mask or mimic memory leaks and introduce bias into the profiles, complicating their analysis. Therefore, Pyroscope defaults to forcing GC every time a heap profile is collected.

However, in some cases, forcing GC can increase CPU usage, especially if there are many live objects in the heap. This issue is reflected by the appearance of the runtime.GC function in the CPU profile. If the problem has manifested, and some inaccuracy in the heap profile is acceptable, then it is advisable to disable this option to avoid performance degradation.

Activate `DisableGCRuns`

Add DisableGCRuns: true to the pyroscope.Start(pyroscope.Config) block.

pyroscope.Start(pyroscope.Config{
  ApplicationName:   "example.golang.app",
  ServerAddress:     "<URL>",
  // Disable automatic runtime.GC runs between getting the heap profiles.
		DisableGCRuns:   true,

Golang profiling examples

Check out the following resources to learn more about Golang profiling:

Golang examples
Golang Demo showing golang example with tags

Java

Wed, 08 Apr 2026 14:38:28 +0000

Java

The Java Profiler, integrated with Pyroscope, offers a comprehensive solution for performance analysis in Java applications. It provides real-time insights, enabling developers to understand and optimize their Java codebase effectively. This tool is crucial for improving application responsiveness, reducing resource consumption, and ensuring top-notch performance in Java environments.

Note
Refer to Available profiling types for a list of profile types supported by each language.

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Add Java profiling to your application

Java integration is distributed as a single jar file (pyroscope.jar) or a Maven package. Supported platforms include:

Linux on x64
Linux on ARM64
MacOS on x64
MacOS on ARM64

Visit the GitHub releases page to download the latest version of pyroscope.jar.

The latest release is also available on Maven Central.

Configure the Java client

You can start Pyroscope either from your application’s code or attach it as javaagent.

Start Pyroscope from app’s Java code

First, add the Pyroscope dependency:

maven

gradle

<dependency>
  <groupId>io.pyroscope</groupId>
  <artifactId>agent</artifactId>
  <version>2.1.2</version>
</dependency>

implementation("io.pyroscope:agent:2.1.2")

Add the following code to your application:

java

spring

PyroscopeAgent.start(
  new Config.Builder()
    .setApplicationName("ride-sharing-app-java")
    .setProfilingEvent(EventType.ITIMER)
    .setFormat(Format.JFR)
    .setServerAddress("http://pyroscope-server:4040")
    .build()
);

import io.pyroscope.javaagent.PyroscopeAgent;
import io.pyroscope.javaagent.config.Config;
import io.pyroscope.javaagent.EventType;
import io.pyroscope.http.Format;

@PostConstruct
public void init() {

    PyroscopeAgent.start(
    new Config.Builder()
        .setApplicationName("ride-sharing-app-java")
        .setProfilingEvent(EventType.ITIMER)
        .setFormat(Format.JFR)
        .setServerAddress("http://pyroscope-server:4040")
        // Optionally, if authentication is enabled, specify the API key.
        // .setBasicAuthUser("<User>")
        // .setBasicAuthPassword("<Password>")
        // Optionally, if you'd like to set allocation threshold to register events, in bytes. '0' registers all events
        // .setProfilingAlloc("0")
        .build()
    );
}

You can also optionally replace some Pyroscope components:

PyroscopeAgent.start(
  new PyroscopeAgent.Options.Builder(config)
    .setExporter(snapshot -> {
      // Your custom export/upload logic may go here
      // It is invoked every 10 seconds by default with snapshot of
      // profiling data
    })
    .setLogger((l, msg, args) -> {
      // Your custom logging may go here
      // Pyroscope does not depend on any logging library
      System.out.printf((msg) + "%n", args);
    })
    .setScheduler(profiler -> {
      // Your custom profiling schedule logic may go here
    })
    .build()
);

Start Pyroscope as `javaagent`

To start profiling a Java application, run your application with pyroscope.jar javaagent:

export PYROSCOPE_APPLICATION_NAME=my.java.app
export PYROSCOPE_SERVER_ADDRESS=http://pyroscope-server:4040

java -javaagent:pyroscope.jar -jar app.jar

Add profiling labels to Java applications

You can add dynamic tags (labels) to the profiling data. These tags can filter the data in the UI.

Add labels dynamically:

Pyroscope.LabelsWrapper.run(new LabelsSet("controller", "slow_controller"), () -> {
  slowCode();
});

You can also add static tags (labels) to the profiling data:

Pyroscope.setStaticLabels(Map.of("region", System.getenv("REGION")));
// or with Config.Builder if you start pyroscope with PyroscopeAgent.start
PyroscopeAgent.start(new Config.Builder()
    .setLabels(mapOf("region", System.getenv("REGION")))
    // ...
    .build()
);

Configuration options

When you start Pyroscope as javaagent or obtain configuration by Config.build(), Pyroscope searches for configuration in multiple sources: system properties, environment variables, and pyroscope.properties. Property keys have the same names as environment variables, but are in lowercase and underscores (_) are replaced with periods (.). For example, PYROSCOPE_FORMAT becomes pyroscope.format

The Java integration supports JFR format to be able to support multiple events (JFR is the only output format that supports multiple events in async-profiler). There are several environment variables that define how multiple event configuration works:

Flag	Description
`PYROSCOPE_AGENT_ENABLED`	Enables the agent. The default is `true`.
`PYROSCOPE_APPLICATION_NAME`	Sets the application name. If not provided, a generated name will be used.
`PYROSCOPE_PROFILING_INTERVAL`	Sets the profiling sampling interval for CPU profiling. The default is `10ms`.
`PYROSCOPE_FORMAT`	Sets the profiler output format. The default is `collapsed`, but in order to support multiple formats it must be set to `jfr`.
`PYROSCOPE_PROFILER_EVENT`	Sets the profiler event. With JFR format enabled, this event refers to one of the possible CPU profiling events: `itimer`, `cpu`, `wall`. The default is `itimer`.
`PYROSCOPE_PROFILER_ALLOC`	Sets the threshold to register allocation events, in bytes (equivalent to `--alloc=` in `async-profiler`). The default value is `""` - empty string, which means that allocation profiling is disabled. Setting it to `0` will register every event, causing significant CPU and network overhead, making it not suitable for production environments. We recommend setting a starting value of 512k and adjusting it as needed.
`PYROSCOPE_PROFILER_LOCK`	Sets the threshold to register lock events, in nanoseconds (equivalent to `--lock=` in `async-profiler`). The default value is `""` - empty string, which means that lock profiling is disabled. Setting it to `0` will register every event, causing significant CPU and network overhead, making it not suitable for production environments. We recommend setting a starting value of 10ms and adjusting it as needed.
`PYROSCOPE_UPLOAD_INTERVAL`	Sets the interval for uploading profiling data. The default is `10s`.
`PYROSCOPE_JAVA_STACK_DEPTH_MAX`	Sets the maximum stack depth. The default is `2048`.
`PYROSCOPE_SERVER_ADDRESS`	Address of the Pyroscope server. The default is `http://localhost:4040`
`PYROSCOPE_CONFIGURATION_FILE`	Sets an additional properties configuration file. The default value is `pyroscope.properties`.
`PYROSCOPE_BASIC_AUTH_USER`	HTTP Basic authentication username. The default value is `""` - empty string, no authentication.
`PYROSCOPE_BASIC_AUTH_PASSWORD`	HTTP Basic authentication password. The default value is `""` - empty string, no authentication.
`PYROSCOPE_TENANT_ID`	pyroscope tenant ID, passed as X-Scope-OrgID http header. The default value is `""` - empty string, no tenant ID.
`PYROSCOPE_HTTP_HEADERS`	Extra HTTP headers in JSON format, for example: `{"X-Header": "Value"}`. The default value is `{}` - no extra headers.
`PYROSCOPE_LABELS`	Sets static labels in the form of comma separated `key=value` pairs. The default value is `""` - empty string, no labels.
`PYROSCOPE_LOG_LEVEL`	Determines the level of verbosity for Pyroscope’s logger. Available options include `debug`, `info`, `warn`, and `error`. The default value is set to `info`.
`PYROSCOPE_PUSH_QUEUE_CAPACITY`	Specifies the size of the ingestion queue that temporarily stores profiling data in memory during network outages. The default value is set to 8.
`PYROSCOPE_INGEST_MAX_TRIES`	Sets the maximum number of times to retry an ingestion API call in the event of failure. A value of `-1` indicates that the retries will continue indefinitely. The default value is set to `8`.
`PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR`	Sets the level of GZIP compression applied to uploaded JFR files. This option accepts values of `NO_COMPRESSION`, `BEST_SPEED`, `BEST_COMPRESSION`, and `DEFAULT_COMPRESSION`.
`PYROSCOPE_EXPORT_COMPRESSION_LEVEL_LABELS`	Operates similarly to `PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR`, but applies to the dynamic labels part. The default value is set to `BEST_SPEED`.
`PYROSCOPE_ALLOC_LIVE`	Retain allocation samples with live objects only (objects that have not been collected by the end of profiling session). Useful for finding Java heap memory leaks. The default value is `false`
`PYROSCOPE_GC_BEFORE_DUMP`	A boolean value that executes a `System.gc()` command before dumping the profile when set to `true`. This option may be useful for live profiling, but is disabled by default.

Send data to Pyroscope OSS or Grafana Cloud Profiles

Add the following code to your application:

PyroscopeAgent.start(
    new Config.Builder()
        .setApplicationName("test-java-app")
        .setProfilingEvent(EventType.ITIMER)
        .setFormat(Format.JFR)
        .setServerAddress("<URL>")
        // Set these if using Grafana Cloud:
        .setBasicAuthUser("<User>")
        .setBasicAuthPassword("<Password>")
        // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana cloud.
        // .setTenantID("<TenantID>")
        .build()
);

To configure the Java SDK to send data to Pyroscope, replace the <URL> placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace <User> with your Grafana Cloud stack user and <Password> with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace <TenantID> with your Pyroscope tenant ID.

Locate the URL, user, and password in Grafana Cloud Profiles

Navigate to your Grafana Cloud stack.
Select Details next to your stack.
Locate the Pyroscope section and select Details.
Copy the URL, User, and Password values in the Configure the client and data source using Grafana credentials section.
Use these values to complete the configuration.

As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to Create a Cloud Access Policy.

Example configurations

The following configuration sets application name, Pyroscope format, profiling interval, event, and lock. This example is an excerpt from the rideshare Dockerfile available in the Pyroscope repository.

ENV PYROSCOPE_APPLICATION_NAME=rideshare.java.push.app
ENV PYROSCOPE_FORMAT=jfr
ENV PYROSCOPE_PROFILING_INTERVAL=10ms
ENV PYROSCOPE_PROFILER_EVENT=itimer
ENV PYROSCOPE_PROFILER_LOCK=10ms

This configuration excerpt enables allocation and lock profiling:

PYROSCOPE_PROFILER_ALLOC=512k
PYROSCOPE_PROFILER_LOCK=10ms

Java profiling examples

Check out the following resources to learn more about Java profiling:

Java examples
Java Demo showing Java example with tags

.NET

Wed, 08 Apr 2026 14:38:28 +0000

.NET

Our .NET Profiler is a powerful tool designed to enhance the performance analysis and optimization of .NET applications. It seamlessly integrates with Pyroscope, offering real-time insights into the resource usage and bottlenecks within your .NET codebase. This integration empowers developers to pinpoint inefficiencies, improve application speed, and ensure resource-efficient operation.

Note
Refer to Available profiling types for a list of profile types supported by each language.

Supported profiling types

The .NET Profiler supports the following profiling types:

CPU
Wall time
Allocations
Lock contention
Exceptions
Live heap (requires .NET 7+)

Compatibility

The only compatible operating system and architecture combination is Linux running on amd64 architecture.

Our .NET profiler works with the following .NET versions:

.NET 6
.NET 7
.NET 8

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Configure the .NET client

Obtain Pyroscope.Profiler.Native.so and Pyroscope.Linux.ApiWrapper.x64.so from the latest tarball:

curl -s -L https://github.com/grafana/pyroscope-dotnet/releases/download/v0.13.0-pyroscope/pyroscope.0.13.0-glibc-x86_64.tar.gz  | tar xvz -C .

Or copy them from the latest docker image. We have glibc and musl versions:

COPY --from=pyroscope/pyroscope-dotnet:0.13.0-glibc /Pyroscope.Profiler.Native.so /dotnet/Pyroscope.Profiler.Native.so
COPY --from=pyroscope/pyroscope-dotnet:0.13.0-glibc /Pyroscope.Linux.ApiWrapper.x64.so /dotnet/Pyroscope.Linux.ApiWrapper.x64.so

Set the following required environment variables to enable profiler

PYROSCOPE_APPLICATION_NAME=rideshare.dotnet.app
PYROSCOPE_SERVER_ADDRESS=http://localhost:4040
PYROSCOPE_PROFILING_ENABLED=1
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={BD1A650D-AC5D-4896-B64F-D6FA25D6B26A}
CORECLR_PROFILER_PATH=/dotnet/Pyroscope.Profiler.Native.so
LD_PRELOAD=/dotnet/Pyroscope.Linux.ApiWrapper.x64.so
LD_LIBRARY_PATH=/dotnet

Note
The LD_LIBRARY_PATH environment variable should point to the directory containing the Pyroscope.Profiler.Native.so file. This ensures that the dynamic linker can locate the profiler’s shared libraries at runtime.

Note
Since .NET version 8 the environment variable DOTNET_EnableDiagnostics=0 (or its legacy equivalent COMPlus_EnableDiagnostics=0) will also disable the profiler. In order to get the previous behaviour (allowing profiling, but switch off IPC and Debugging) the following environment variables should be set instead:
shell
DOTNET_EnableDiagnostics=1
DOTNET_EnableDiagnostics_IPC=0
DOTNET_EnableDiagnostics_Debugger=0
DOTNET_EnableDiagnostics_Profiler=1

.NET Profiler API

With a managed helper you can interact with the Pyroscope profiler from .NET runtime. You can add labels, turn on/off profiling types, and more.

To use it, first, add the Pyroscope dependency:

dotnet add package Pyroscope

Add profiling labels to your application

You can add labels to the profiling data to filter the data in the UI. Common labels include:

hostname
region
team
api_endpoint

Create a LabelSet and wrap a piece of code with Pyroscope.LabelsWrapper.

var labels = Pyroscope.LabelSet.Empty.BuildUpon()
    .Add("key1", "value1")
    .Build();
Pyroscope.LabelsWrapper.Do(labels, () =>
{
  SlowCode();
});

Labels can be nested. For nesting LabelSets use LabelSet.BuildUpon on non-empty set.

var labels = Pyroscope.LabelSet.Empty.BuildUpon()
    .Add("key1", "value1")
    .Build();
Pyroscope.LabelsWrapper.Do(labels, () =>
{
  var labels2 = labels.BuildUpon()
    .Add("key2", "value2")
    .Build();
  Pyroscope.LabelsWrapper.Do(labels2, () =>
  {
    SlowCode();
  });
  FastCode();
});

Dynamic control

It is possible to dynamically enable/disable specific profiling types. Profiling types have to be configured prior.

// Enables or disables CPU/wall profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_CPU_ENABLED and
// PYROSCOPE_PROFILING_WALLTIME_ENABLED environment variables. If CPU/wall profiling is not
// configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetCPUTrackingEnabled(enabled);
// Enables or disables allocation profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_ALLOCATION_ENABLED environment variable.
// If allocation profiling is not configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetAllocationTrackingEnabled(enabled);
// Enables or disables contention profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_LOCK_ENABLED environment variable.
// If contention profiling is not configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetContentionTrackingEnabled(enabled);
// Enables or disables exception profiling dynamically.
// This function works in conjunction with the PYROSCOPE_PROFILING_EXCEPTION_ENABLED environment variable.
// If exception profiling is not configured, this function will have no effect.
Pyroscope.Profiler.Instance.SetExceptionTrackingEnabled(enabled);

It is possible to dynamically change authorization credentials:

// Set Basic authorization username and password. Clears any previous authorization credentials.
Pyroscope.Profiler.Instance.SetBasicAuth(basicAuthUser, BasicAuthPassword);

Here is a simple example exposing these APIs as HTTP endpoints.

Configuration options

ENVIRONMENT VARIABLE	Type	DESCRIPTION
PYROSCOPE_PROFILING_LOG_DIR	String	Sets the directory for .NET Profiler logs. Defaults to /var/log/pyroscope/.
PYROSCOPE_LABELS	String	Static labels to apply to an uploaded profile. Must be a list of key:value separated by commas such as: layer:api or team:intake.
PYROSCOPE_SERVER_ADDRESS	String	Address of the Pyroscope Server
PYROSCOPE_PROFILING_ENABLED	Boolean	If set to true, enables the .NET Profiler. Defaults to false.
PYROSCOPE_PROFILING_WALLTIME_ENABLED	Boolean	If set to false, disables the Wall time profiling. Defaults to false.
PYROSCOPE_PROFILING_CPU_ENABLED	Boolean	If set to false, disables the CPU profiling. Defaults to true.
PYROSCOPE_PROFILING_EXCEPTION_ENABLED	Boolean	If set to true, enables the Exceptions profiling. Defaults to false.
PYROSCOPE_PROFILING_ALLOCATION_ENABLED	Boolean	If set to true, enables the Allocations profiling. Defaults to false.
PYROSCOPE_PROFILING_LOCK_ENABLED	Boolean	If set to true, enables the Lock Contention profiling. Defaults to false.
PYROSCOPE_PROFILING_HEAP_ENABLED	Boolean	If set to true, enables the Live heap profiling. Requires .NET 7+. Defaults to false.
PYROSCOPE_BASIC_AUTH_USER	String	For HTTP Basic Authentication, use this to send profiles to authenticated server, for example Grafana Cloud
PYROSCOPE_BASIC_AUTH_PASSWORD	String	For HTTP Basic Authentication, use this to send profiles to authenticated server, for example Grafana Cloud
PYROSCOPE_TENANT_ID	String	Only needed if using multi-tenancy in Pyroscope.

Send data to Pyroscope OSS or Grafana Cloud Profiles

To send profiling data from your .NET application, configure your environment for either Pyroscope OSS or Grafana Cloud Profiles using the following steps:

export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={BD1A650D-AC5D-4896-B64F-D6FA25D6B26A}
export CORECLR_PROFILER_PATH=/dotnet/Pyroscope.Profiler.Native.so
export LD_PRELOAD=/dotnet/Pyroscope.Linux.ApiWrapper.x64.so
export LD_LIBRARY_PATH=/dotnet
export PYROSCOPE_PROFILING_ENABLED=1
export PYROSCOPE_APPLICATION_NAME=example.dotnet.app
export PYROSCOPE_SERVER_ADDRESS=<URL>
# Use these environment variables to send data to Grafana Cloud Profiles
export PYROSCOPE_BASIC_AUTH_USER=<User>
export PYROSCOPE_BASIC_AUTH_PASSWORD=<Password>
# Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
# export PYROSCOPE_TENANT_ID=<TenantID>

To configure the .NET SDK to send data to Grafana Cloud Profiles or Pyroscope, replace the <URL> placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace <User> with your Grafana Cloud stack user and <Password> with your Grafana Cloud API key.

If your open source Pyroscope server has multi-tenancy enabled, you’ll need to specify a tenant ID. Replace <TenantID> with your Pyroscope tenant ID.

Locate the URL, user, and password in Grafana Cloud Profiles

Navigate to your Grafana Cloud stack.
Select Details next to your stack.
Locate the Pyroscope section and select Details.
Copy the URL, User, and Password values in the Configure the client and data source using Grafana credentials section.
Use these values to complete the configuration.

As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to Create a Cloud Access Policy.

Python

Wed, 08 Apr 2026 14:38:28 +0000

Python

The Python profiler, when integrated with Pyroscope, transforms the way you analyze and optimize Python applications. This combination provides unparalleled real-time insights into your Python codebase, allowing for precise identification of performance issues It’s an essential tool for Python developers focused on enhancing code efficiency and application speed.

Note
Refer to Available profiling types for a list of profile types supported by each language.

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Profiling on macOS

macOS has a feature called System Integrity Protection (SIP) that prevents even the root user from reading memory from any binary located in system folders.

The easiest way to avoid interference from SIP, is by installing a Python distribution into your home folder. This can be achieved for example by using pyenv:

# Setup pyenv
brew update
brew install pyenv
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc
#  Restart your shell
exec "$SHELL"
# Install Python 3.12
pyenv install 3.12

Add Python profiling to your application

Install the pyroscope-io pip package:

pip install pyroscope-io

Configure the Python client

Add the following code to your application. This code will initialize the Pyroscope profiler and start profiling:

import pyroscope

pyroscope.configure(
  application_name = "my.python.app", # replace this with some name for your application
  server_address   = "http://my-pyroscope-server:4040", # replace this with the address of your Pyroscope server
)

Optionally, you can configure several additional parameters:

import os
import pyroscope

pyroscope.configure(
    application_name    = "my.python.app", # replace this with some name for your application
    server_address      = "http://my-pyroscope-server:4040", # replace this with the address of your Pyroscope server
    sample_rate         = 100, # default is 100
    detect_subprocesses = False, # detect subprocesses started by the main process; default is False
    oncpu               = True, # report cpu time only; default is True
    gil_only            = True, # only include traces for threads that are holding on to the Global Interpreter Lock; default is True
    enable_logging      = True, # does enable logging facility; default is False
    tags                = {
        "region": f'{os.getenv("REGION")}',
    }
)

Add profiling labels to Python applications

You can add tags to certain parts of your code:

# You can use a wrapper:
with pyroscope.tag_wrapper({ "controller": "slow_controller_i_want_to_profile" }):
    slow_code()

Sending data to Pyroscope OSS or Grafana Cloud Profiles with Python SDK

import pyroscope

pyroscope.configure(
    application_name = "example.python.app",
    server_address = "<URL>",
    basic_auth_username = '<User>',
    basic_auth_password = '<Password>',
    # Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
    # tenant_id = "<TenantID>",
)

To configure the Python SDK to send data to Pyroscope, replace the <URL> placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace <User> with your Grafana Cloud stack user and <Password> with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace <TenantID> with your Pyroscope tenant ID.

Locate the URL, user, and password in Grafana Cloud Profiles

Navigate to your Grafana Cloud stack.
Select Details next to your stack.
Locate the Pyroscope section and select Details.
Copy the URL, User, and Password values in the Configure the client and data source using Grafana credentials section.
Use these values to complete the configuration.

As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to Create a Cloud Access Policy.

Python profiling examples

Check out the following resources to learn more about Python profiling:

Python examples demonstrating how Django, Flask, and FastAPI apps can be profiled with Pyroscope.
A Python demo on play.grafana.org.

Ruby

Wed, 08 Apr 2026 14:38:28 +0000

Ruby

The Ruby Profiler revolutionizes performance tuning in Ruby applications. Integrated with Pyroscope, it offers real-time performance data, allowing developers to delve deep into their Ruby codebase. This tool is essential for identifying performance issues, optimizing code efficiency, and enhancing the overall speed and reliability of Ruby applications.

Note
Refer to Available profiling types for a list of profile types supported by Ruby.

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Add Ruby profiling to your application

Add the pyroscope gem to your Gemfile:

bundle add pyroscope

Configure the Ruby client

Add the following code to your application. If you’re using Rails, put this into config/initializers directory. This code will initialize the Pyroscope profiler and start profiling:

require 'pyroscope'

Pyroscope.configure do |config|
  config.application_name = "my.ruby.app" # replace this with some name for your application
  config.server_address   = "http://my-pyroscope-server:4040" # replace this with the address of your Pyroscope server
end

How to add profiling labels to Ruby applications

The Pyroscope Ruby integration provides a number of ways to tag profiling data. For example, you can provide tags when you’re initializing the profiler:

require 'pyroscope'

Pyroscope.configure do |config|
  config.application_name = "my.ruby.app"
  config.server_address   = "http://my-pyroscope-server:4040"

  config.tags = {
    "hostname" => ENV["HOSTNAME"],
  }
end

Or you can dynamically tag certain parts of your code:

Pyroscope.tag_wrapper({ "controller": "slow_controller_i_want_to_profile" }) do
  slow_code
end

Rails profiling auto-instrumentation

By default, if you add Pyroscope to a Rails application it will automatically tag your actions with a action="<controller_name>/<action_name>" tag.

To disable Rails auto-instrumentation, set autoinstrument_rails to false:

Pyroscope.configure do |config|
  config.autoinstrument_rails = false
  # more configuration
end

Sending data to Pyroscope OSS or Grafana Cloud Profiles with Ruby SDK

require "pyroscope"

Pyroscope.configure do |config|
  config.application_name = "example.ruby.app"
  config.server_address = "<URL>"
  config.basic_auth_username='<User>'
  config.basic_auth_password='<Password>'
  # Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
  # config.tenant_id='<TenantID>'
end

To configure the Ruby SDK to send data to Pyroscope, replace the <URL> placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace <User> with your Grafana Cloud stack user and <Password> with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace <TenantID> with your Pyroscope tenant ID.

Locate the URL, user, and password in Grafana Cloud Profiles

Navigate to your Grafana Cloud stack.
Select Details next to your stack.
Locate the Pyroscope section and select Details.
Copy the URL, User, and Password values in the Configure the client and data source using Grafana credentials section.
Use these values to complete the configuration.

As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to Create a Cloud Access Policy.

Ruby profiling examples

Check out the following resources to learn more about Ruby profiling:

Ruby examples demonstrating how Ruby applications, including Rails, can be profiled with Pyroscope.
A Ruby demo on play.grafana.org.

Rust

Wed, 08 Apr 2026 14:38:28 +0000

Rust

Optimize your Rust applications with our advanced Rust Profiler. In collaboration with Pyroscope, it offers real-time profiling capabilities, shedding light on the intricacies of your Rust codebase. This integration is invaluable for developers seeking to enhance performance, reduce resource usage, and achieve efficient code execution in Rust applications.

Note
Refer to Available profiling types for a list of profile types supported by Rust.

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Add Rust profiling to your application

Add the pyroscope and pyroscope_pprofrs crates to your Cargo.toml:

cargo add pyroscope
cargo add pyroscope_pprofrs

Configure the Rust client

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 backend
let pprof_config = PprofConfig::new().sample_rate(100);
let backend_impl = pprof_backend(pprof_config);

// Configure Pyroscope Agent
let agent = PyroscopeAgent::builder("http://localhost:4040", "myapp")
    .backend(backend_impl)
    .build()?;

Users of a secured backend will need to provide authentication details. Grafana Cloud uses Basic authentication. Your username is a numeric value which you can get from the “Details Page” for Pyroscope from your stack on grafana.com. On this same page, create a token and use it as the Basic authentication password. The configuration then would look similar to:

fn  main() ->  Result<()> {
std::env::set_var("RUST_LOG", "debug");
pretty_env_logger::init_timed();
let user = std::env::var("USER").unwrap();
let password = std::env::var("PASSWORD").unwrap();
let url = std::env::var("PYROSCOPE_URL").unwrap();
let samplerate = std::env::var("SAMPLE_RATE").unwrap().to_string().parse().unwrap();
let application_name = "example.basic";

let agent = PyroscopeAgent::builder(url, application_name.to_string())
    .basic_auth(user, password).backend(pprof_backend(PprofConfig::new().sample_rate(samplerate)))
    .tags([("app", "Rust"), ("TagB", "ValueB")].to_vec())
    .build()?;

You can start profiling by invoking the following code:

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 shut down 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();

Locate the URL, user, and password in Grafana Cloud Profiles

Navigate to your Grafana Cloud stack.
Select Details next to your stack.
Locate the Pyroscope section and select Details.
Copy the URL, User, and Password values in the Configure the client and data source using Grafana credentials section.
Use these values to complete the configuration.

As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to Create a Cloud Access Policy.

Add profiling labels to Rust applications

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, 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 Profiling
let agent_running = agent.start().unwrap();

// Generate Tag Wrapper functions
let (add_tag, remove_tag) = agent_running.tag_wrapper();

// Profiled code (with no tags)

// Add tags to the agent
add_tag("key".to_string(), "value".to_string());

// This portion will be profiled with the specified tag.

// Remove tags from the agent
remove_tag("key".to_string(), "value".to_string());

// Stop the agent
let agent_ready = running_agent.stop();

Rust client configuration options

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 backend
let pprof_config = PprofConfig::new().sample_rate(100);
let pprof_backend = Pprof::new(pprof_config);

// Configure Pyroscope Agent
let 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 shut down properly and drop its threads. For a proper shutdown, it’s recommended that you run the shutdown function before dropping the agent.
Relevant Links

Examples

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.

Stand-alone examples

basic: Simple Rust application that uses the Pyroscope Library.
rideshare: A multi-instances web service running on Docker.

Node.js

Wed, 08 Apr 2026 14:38:28 +0000

Node.js

Enhance your Node.js application’s performance with our Node.js Profiler. Seamlessly integrated with Pyroscope, it provides real-time insights into your application’s operation, helping you identify and resolve performance bottlenecks. This integration is key for Node.js developers aiming to boost efficiency, reduce latency, and maintain optimal application performance.

Note
Refer to Available profiling types for a list of profile types supported by each language.

Before you begin

To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted Pyroscope instance with Grafana Cloud Profiles (requires a free Grafana Cloud account).

The Pyroscope server can be a local server for development or a remote server for production use.

Add Node.js profiling to your application

To start profiling a Node.js application, you need to include the npm module in your app:

npm install @pyroscope/nodejs

# or
yarn add @pyroscope/nodejs

Configure the Node.js client

Add the following code to your application:

const Pyroscope = require('@pyroscope/nodejs');

Pyroscope.init({
    serverAddress: 'http://pyroscope:4040',
    appName: 'myNodeService',
    // Enable CPU time collection for wall profiles
    // This is required for CPU profiling functionality
    // wall: {
    //   collectCpuTime: true
    // }
});

Pyroscope.start()

Note
If you’d prefer, you can use Pull mode using Grafana Alloy.

Configuration options

Init parameter	ENVIRONMENT VARIABLE	Type	DESCRIPTION
`appName:`	`PYROSCOPE_APPLICATION_NAME`	String	Sets the `service_name` label
`serverAddress:`	`PYROSCOPE_SERVER_ADDRESS`	String	URL of the Pyroscope Server
`basicAuthUser:`	n/a	String	Username for basic auth / Grafana Cloud stack user ID (Default `""`)
`basicAuthPassword:`	n/a	String	Password for basic auth / Grafana Cloud API key (Default `""`)
`flushIntervalMs:`	`PYROSCOPE_FLUSH_INTERVAL_MS`	Number	Interval when profiles are sent to the server (Default `60000`)
`heapSamplingIntervalBytes`	`PYROSCOPE_HEAP_SAMPLING_INTERVAL_BYTES`	Number	Average number of bytes between samples. (Default `524288`)
`heapStackDepth:`	`PYROSCOPE_HEAP_STACK_DEPTH`	Number	Maximum stack depth for heap samples (Default `64`)
`wall.SamplingDurationMs:`	`PYROSCOPE_WALL_SAMPLING_DURATION_MS`	Number	Duration of a single wall profile (Default `60000`)
`wall.SamplingIntervalMicros:`	`PYROSCOPE_WALL_SAMPLING_INTERVAL_MICROS`	Number	Interval of how often wall samples are collected (Default `10000`
`wall.CollectCpuTime:`	`PYROSCOPE_WALL_COLLECT_CPU_TIME`	Boolean	Required for CPU profiling. Enable CPU time collection as part of the wall profiler (Default `false`)
`tags:`	n/a	LabelSet	Static labels applying to all profiles collected (Default `{}`)
`sourceMapper:`	n/a	SourceMapper	Provide source file mapping information (Default `undefined`)

Add profiling labels to Node.js applications

Static labels

You can add static labels to the profiling data. These labels can be used to filter the data in the UI and apply for all profiles collected. Common static labels include:

hostname
region
team

Pyroscope.init({
  serverAddress: 'http://pyroscope:4040',
  appName: 'myNodeService',
  tags: {
    region: ENV['region']
  },
});

Pyroscope.start()

Dynamic labels for Wall/CPU profiles

In Wall and CPU profiles, labels can also be attached dynamically and help to separate different code paths:

Pyroscope.wrapWithLabels({ vehicle: 'bike' }, () =>
  slowCode()
);

Send data to Pyroscope OSS or Grafana Cloud

Pyroscope.init({
  serverAddress: 'http://pyroscope:4040',
  appName: 'myNodeService',
  tags: {
    region: ENV['region']
  },
  basicAuthUser: ENV['PYROSCOPE_BASIC_AUTH_USER'],
  basicAuthPassword: ENV['PYROSCOPE_BASIC_AUTH_PASSWORD'],
  // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
  // tenantID: ENV['PYROSCOPE_TENANT_ID'],
});

Pyroscope.start()

To configure the Node.js SDK to send data to Pyroscope, replace the serverAddress placeholder with the appropriate server URL. This could be the Grafana Cloud Pyroscope URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace basicAuthUser with your Grafana Cloud stack user ID and basicAuthPassword with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace tenantID with your Pyroscope tenant ID.

Locate the URL, user, and password in Grafana Cloud Profiles

Navigate to your Grafana Cloud stack.
Select Details next to your stack.
Locate the Pyroscope section and select Details.
Copy the URL, User, and Password values in the Configure the client and data source using Grafana credentials section.
Use these values to complete the configuration.

As an alternative, you can also create a Cloud Access Policy and generate a token to use instead of the user and password. For more information, refer to Create a Cloud Access Policy.

Troubleshoot

Setting DEBUG env to pyroscope provides additional debugging information.

DEBUG=pyroscope node index.js

Pyroscope language SDKs on Grafana Labs

Go (push mode)

Go (push mode)

Before you begin

Configure the Go client

Add profiling labels to your application

Mutex profiling

Block profiling

Send data to Pyroscope OSS or Grafana Cloud Profiles

Locate the URL, user, and password in Grafana Cloud Profiles

Option: Use DisableGCRuns for handling increased memory usage

Background

Activate DisableGCRuns

Golang profiling examples

Java

Java

Before you begin

Add Java profiling to your application

Configure the Java client

Start Pyroscope from app’s Java code

Start Pyroscope as javaagent

Add profiling labels to Java applications

Configuration options

Send data to Pyroscope OSS or Grafana Cloud Profiles

Locate the URL, user, and password in Grafana Cloud Profiles

Example configurations

Java profiling examples

.NET

.NET

Supported profiling types

Compatibility

Before you begin

Configure the .NET client

.NET Profiler API

Add profiling labels to your application

Dynamic control

Configuration options

Send data to Pyroscope OSS or Grafana Cloud Profiles

Locate the URL, user, and password in Grafana Cloud Profiles

Python

Python

Before you begin

Profiling on macOS

Add Python profiling to your application

Configure the Python client

Add profiling labels to Python applications

Sending data to Pyroscope OSS or Grafana Cloud Profiles with Python SDK

Locate the URL, user, and password in Grafana Cloud Profiles

Python profiling examples

Ruby

Ruby

Before you begin

Add Ruby profiling to your application

Configure the Ruby client

How to add profiling labels to Ruby applications

Rails profiling auto-instrumentation

Sending data to Pyroscope OSS or Grafana Cloud Profiles with Ruby SDK

Locate the URL, user, and password in Grafana Cloud Profiles

Ruby profiling examples

Rust

Rust

Before you begin

Add Rust profiling to your application

Configure the Rust client

Locate the URL, user, and password in Grafana Cloud Profiles

Add profiling labels to Rust applications

Rust client configuration options

Technical details

Examples

Usage examples

Stand-alone examples

Node.js

Node.js

Before you begin

Add Node.js profiling to your application

Configure the Node.js client

Configuration options

Add profiling labels to Node.js applications

Static labels

Dynamic labels for Wall/CPU profiles

Option: Use `DisableGCRuns` for handling increased memory usage

Activate `DisableGCRuns`

Start Pyroscope as `javaagent`