Pyroscope

Oodle supports continuous profiling through a Pyroscope-compatible ingestion endpoint. You can send CPU, memory, goroutine, mutex, and block profiles from any language that has a Pyroscope SDK — and visualize flame graphs directly in Grafana.

Prerequisites

You will need:

• OODLE_INSTANCE — your Oodle instance ID. Find it under Settings → API Keys in the Oodle UI. (ap1, us1)
• OODLE_API_KEY — an API key for authentication. Choose one from the same page. (ap1, us1)
• OODLE_COLLECTOR — your collector domain (e.g. <INSTANCE>.collector.oodle.ai).

Send Profiles to Oodle

Go

Install the Pyroscope Go SDK:

go get github.com/grafana/pyroscope-go

Add the following to your application's main() or initialization code:

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

func main() {
    pyroscope.Start(pyroscope.Config{
        ApplicationName: "my-app",
        ServerAddress:
            "https://<OODLE_COLLECTOR>" +
            "/v1/pyroscope/<OODLE_INSTANCE>",
        AuthToken: "<OODLE_API_KEY>",
        ProfileTypes: []pyroscope.ProfileType{
            pyroscope.ProfileCPU,
            pyroscope.ProfileAllocObjects,
            pyroscope.ProfileAllocSpace,
            pyroscope.ProfileInuseObjects,
            pyroscope.ProfileInuseSpace,
            pyroscope.ProfileGoroutines,
            pyroscope.ProfileMutexCount,
            pyroscope.ProfileMutexDuration,
            pyroscope.ProfileBlockCount,
            pyroscope.ProfileBlockDuration,
        },
    })

    // ... your application code ...
}

Python

Install the Pyroscope Python SDK:

pip install pyroscope-io

Add the following to your application startup:

import pyroscope

pyroscope.configure(
    application_name="my-app",
    server_address=(
        "https://<OODLE_COLLECTOR>"
        "/v1/pyroscope/<OODLE_INSTANCE>"
    ),
    auth_token="<OODLE_API_KEY>",
)

Java

Add the Pyroscope Java agent to your JVM startup flags:

java -javaagent:pyroscope.jar \
  -Dpyroscope.application.name=my-app \
  -Dpyroscope.server.address=\
https://<OODLE_COLLECTOR>/v1/pyroscope/<OODLE_INSTANCE> \
  -Dpyroscope.auth.token=<OODLE_API_KEY> \
  -jar my-app.jar

Download the latest pyroscope.jar from the Grafana Pyroscope Java releases.

Rust

Add the Pyroscope crate with the pprof-rs backend to your Cargo.toml:

[dependencies]
pyroscope = { version = "2.0", features = ["backend-pprof-rs"] }

Start pyroscope before the tokio runtime:

use pyroscope::pyroscope::PyroscopeAgentBuilder;
use pyroscope::backend::{
    pprof_backend, PprofConfig, BackendConfig,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent = PyroscopeAgentBuilder::new(
        "https://<OODLE_COLLECTOR>/v1/pyroscope/<OODLE_INSTANCE>",
        "my-app",
        100,
        "pyroscope-rs",
        env!("CARGO_PKG_VERSION"),
        pprof_backend(
            PprofConfig::default(),
            BackendConfig::default(),
        ),
    )
    .basic_auth(
        "Bearer".to_string(),
        "<OODLE_API_KEY>".to_string(),
    )
    .build()?;

    let _running = agent.start()?;

    // Enter the tokio runtime AFTER pyroscope starts.
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()?
        .block_on(async_main())
}

Grafana Alloy / Agent

If you run Grafana Alloy (or the legacy Grafana Agent), you can configure it to scrape pprof endpoints and forward profiles to Oodle:

pyroscope.scrape "default" {
  targets = [
    {"__address__" = "localhost:6060"},
  ]
  forward_to = [pyroscope.write.oodle.receiver]
}

pyroscope.write "oodle" {
  endpoint {
    url = "https://<OODLE_COLLECTOR>/v1/pyroscope/<OODLE_INSTANCE>"
    headers = {
      "X-API-KEY" = "<OODLE_API_KEY>",
    }
  }
}

Supported Profile Types

Profile type	What it measures
CPU	Time spent executing code
Alloc Objects	Number of heap allocations
Alloc Space	Bytes allocated on the heap
Inuse Objects	Live objects on the heap
Inuse Space	Live bytes on the heap
Goroutines	Number of goroutines (Go)
Mutex Count	Mutex contention events
Mutex Duration	Time spent waiting on mutexes
Block Count	Blocking events (channels, I/O)
Block Duration	Time spent blocked

Visualize Profiles

Profiles are queryable through the Grafana Explore interface using the Pyroscope datasource. Navigate to Dashboards → Explore in the Oodle UI and select the Pyroscope datasource to view flame graphs, filter by application name, and compare profiles across time ranges.

Labels and Filtering

The Pyroscope SDK automatically attaches labels like service_name (from ApplicationName). You can add custom labels to correlate profiles with specific requests, users, or feature flags:

Go

pyroscope.TagWrapper(
    context.Background(),
    pyroscope.Labels("controller", "order"),
    func(ctx context.Context) {
        handleOrder(ctx)
    },
)

Python

with pyroscope.tag_wrapper({
    "controller": "order",
}):
    handle_order()

Rust

let agent_running = agent_running.tag_wrapper(
    "controller".to_string(),
    "order".to_string(),
    || {
        handle_order();
    },
)?;

Best Practices

• Start with CPU and memory profiles — they surface the most actionable insights with minimal overhead.
• Use labels to separate profiles by environment, region, or request type so you can filter in the flame graph UI.
• Sample rate — the default 100 Hz CPU sample rate is a good starting point. Avoid going above 250 Hz in production as it increases overhead.
• Profile in production — continuous profiling is designed for always-on use with low overhead (typically <1% CPU).