{"id":6195,"library":"pyroscope-otel","title":"Pyroscope OpenTelemetry Python Integration","description":"The `pyroscope-otel` library for Python provides functionalities to link OpenTelemetry tracing data with Grafana Pyroscope's continuous profiling data. It offers a `SpanProcessor` implementation that automatically attaches profiling identifiers to trace spans, enabling users to correlate traces with detailed performance profiles. The library is actively maintained by Grafana, with its current version being 1.0.0. Releases appear to be somewhat regular, reflecting ongoing development.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/grafana/otel-profiling-python","tags":["observability","profiling","opentelemetry","pyroscope","tracing","performance","python","grafana"],"install":[{"cmd":"pip install pyroscope-otel","lang":"bash","label":"Install `pyroscope-otel`"}],"dependencies":[{"reason":"Required for core continuous profiling functionality, as `pyroscope-otel` integrates with it.","package":"pyroscope","optional":false},{"reason":"Required for OpenTelemetry tracing instrumentation, which `pyroscope-otel` extends.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"PyroscopeSpanProcessor","correct":"from pyroscope.otel import PyroscopeSpanProcessor"},{"note":"`pyroscope.configure` is for the core profiler, not directly part of the `pyroscope-otel` package.","wrong":"from pyroscope.otel import configure","symbol":"configure","correct":"from pyroscope import configure as pyroscope_configure"},{"symbol":"TracerProvider","correct":"from opentelemetry.sdk.trace import TracerProvider"}],"quickstart":{"code":"import os\nimport time\n\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\n\nfrom pyroscope import configure as pyroscope_configure\nfrom pyroscope.otel import PyroscopeSpanProcessor\n\n# 1. Configure Pyroscope profiler first\npyroscope_configure(\n    app_name=\"my-python-app\",\n    server_address=os.environ.get(\"PYROSCOPE_SERVER_ADDRESS\", \"http://localhost:4040\"),\n    auth_token=os.environ.get(\"PYROSCOPE_AUTH_TOKEN\", \"\"), # Optional for Grafana Cloud\n    sample_rate=100, # Default sample rate\n)\n\n# 2. Configure OpenTelemetry TracerProvider\nprovider = TracerProvider()\n\n# Add PyroscopeSpanProcessor to link traces and profiles\nprovider.add_span_processor(PyroscopeSpanProcessor())\n\n# Optional: Add a console exporter for visibility of spans\nprovider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\n\ntrace.set_tracer_provider(provider)\n\n# 3. Get a tracer and create spans\ntracer = trace.get_tracer(__name__)\n\ndef my_function():\n    with tracer.start_as_current_span(\"my-function-span\") as span:\n        print(\"Executing my_function...\")\n        time.sleep(0.05)\n        with tracer.start_as_current_span(\"inner-operation\"):\n            print(\"Executing inner_operation...\")\n            time.sleep(0.02)\n        print(\"my_function finished.\")\n\nif __name__ == \"__main__\":\n    print(\"Starting application with Pyroscope-OpenTelemetry integration...\")\n    my_function()\n    print(\"Application finished.\")\n    # Give some time for exporters to send data\n    time.sleep(1)\n","lang":"python","description":"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`)."},"warnings":[{"fix":"Ensure `pip install pyroscope opentelemetry-sdk` is done, and `pyroscope.configure()` and OpenTelemetry `TracerProvider` are set up prior to using `PyroscopeSpanProcessor`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Place `pyroscope_configure(...)` at the very beginning of your application's instrumentation setup, before OpenTelemetry provider initialization.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, due to external OTel specification evolution."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}