OpenTelemetry Python Distro
raw JSON → 0.61b0 verified Tue May 12 auth: no python install: stale
OpenTelemetry Distro provides a mechanism to automatically configure some of the more common options for users, making OpenTelemetry and auto-instrumentation as quick as possible without sacrificing flexibility. It configures the SDK TracerProvider, a BatchSpanProcessor, and the OTLP SpanExporter to send data to an OpenTelemetry Collector. The current version is 0.61b0, and it is part of the `opentelemetry-python-contrib` project with frequent beta releases.
pip install opentelemetry-distro[otlp] opentelemetry-instrumentation
opentelemetry-bootstrap -a install Common errors
error ModuleNotFoundError: No module named 'opentelemetry_distro' ↓
cause This error occurs when the 'opentelemetry-distro' package is not installed in the Python environment where the application is being run, or if the Python environment is not correctly activated.
fix
Ensure the package is installed using pip:
pip install opentelemetry-distro and that your virtual environment is activated if applicable. error ModuleNotFoundError: No module named 'opentelemetry.exporter.otlp.proto.grpc' ↓
cause While `opentelemetry-distro` configures the OTLP SpanExporter by default, the specific OTLP exporter package (e.g., `opentelemetry-exporter-otlp`) is often not installed as a direct dependency of `opentelemetry-distro` itself.
fix
Install the OTLP exporter with the necessary protocol support (e.g., gRPC or HTTP) by using extras or explicitly:
pip install opentelemetry-distro[otlp] or pip install opentelemetry-exporter-otlp. error OTLP Exporter: Failed to connect ↓
cause This error indicates that the OpenTelemetry Python application, configured by `opentelemetry-distro` to export via OTLP, cannot establish a connection to the OpenTelemetry Collector. Common reasons include the Collector not running, an incorrect endpoint URL or port configuration, or network/firewall issues blocking the connection.
fix
Verify that the OpenTelemetry Collector is running and accessible. Check your
OTEL_EXPORTER_OTLP_ENDPOINT environment variable or code configuration to ensure the correct protocol (gRPC default 4317, HTTP default 4318), hostname, and port are specified. Ensure no firewalls are blocking the connection. error No traces appearing ↓
cause Even without explicit errors, traces or metrics might not be exported if the OpenTelemetry SDK (configured by `opentelemetry-distro`) is initialized too late, meaning the auto-instrumentation hooks are not registered before the target libraries (like Flask or Django) are loaded.
fix
Ensure OpenTelemetry auto-instrumentation is initialized as early as possible in your application's lifecycle, typically by running your application with
opentelemetry-instrument python myapp.py or configuring environment variables like PYTHONPATH and OTEL_PYTHON_DISTRO/OTEL_PYTHON_CONFIGURATOR for zero-code instrumentation. error AttributeError: module 'opentelemetry.sdk.trace' has no attribute 'SpanLimits' ↓
cause This `AttributeError` (or similar for other SDK components) typically arises from version mismatches between different `opentelemetry-python` packages (e.g., `opentelemetry-sdk`, `opentelemetry-api`, `opentelemetry-distro`). Beta releases, like 0.61b0 for `opentelemetry-distro`, can be particularly sensitive to these mismatches.
fix
Ensure all OpenTelemetry-related packages are installed with compatible versions. It's often best to upgrade all OpenTelemetry packages to their latest compatible versions or pin them to known working sets. A clean reinstall (
pip freeze | grep opentelemetry | xargs pip uninstall -y followed by pip install opentelemetry-distro opentelemetry-sdk opentelemetry-exporter-otlp) can resolve this. Warnings
gotcha OpenTelemetry Python, including `opentelemetry-distro`, is largely in beta. While tracing APIs are relatively stable, metrics and logging APIs are still evolving. This means breaking changes can occur between minor versions. ↓
fix Review release notes carefully before upgrading. Test new versions thoroughly in non-production environments.
gotcha The `opentelemetry-distro` configures a default OTLP SpanExporter, which attempts to send data to an OpenTelemetry Collector (by default on `http://localhost:4317` or `grpc://localhost:4317`). If no Collector is running or accessible, telemetry will not be exported. ↓
fix Ensure an OpenTelemetry Collector is running and accessible from your application. Configure the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable if your Collector is at a different address or port.
breaking When using web frameworks like Flask or Django, running in debug mode with an enabled reloader (e.g., `app.run(debug=True)`) can conflict with auto-instrumentation, causing it to fail. ↓
fix Disable the reloader when using auto-instrumentation. For Flask, set `use_reloader=False` (e.g., `app.run(debug=True, use_reloader=False)`). For Django, use the `--noreload` flag when starting your application.
gotcha The generic `opentelemetry-distro` provides default configurations. If you intend to use a vendor-specific OpenTelemetry distribution (e.g., AWS Distro for OpenTelemetry, Azure Monitor OpenTelemetry Distro), ensure you install and use *that specific distro* as it often includes tailored exporters, resource detectors, and instrumentations for the target backend. Mixing distros or expecting generic distro to have vendor-specific features is a common mistake. ↓
fix Identify your target observability backend and consult its specific OpenTelemetry documentation. Install the appropriate vendor-specific distro if one exists and is recommended.
breaking The `opentelemetry-bootstrap` command-line tool, often used for auto-instrumentation, may not support all common CLI arguments (e.g., `-q` for quiet mode). Passing unsupported arguments will result in an 'unrecognized arguments' error. ↓
fix Ensure `opentelemetry-bootstrap` is called with only its recognized arguments. If it's being implicitly called by a testing framework or script with flags like `-q`, modify the script to remove such flags when invoking `opentelemetry-bootstrap`.
Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) dependency_conflict - - - -
3.10 alpine (musl) - - - -
3.10 slim (glibc) dependency_conflict - 5.5s - -
3.10 slim (glibc) - - - -
3.11 alpine (musl) dependency_conflict - - - -
3.11 alpine (musl) - - - -
3.11 slim (glibc) dependency_conflict - 4.9s - -
3.11 slim (glibc) - - - -
3.12 alpine (musl) dependency_conflict - - - -
3.12 alpine (musl) - - - -
3.12 slim (glibc) dependency_conflict - 4.0s - -
3.12 slim (glibc) - - - -
3.13 alpine (musl) dependency_conflict - - - -
3.13 alpine (musl) - - - -
3.13 slim (glibc) dependency_conflict - 4.0s - -
3.13 slim (glibc) - - - -
3.9 alpine (musl) dependency_conflict - - - -
3.9 alpine (musl) - - - -
3.9 slim (glibc) dependency_conflict - 6.5s - -
3.9 slim (glibc) - - - -
Imports
- Auto-instrumentation via opentelemetry-instrument
opentelemetry-instrument python my_app.py
Quickstart last tested: 2026-04-24
import os
import requests
from flask import Flask
app = Flask(__name__)
@app.route("/hello")
def hello_world():
return "Hello, World!"
@app.route("/external")
def call_external():
# This call should be traced automatically if requests is instrumented
response = requests.get("http://localhost:5001/hello")
return f"Called external service: {response.text}"
if __name__ == '__main__':
# Run this app with: opentelemetry-instrument python app.py
# Ensure an OpenTelemetry Collector is running on localhost:4317 or configure OTEL_EXPORTER_OTLP_ENDPOINT
# (e.g., docker run -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:latest --config=/etc/otel-collector-config.yaml)
# The collector config should include otlp receiver and a logging/debug exporter.
app.run(port=5001, debug=False, use_reloader=False)