Pyroscope OpenTelemetry Python Integration

Warnings

• gotcha The `pyroscope-otel` package requires both the base `pyroscope` profiler and OpenTelemetry tracing to be instrumented in your application. It acts as a bridge, not a standalone profiler or tracer. You must explicitly install and configure both prerequisites.
  Fix: Ensure `pip install pyroscope opentelemetry-sdk` is done, and `pyroscope.configure()` and OpenTelemetry `TracerProvider` are set up prior to using `PyroscopeSpanProcessor`.
• gotcha The `pyroscope.configure()` function must be called and executed *before* any OpenTelemetry `TracerProvider` is created and the `PyroscopeSpanProcessor` is registered. Incorrect ordering can lead to profiling data not being correctly associated with traces.
  Fix: Place `pyroscope_configure(...)` at the very beginning of your application's instrumentation setup, before OpenTelemetry provider initialization.
• gotcha Due to the nature of sampling profilers, trace spans that are very short in duration (e.g., less than the profiler's sample interval, typically 10ms for a 100 samples/second CPU profiler) may not be captured or linked with profiling data. This is a limitation of the profiling technique.
  Fix: Be aware that very short-lived operations might not show profiling data. Focus on longer-running or frequently executed spans when analyzing performance bottlenecks. Consider adjusting the `sample_rate` in `pyroscope.configure` if granular short-span profiling is critical, but be mindful of increased overhead.
• breaking The OpenTelemetry profiles signal specification is under active development. This means that breaking changes can occur in related components (profilers, collectors, SDKs), potentially requiring careful version management and updates to maintain compatibility across your observability stack.
  Fix: Monitor official OpenTelemetry and Grafana Pyroscope release notes for compatibility updates. Pinning versions of related OpenTelemetry and collector components might be necessary in production environments.
• gotcha Currently, `pyroscope-otel` for Python primarily supports CPU profiling. Other profiling types (e.g., memory) available in Pyroscope might not be integrated with OpenTelemetry traces via this package.
  Fix: When using `pyroscope-otel` in Python, expect to primarily correlate traces with CPU profiling data. Check the latest documentation for updates on supported profile types.

Install

• pip install pyroscope-otel Install `pyroscope-otel`

Imports

• PyroscopeSpanProcessor

  from pyroscope.otel import PyroscopeSpanProcessor

• configure

  from pyroscope import configure as pyroscope_configure

  `pyroscope.configure` is for the core profiler, not directly part of the `pyroscope-otel` package.
• TracerProvider

  from opentelemetry.sdk.trace import TracerProvider

Quickstart

This quickstart demonstrates the essential steps to integrate `pyroscope-otel`. It configures the core Pyroscope profiler, sets up an OpenTelemetry `TracerProvider`, and then registers the `PyroscopeSpanProcessor` to automatically link trace spans with profiling data. Ensure a Pyroscope server is running and accessible at the configured `server_address` (default `http://localhost:4040`).

import os
import time

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

from pyroscope import configure as pyroscope_configure
from pyroscope.otel import PyroscopeSpanProcessor

# 1. Configure Pyroscope profiler first
pyroscope_configure(
    app_name="my-python-app",
    server_address=os.environ.get("PYROSCOPE_SERVER_ADDRESS", "http://localhost:4040"),
    auth_token=os.environ.get("PYROSCOPE_AUTH_TOKEN", ""), # Optional for Grafana Cloud
    sample_rate=100, # Default sample rate
)

# 2. Configure OpenTelemetry TracerProvider
provider = TracerProvider()

# Add PyroscopeSpanProcessor to link traces and profiles
provider.add_span_processor(PyroscopeSpanProcessor())

# Optional: Add a console exporter for visibility of spans
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# 3. Get a tracer and create spans
tracer = trace.get_tracer(__name__)

def my_function():
    with tracer.start_as_current_span("my-function-span") as span:
        print("Executing my_function...")
        time.sleep(0.05)
        with tracer.start_as_current_span("inner-operation"):
            print("Executing inner_operation...")
            time.sleep(0.02)
        print("my_function finished.")

if __name__ == "__main__":
    print("Starting application with Pyroscope-OpenTelemetry integration...")
    my_function()
    print("Application finished.")
    # Give some time for exporters to send data
    time.sleep(1)