---
id: pyroscope-otel
version: "1.1.0"
license: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# pyroscope-otel — A library providing profiling functionalities related to OpenTelemetry

License: permissive · Maintenance: active · Downloads: 1.5M/mo

## What it is and what it does

Pyroscope-otel is a bridge between OpenTelemetry tracing and Pyroscope continuous profiling. It provides a span processor that automatically attaches a profile identifier to the root span of each trace, creating a direct link between traces in Grafana Tempo and their corresponding performance profiles in Pyroscope. On the profiling side, it adds thread-level tags (span_id, span_name, trace_id) for the lifetime of the root span, enabling filtering and correlation of profile samples by trace.

The package requires both Pyroscope and OpenTelemetry to be independently configured in your application. It works with manual instrumentation (explicit TracerProvider setup) and auto-instrumentation frameworks, though Pyroscope configuration remains mandatory in all cases. The integration is lightweight—it depends only on opentelemetry-api, opentelemetry-sdk, and pyroscope-io—and installs as a pure Python wheel with no compiled dependencies.

Use it for:

- Correlate slow traces in Grafana Tempo with CPU/memory profiles in Pyroscope to pinpoint performance bottlenecks
- Navigate from a distributed trace to the exact profiling data for that transaction to debug latency issues
- Filter profile samples by trace ID on the Pyroscope server to isolate performance data for specific requests
- Monitor applications using both OpenTelemetry and Pyroscope without maintaining separate correlation logic

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Connects OpenTelemetry tracing with Pyroscope continuous profiling, attaching profile identifiers to spans and adding trace context to profile samples.

Yes, if you already use both OpenTelemetry and Pyroscope and need to correlate traces with profiles. The package is actively maintained, has no known vulnerabilities, and installs with low friction. It is a thin, purpose-built integration layer rather than a general-purpose tool, so install it only if you have both tracing and profiling infrastructure in place.

## Install

pip install pyroscope-otel
uv add pyroscope-otel
poetry add pyroscope-otel

## Installing pyroscope-otel

Before you install: Low install friction with a pure-Python wheel. Actively maintained as of 45 days ago. Requires Python 3.10 or later.

License in practice: Apache License 2.0 (permissive) permits commercial and derivative use with minimal restrictions; attribution and license reproduction required in distributions.

Quickstart:

pip install pyroscope-otel

from pyroscope import configure as pyroscope_configure
from opentelemetry.sdk.trace import TracerProvider
from pyroscope.otel import PyroscopeSpanProcessor

pyroscope_configure(app_name="my-app", server_address="http://localhost:4040")
provider = TracerProvider()
provider.add_span_processor(PyroscopeSpanProcessor())

Pyroscope must be configured before creating spans. Requires Python 3.10 or later.

Verify before relying:

- Whether the package works with Python versions between 3.10 and current stable, or only the latest minor release
- Performance overhead of attaching profile IDs and trace tags to every root span
- Compatibility with trace exporters other than Grafana Tempo

## Package facts

- License: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

opentelemetry profiling integration, trace profile correlation, pyroscope otel span processor, continuous profiling with traces, grafana tempo pyroscope link, observability, profiling, tracing

[View on SkillFed](https://skillfed.io/packages/pyroscope-otel) · [View on PyPI](https://pypi.org/project/pyroscope-otel/)