Registry /
observability / opentelemetry-instrumentation-asgi
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.394s · 24.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.9s · import 0.376s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenTelemetryMiddleware
✓ from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
This quickstart demonstrates how to instrument a basic ASGI application using `OpenTelemetryMiddleware`. It configures a simple OpenTelemetry SDK with a console exporter to print traces directly to the terminal. After running the `uvicorn` command, accessing the application will generate and display trace information.
import os
import uvicorn
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.asgi import OpenTelemetryMiddleware
# Configure OpenTelemetry SDK
resource = Resource.create({"service.name": "my-asgi-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Define a simple ASGI application
async def hello_world_app(scope, receive, send):
assert scope['type'] == 'http'
await send({
'type': 'http.response.start',
'status': 200,
'headers': [
(b'content-type', b'text/plain'),
],
})
await send({
'type': 'http.response.body',
'body': b'Hello, OpenTelemetry World!'
})
# Instrument the ASGI application
instrumented_app = OpenTelemetryMiddleware(hello_world_app)
# To run this example:
# 1. Save as 'app.py'
# 2. Run: uvicorn app:instrumented_app --port 8000
# 3. Access http://localhost:8000/ in your browser.
# You will see trace output in the console where uvicorn is running.
# Note: This is an embedded example. In a real application, you would typically
# apply the middleware to your framework's app instance (e.g., FastAPI, Starlette).
# For example, for FastAPI:
# from fastapi import FastAPI
# app = FastAPI()
# app.add_middleware(OpenTelemetryMiddleware)
opentelemetry-instrumentation --version
Debug
Known issues
gotchaThe `opentelemetry-instrumentation-asgi` package is currently in beta. While actively developed, its API and behavior may change before a stable `1.0` release. It is not generally recommended for production environments where stability is critical.fixBe aware of potential breaking changes in minor updates. For production, consider using stable, manually instrumented components or a more mature OpenTelemetry language agent.
affects: All beta versions (e.g., <1.0.0)
breakingStarting with version `0.61b0`, `SpanAttributes` were replaced with semantic convention constants. Directly referencing `SpanAttributes` might lead to `AttributeError` or incorrect attribute names.fixUpdate your code to use constants from `opentelemetry.semconv.trace` or similar `semconv` modules, or rely on automatic instrumentation to apply correct semantic conventions.
affects: >=0.61b0
gotchaWhen using pre-fork servers like Gunicorn with multiple workers, OpenTelemetry's automatic metric generation might break. This is due to how child processes handle background threads and locks. Tracing usually remains functional, and Uvicorn with multiple workers is supported for both traces and metrics.fixFor Gunicorn, consider running with a single worker (`--workers 1`), or use programmatic auto-instrumentation. If using Uvicorn with multiple workers, ensure your setup is compatible with OpenTelemetry's recommendations.
affects: All versions
gotchaTo capture HTTP request and response headers as span attributes, specific environment variables must be set (e.g., `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST`, `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`). Headers are case-insensitive.fixSet environment variables like `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST='Content-Type,X-Request-ID'` or `'.*'` to capture all headers (use with caution). The attribute names will be `http.request.header.<header_name>`.
affects: All versions
gotchaThe `opentelemetry-instrumentation-asgi` package does not provide a `fastapi` extra. FastAPI instrumentation is typically provided by a separate package, `opentelemetry-instrumentation-fastapi`. Attempting to install `opentelemetry-instrumentation-asgi[fastapi]` will result in a warning.fixIf FastAPI instrumentation is needed, install `opentelemetry-instrumentation-fastapi` as a separate package. Avoid using `[fastapi]` when installing `opentelemetry-instrumentation-asgi`.
affects: All versions of `opentelemetry-instrumentation-asgi` that do not explicitly declare a `fastapi` extra (which appears to be current behavior).
gotchaThe `opentelemetry-instrumentation-asgi` package does not officially provide a `fastapi` extra. Attempting to install it with `[fastapi]` will result in a warning indicating that the extra is not found and will only install the base package dependencies.fixAvoid using the `[fastapi]` extra. If FastAPI-specific instrumentation is required, check the OpenTelemetry documentation for alternative, dedicated FastAPI instrumentation packages or rely on the base ASGI instrumentation.
affects: 0.62b0 and potentially other versions where `fastapi` extra is not explicitly defined.
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API, fundamental for all instrumentation.
opentelemetry-sdkrequiredOpenTelemetry SDK for processing and exporting telemetry data (required for a functional setup).
opentelemetry-instrumentationrequiredBase classes and utilities for OpenTelemetry instrumentation.
opentelemetry-semantic-conventionsrequiredDefines standard attribute names for OpenTelemetry telemetry.
opentelemetry-util-httprequiredShared utilities for HTTP-related instrumentations.
asgi-compatible-frameworkoptionalRequires an ASGI framework like FastAPI, Starlette, Quart, or Django-channels to function, but these are application dependencies, not direct Python package dependencies.