{"id":1003,"library":"opentelemetry-distro","title":"OpenTelemetry Python Distro","description":"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.","status":"active","version":"0.61b0","language":"python","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["observability","opentelemetry","tracing","metrics","auto-instrumentation","telemetry"],"install":[{"cmd":"pip install opentelemetry-distro[otlp] opentelemetry-instrumentation\nopentelemetry-bootstrap -a install","lang":"bash","label":"Basic Installation with OTLP Exporter and Auto-instrumentation"}],"dependencies":[{"reason":"Core OpenTelemetry API, pulled in by the distro.","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK, pulled in by the distro.","package":"opentelemetry-sdk","optional":false},{"reason":"Enables auto-instrumentation capabilities, pulled in by the distro.","package":"opentelemetry-instrumentation","optional":false},{"reason":"Required for OTLP export, installed via the `[otlp]` extra.","package":"opentelemetry-exporter-otlp","optional":true}],"imports":[{"note":"The `opentelemetry-distro` package is primarily used via the `opentelemetry-instrument` command-line wrapper, which applies auto-instrumentation at runtime based on discovered libraries and the distro's configuration.","symbol":"Auto-instrumentation via opentelemetry-instrument","correct":"opentelemetry-instrument python my_app.py"}],"quickstart":{"code":"import os\nimport requests\nfrom flask import Flask\n\napp = Flask(__name__)\n\n@app.route(\"/hello\")\ndef hello_world():\n    return \"Hello, World!\"\n\n@app.route(\"/external\")\ndef call_external():\n    # This call should be traced automatically if requests is instrumented\n    response = requests.get(\"http://localhost:5001/hello\")\n    return f\"Called external service: {response.text}\"\n\nif __name__ == '__main__':\n    # Run this app with: opentelemetry-instrument python app.py\n    # Ensure an OpenTelemetry Collector is running on localhost:4317 or configure OTEL_EXPORTER_OTLP_ENDPOINT\n    # (e.g., docker run -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:latest --config=/etc/otel-collector-config.yaml)\n    # The collector config should include otlp receiver and a logging/debug exporter.\n    app.run(port=5001, debug=False, use_reloader=False)\n","lang":"python","description":"To quickly get started, install `opentelemetry-distro[otlp]` and then run `opentelemetry-bootstrap -a install` to automatically install instrumentations for detected libraries. Then, run your application using the `opentelemetry-instrument` wrapper script. This example demonstrates a simple Flask application that makes an HTTP request, which will be automatically traced. Ensure an OpenTelemetry Collector is running to receive telemetry data. For Flask/Django, set `use_reloader=False` (Flask) or use `--noreload` (Django) to avoid instrumentation issues."},"warnings":[{"fix":"Review release notes carefully before upgrading. Test new versions thoroughly in non-production environments.","message":"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.","severity":"gotcha","affected_versions":"0.x.x (all beta versions)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Identify your target observability backend and consult its specific OpenTelemetry documentation. Install the appropriate vendor-specific distro if one exists and is recommended.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T22:30:09.508Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed using pip: `pip install opentelemetry-distro` and that your virtual environment is activated if applicable.","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.","error":"ModuleNotFoundError: No module named 'opentelemetry_distro'"},{"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`.","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.","error":"ModuleNotFoundError: No module named 'opentelemetry.exporter.otlp.proto.grpc'"},{"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.","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.","error":"OTLP Exporter: Failed to connect"},{"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.","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.","error":"No traces appearing"},{"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.","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.","error":"AttributeError: module 'opentelemetry.sdk.trace' has no attribute 'SpanLimits'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.62b1","cli_name":"opentelemetry-bootstrap","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":5.5,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":4.9,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":4,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":4,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":"dependency_conflict","install_time_s":6.5,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"otlp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":2},{"runtime":"python:3.10-slim","exit_code":2},{"runtime":"python:3.11-alpine","exit_code":2},{"runtime":"python:3.11-slim","exit_code":2},{"runtime":"python:3.12-alpine","exit_code":2},{"runtime":"python:3.12-slim","exit_code":2},{"runtime":"python:3.13-alpine","exit_code":2},{"runtime":"python:3.13-slim","exit_code":2},{"runtime":"python:3.9-alpine","exit_code":2},{"runtime":"python:3.9-slim","exit_code":2}]}}