Client Instrumentation

Instrumenting Applications with Pyroscope

Source: https://grafana.com/docs/pyroscope/latest/configure-client/

There are three ways to send profiling data to Pyroscope. Each approach offers different trade-offs between setup effort, data richness, and language support.

Instrumentation Methods

┌───────────────────────────────────────────────────────────────────────┐
│                    Three Ways to Send Profiles                        │
│                                                                       │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
│  │  1. Grafana      │  │  2. SDK Direct   │  │  3. SDK via Alloy   │  │
│  │     Alloy        │  │     Push         │  │     (hybrid)        │  │
│  │                  │  │                  │  │                     │  │
│  │  No code changes │  │  SDK in app code │  │  SDK in app code    │  │
│  │  eBPF / pull     │  │  pushes directly │  │  pushes to local    │  │
│  │  mode profiling  │  │  to Pyroscope    │  │  Alloy, which       │  │
│  │                  │  │                  │  │  forwards to        │  │
│  │                  │  │                  │  │  Pyroscope          │  │
│  └────────┬─────────┘  └────────┬─────────┘  └──────────┬──────────┘ │
│           │                     │                        │            │
│           ▼                     ▼                        ▼            │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                     Pyroscope Server                            │  │
│  └─────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘

Method 1 — Auto-instrumentation with Grafana Alloy

Grafana Alloy collects profiles without any code changes. It supports:

• eBPF profiling — CPU profiles from natively compiled languages (C/C++, Go, Rust, Zig) and high-level languages (Java, .NET, Python, Ruby, PHP, Node.js, Perl)
• Pull mode — scrapes pprof endpoints from Go and Java applications

Best for: quick setup, polyglot environments, when you can’t modify application code.

Method 2 — Direct SDK Instrumentation

Install a language-specific Pyroscope SDK in your application. The SDK automatically pushes profiles periodically to Pyroscope server.

Best for: maximum control over profiling configuration, richer profile types (mutex, block, allocations), dynamic labels.

Method 3 — SDK via Alloy (Hybrid)

Applications instrumented with SDKs send profiles to Alloy’s pyroscope.receive_http component, which forwards them to Pyroscope. Benefits:

• Lower latency — local Alloy instance vs direct internet connection
• Centralized metadata — Alloy adds infrastructure labels (node, namespace, pod)
• Buffering & retry — Alloy handles transient failures

Best for: production environments where you want SDK-level data with infrastructure-level enrichment.

Choosing the Right Method

Supported Language SDKs

SDK Examples by Language

Go

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

func main() {
  runtime.SetMutexProfileFraction(5)
  runtime.SetBlockProfileRate(5)

  pyroscope.Start(pyroscope.Config{
    ApplicationName: "my-go-app",
    ServerAddress:   "http://pyroscope-server:4040",
    Tags:            map[string]string{"hostname": os.Getenv("HOSTNAME")},
    ProfileTypes: []pyroscope.ProfileType{
      pyroscope.ProfileCPU,
      pyroscope.ProfileAllocObjects,
      pyroscope.ProfileAllocSpace,
      pyroscope.ProfileInuseObjects,
      pyroscope.ProfileInuseSpace,
      pyroscope.ProfileGoroutines,
      pyroscope.ProfileMutexCount,
      pyroscope.ProfileMutexDuration,
      pyroscope.ProfileBlockCount,
      pyroscope.ProfileBlockDuration,
    },
  })
}

Dynamic labels — tag specific code paths:

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

Java

Option A — from code (e.g. Spring Boot @PostConstruct):

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

Option B — as javaagent (no code changes):

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

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

Key Java configuration:

Dynamic labels in Java:

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

Python

import pyroscope

pyroscope.configure(
  application_name = "my-python-app",
  server_address   = "http://pyroscope-server:4040",
  sample_rate      = 100,
  oncpu            = True,
  gil_only         = True,
  tags             = {
    "region": os.getenv("REGION"),
  }
)

Dynamic labels in Python:

with pyroscope.tag_wrapper({"controller": "slow_controller"}):
    slow_code()

.NET

.NET profiling uses a native CLR profiler — no code changes needed, only environment variables:

PYROSCOPE_APPLICATION_NAME=my-dotnet-app
PYROSCOPE_SERVER_ADDRESS=http://pyroscope-server: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

Available profile types (all toggled via environment variables):

Dynamic labels in .NET:

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

Node.js

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

Pyroscope.init({
  serverAddress: 'http://pyroscope-server:4040',
  appName: 'my-node-app',
  tags: {
    region: 'eu-west-1',
  },
});

Pyroscope.start();

Dynamic labels in Node.js:

Pyroscope.wrapWithLabels({ controller: 'slow_controller' }, () =>
  slowCode()
);

Tag and Label Rules

Tags (labels) allow filtering profiles in Grafana. All Pyroscope SDKs follow the same rules:

• Valid characters: ASCII letters, digits, underscores ([a-zA-Z_][a-zA-Z0-9_])
• Periods (.) are not valid in tag names
• Two types of labels:
  • Static — set at initialization, apply to all profiles (e.g. region, hostname)
  • Dynamic — set per code block using language-specific wrappers (e.g. controller, endpoint)

💡 Tip: Use dynamic labels to tag specific endpoints or controllers. This lets you filter flame graphs to see exactly which code paths are expensive for a given route.