Install & Compatibility
Where this runs
tested against v1.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✓ 3.03s
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PyroscopeSpanProcessor
✓ from pyroscope.otel import PyroscopeSpanProcessor
configure
✓ from pyroscope import configure as pyroscope_configure
✗ from pyroscope.otel import configure
`pyroscope.configure` is for the core profiler, not directly part of the `pyroscope-otel` package.
TracerProvider
✓ from opentelemetry.sdk.trace import TracerProvider
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)
Debug
Known issues
gotchaThe `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.fixEnsure `pip install pyroscope opentelemetry-sdk` is done, and `pyroscope.configure()` and OpenTelemetry `TracerProvider` are set up prior to using `PyroscopeSpanProcessor`.
affects: All versions
gotchaThe `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.fixPlace `pyroscope_configure(...)` at the very beginning of your application's instrumentation setup, before OpenTelemetry provider initialization.
affects: All versions
gotchaDue 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.fixBe 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.
affects: All versions
breakingThe 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.fixMonitor official OpenTelemetry and Grafana Pyroscope release notes for compatibility updates. Pinning versions of related OpenTelemetry and collector components might be necessary in production environments.
affects: All versions, due to external OTel specification evolution.
gotchaCurrently, `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.fixWhen using `pyroscope-otel` in Python, expect to primarily correlate traces with CPU profiling data. Check the latest documentation for updates on supported profile types.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opentelemetry.sdk.trace'
The `pyroscope-otel` library relies on the OpenTelemetry SDK for its functionality, and the `opentelemetry-sdk` package might not be installed in your environment.
fixInstall the required OpenTelemetry SDK package: `pip install opentelemetry-sdk`
ImportError: cannot import name 'PyroscopeSpanProcessor' from 'pyroscope_otel'
The `PyroscopeSpanProcessor` class is located within the `pyroscope_otel.processor` submodule, not directly under the top-level `pyroscope_otel` package.
fixCorrect the import statement to specify the correct submodule: `from pyroscope_otel.processor import PyroscopeSpanProcessor`
TypeError: PyroscopeSpanProcessor() missing 2 required positional arguments: 'pyroscope_client' and 'service_name'
The `PyroscopeSpanProcessor` constructor requires both an initialized `pyroscope.PyroscopeClient` instance and a `service_name` string to be passed.
fixProvide the `pyroscope_client` and `service_name` arguments during initialization:
```python
import pyroscope
from pyroscope_otel.processor import PyroscopeSpanProcessor
pyroscope_client = pyroscope.PyroscopeClient(server_address="http://localhost:4040")
processor = PyroscopeSpanProcessor(pyroscope_client=pyroscope_client, service_name="my-application")
```
AttributeError: 'NoneType' object has no attribute 'add_profile_id_to_span'
The `pyroscope_client` argument passed to `PyroscopeSpanProcessor` was `None` or an invalid object, preventing the processor from interacting with the Pyroscope client's methods.
fixEnsure a valid and properly initialized `pyroscope.PyroscopeClient` instance is passed to the `PyroscopeSpanProcessor`:
```python
import pyroscope
from pyroscope_otel.processor import PyroscopeSpanProcessor
# Initialize pyroscope client
pyroscope_client = pyroscope.PyroscopeClient(server_address="http://localhost:4040")
# Pass the initialized client to the processor
processor = PyroscopeSpanProcessor(pyroscope_client=pyroscope_client, service_name="my-application")
```
Upgrade
Version history
1.0.1latest on PyPI · released Jun 1, 2026
Audit
Dependencies
pyroscoperequiredRequired for core continuous profiling functionality, as `pyroscope-otel` integrates with it.
opentelemetry-sdkrequiredRequired for OpenTelemetry tracing instrumentation, which `pyroscope-otel` extends.