OpenTelemetry Contrib Instrumentation Packages

0.62b0 · active · verified Thu Apr 16

The `opentelemetry-contrib-instrumentations` library is a metapackage that conveniently installs a collection of community-maintained OpenTelemetry Python instrumentation packages. These instrumentations automatically capture telemetry data (traces, metrics, logs) from various third-party frameworks, databases, and HTTP clients without requiring manual code changes to the instrumented libraries themselves. The project is actively developed and follows a frequent release cadence, often aligning with the core OpenTelemetry Python SDK, typically on a monthly or bi-monthly schedule, with `b` (beta) versions being common.

Common errors

```
ModuleNotFoundError: No module named 'opentelemetry.instrumentation.flask'
```
cause The specific `opentelemetry-instrumentation-flask` package (or any other instrumentation) was not installed, or was removed by a package manager like `uv`.

fix Ensure all required individual instrumentation packages are installed. If using `uv`, explicitly list all `opentelemetry-instrumentation-*` packages in your `pyproject.toml` or reinstall using `opentelemetry-bootstrap` after `uv sync`. `pip install opentelemetry-instrumentation-flask`.
```
My application is running, but I'm not seeing any traces/metrics in the console or my backend.
```
cause The instrumentor's `.instrument()` method was not called, or a reloader (like Flask's debug mode) is interfering with instrumentation.

fix Verify that `YourInstrumentor().instrument()` is explicitly called for each library you want to trace. If using `opentelemetry-instrument` for auto-instrumentation, ensure the Flask debug mode is disabled. If using a pre-forking server, see warnings regarding forking issues.
```
TypeError: 'type' object is not subscriptable (when importing from opentelemetry_contrib_instrumentations)
```
cause Attempting to import an `Instrumentor` class directly from the `opentelemetry-contrib-instrumentations` metapackage.

fix Import `Instrumentor` classes from their dedicated package, e.g., `from opentelemetry.instrumentation.requests import RequestsInstrumentor` instead of `from opentelemetry_contrib_instrumentations import RequestsInstrumentor`.

Warnings

beta The `opentelemetry-contrib-instrumentations` package, like many OpenTelemetry Python components, is still in 'beta' (indicated by 'b' in version number). This means breaking changes can be introduced between releases without a full major version bump, though efforts are made to minimize these.
Fix: Review changelogs carefully when upgrading, especially for individual instrumentation packages. Pin versions of critical instrumentations.
breaking Breaking changes are often introduced within individual instrumentation packages, not directly by the `opentelemetry-contrib-instrumentations` metapackage. For example, specific instrumentations may drop support for older versions of the libraries they instrument, or rename callback classes.
Fix: Always check the `CHANGELOG.md` in the `opentelemetry-python-contrib` repository, focusing on the specific instrumentation packages you are using. Pin versions of individual `opentelemetry-instrumentation-*` packages if necessary.
gotcha Dependency conflicts can arise between the version requirements of an `opentelemetry-instrumentation-*` package and the version of the actual library you are instrumenting. For example, a Flask instrumentation might require `Werkzeug<3.0.0` while your application installs `Werkzeug==3.0.0`.
Fix: Ensure that the versions of your application's dependencies are compatible with the respective OpenTelemetry instrumentation packages. Check the `setup.cfg` or `pyproject.toml` of the individual instrumentation for its dependency ranges.
gotcha Using forking web servers (e.g., Gunicorn with multiple workers) can lead to issues with OpenTelemetry components, particularly the `PeriodicExportingMetricReader`, due to inconsistencies in background threads and locks across child processes.
Fix: Consider running Gunicorn with a single worker (`gunicorn -w 1 app:app`) or use programmatic auto-instrumentation. For metrics, avoid `PrometheusMetricReader` with forking servers; use `PeriodicExportingMetricReader` with one OTLP worker per process to push to Prometheus.

Install

pip install opentelemetry-contrib-instrumentations opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-distro Install all contrib instrumentations, SDK, OTLP exporter, and distro

Imports

RequestsInstrumentor
wrong:
```
from opentelemetry_contrib_instrumentations import RequestsInstrumentor
```
correct:
```
from opentelemetry.instrumentation.requests import RequestsInstrumentor
```
The `opentelemetry-contrib-instrumentations` package is a convenience for installation. Individual instrumentations must still be imported from their specific `opentelemetry-instrumentation-*` packages, not from the metapackage itself.

configure_opentelemetry

wrong:

from opentelemetry_contrib_instrumentations import configure_instrumentations

correct:

from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.distro import OpenTelemetryDistro

def configure_opentelemetry(service_name: str):
    resource = Resource.create({"service.name": service_name})
    tracer_provider = TracerProvider(resource=resource)
    span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
    tracer_provider.add_span_processor(span_processor)
    
    # Set the global tracer provider
    from opentelemetry import trace
    trace.set_tracer_provider(tracer_provider)

    # Instrument all installed contrib instrumentations
    distro = OpenTelemetryDistro()
    distro.instrument()
    # Or, to instrument specific packages:
    # from opentelemetry.instrumentation.requests import RequestsInstrumentor
    # RequestsInstrumentor().instrument()

There is no single `configure_instrumentations` function in the contrib metapackage. Instrumentation is typically enabled by iterating through `OpenTelemetryDistro().instrument()` or by calling `.instrument()` on individual `Instrumentor` classes after setting up the `TracerProvider`.

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry SDK with a console exporter and then enable automatic tracing for the `requests` library. It initializes a `TracerProvider`, configures a `SimpleSpanProcessor` with a `ConsoleSpanExporter` to print traces to the console, and then uses `RequestsInstrumentor().instrument()` to automatically trace HTTP requests made with the `requests` library. Run the script and observe the trace output in the console. For a more comprehensive automatic instrumentation, you can also use `opentelemetry-distro` which automatically instruments all compatible installed libraries.

import os
import requests
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.requests import RequestsInstrumentor

# Configure OpenTelemetry SDK
resource = Resource.create({"service.name": os.environ.get('OTEL_SERVICE_NAME', 'my-python-app')})
tracer_provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)

# Instrument the requests library
RequestsInstrumentor().instrument()

# Make an HTTP request that will be traced
def make_request():
    print("Making an HTTP request...")
    response = requests.get("https://www.example.com")
    print(f"Request completed with status: {response.status_code}")

if __name__ == "__main__":
    make_request()

# To run this, install:
# pip install opentelemetry-sdk opentelemetry-exporter-console opentelemetry-instrumentation-requests requests

view raw JSON →