{"id":9157,"library":"opentelemetry-contrib-instrumentations","title":"OpenTelemetry Contrib Instrumentation Packages","description":"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.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["observability","opentelemetry","tracing","metrics","instrumentation","auto-instrumentation","contrib"],"install":[{"cmd":"pip install opentelemetry-contrib-instrumentations opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-distro","lang":"bash","label":"Install all contrib instrumentations, SDK, OTLP exporter, and distro"}],"dependencies":[{"reason":"Core OpenTelemetry API, fundamental for any OTel usage.","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK, required for processing and exporting telemetry.","package":"opentelemetry-sdk","optional":false},{"reason":"This is a metapackage that installs many individual instrumentation packages (e.g., `opentelemetry-instrumentation-requests`).","package":"opentelemetry-instrumentation-*","optional":false}],"imports":[{"note":"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.","wrong":"from opentelemetry_contrib_instrumentations import RequestsInstrumentor","symbol":"RequestsInstrumentor","correct":"from opentelemetry.instrumentation.requests import RequestsInstrumentor"},{"note":"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`.","wrong":"from opentelemetry_contrib_instrumentations import configure_instrumentations","symbol":"configure_opentelemetry","correct":"from opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.distro import OpenTelemetryDistro\n\ndef configure_opentelemetry(service_name: str):\n    resource = Resource.create({\"service.name\": service_name})\n    tracer_provider = TracerProvider(resource=resource)\n    span_processor = SimpleSpanProcessor(ConsoleSpanExporter())\n    tracer_provider.add_span_processor(span_processor)\n    \n    # Set the global tracer provider\n    from opentelemetry import trace\n    trace.set_tracer_provider(tracer_provider)\n\n    # Instrument all installed contrib instrumentations\n    distro = OpenTelemetryDistro()\n    distro.instrument()\n    # Or, to instrument specific packages:\n    # from opentelemetry.instrumentation.requests import RequestsInstrumentor\n    # RequestsInstrumentor().instrument()"}],"quickstart":{"code":"import os\nimport requests\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.requests import RequestsInstrumentor\n\n# Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": os.environ.get('OTEL_SERVICE_NAME', 'my-python-app')})\ntracer_provider = TracerProvider(resource=resource)\nspan_processor = SimpleSpanProcessor(ConsoleSpanExporter())\ntracer_provider.add_span_processor(span_processor)\ntrace.set_tracer_provider(tracer_provider)\n\n# Instrument the requests library\nRequestsInstrumentor().instrument()\n\n# Make an HTTP request that will be traced\ndef make_request():\n    print(\"Making an HTTP request...\")\n    response = requests.get(\"https://www.example.com\")\n    print(f\"Request completed with status: {response.status_code}\")\n\nif __name__ == \"__main__\":\n    make_request()\n\n# To run this, install:\n# pip install opentelemetry-sdk opentelemetry-exporter-console opentelemetry-instrumentation-requests requests","lang":"python","description":"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."},"warnings":[{"fix":"Review changelogs carefully when upgrading, especially for individual instrumentation packages. Pin versions of critical instrumentations.","message":"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.","severity":"beta","affected_versions":"All versions up to 0.62b0"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, consult individual instrumentation changelogs"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"The specific `opentelemetry-instrumentation-flask` package (or any other instrumentation) was not installed, or was removed by a package manager like `uv`.","error":"ModuleNotFoundError: No module named 'opentelemetry.instrumentation.flask'"},{"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.","cause":"The instrumentor's `.instrument()` method was not called, or a reloader (like Flask's debug mode) is interfering with instrumentation.","error":"My application is running, but I'm not seeing any traces/metrics in the console or my backend."},{"fix":"Import `Instrumentor` classes from their dedicated package, e.g., `from opentelemetry.instrumentation.requests import RequestsInstrumentor` instead of `from opentelemetry_contrib_instrumentations import RequestsInstrumentor`.","cause":"Attempting to import an `Instrumentor` class directly from the `opentelemetry-contrib-instrumentations` metapackage.","error":"TypeError: 'type' object is not subscriptable (when importing from opentelemetry_contrib_instrumentations)"}]}