Registry /
observability / opentelemetry-instrumentation-aiohttp-server
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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 32.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.1s · import 0.000s · 35MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AiohttpServerInstrumentor
✓ from opentelemetry.instrumentation.aiohttp_server import AiohttpServerInstrumentor
This quickstart demonstrates how to instrument an `aiohttp` server with OpenTelemetry. It sets up a basic `TracerProvider` that exports spans to the console, instruments the `aiohttp` framework, defines two simple routes, and then runs the server. Requests to `/` and `/health` will generate traces showing the incoming request and any custom spans within the handler logic.
import sys
import asyncio
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.aiohttp_server import AiohttpServerInstrumentor
from aiohttp import web
# 1. Configure OpenTelemetry Tracer Provider
resource = Resource.create({"service.name": "aiohttp-server-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter(sys.stdout))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument the aiohttp server
AiohttpServerInstrumentor().instrument()
# 3. Define a simple aiohttp application
async def hello_handler(request):
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("hello-endpoint-logic"):
await asyncio.sleep(0.05) # Simulate some async work
return web.Response(text="Hello, OpenTelemetry aiohttp!")
async def health_check_handler(request):
return web.Response(text="OK")
app = web.Application()
app.router.add_get("/", hello_handler)
app.router.add_get("/health", health_check_handler)
# 4. Run the aiohttp server
if __name__ == '__main__':
print("Server starting on http://localhost:8080")
print("Try: curl http://localhost:8080")
web.run_app(app, host="localhost", port=8080)
Debug
Known issues
gotchaThis instrumentation package is currently in a beta (`b0`) state, indicated by its version `0.62b0`. While generally stable, its API or behavior may undergo breaking changes in minor releases without strict adherence to semantic versioning.fixAlways review the release notes when upgrading to new beta versions. Pin your dependency versions to prevent unexpected updates (`opentelemetry-instrumentation-aiohttp-server==0.62b0`).
affects: All `0.x.xb0` versions
gotchaThe `AiohttpServerInstrumentor` requires explicit instantiation and calling of its `instrument()` method. It is not automatically enabled by `opentelemetry-bootstrap` or similar mechanisms, requiring you to add this code to your application's startup.fixEnsure `AiohttpServerInstrumentor().instrument()` is called early in your application's lifecycle, before the `aiohttp` application is fully initialized or starts processing requests.
affects: All versions
gotchaOpenTelemetry requires a configured `TracerProvider` to be set globally before any instrumentation can effectively create and export spans. Forgetting this setup will result in no traces being generated, even if instrumentation is enabled.fixAlways initialize and set a global `TracerProvider` (e.g., using `trace.set_tracer_provider`) along with a `SpanProcessor` and `SpanExporter` at the very start of your application.
affects: All versions
gotchaIn complex `aiohttp` applications, especially those with custom middlewares, the order of middleware registration can affect how traces are generated. If other middlewares modify the request too early, some attributes or context might be missed by the OpenTelemetry instrumentation.fixPlace the OpenTelemetry instrumentation setup (calling `instrument()`) as early as possible in your application's startup, typically before defining or registering any other `aiohttp` middlewares if possible, or ensure OTel middleware is applied before others that might obscure request details.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
aiohttprequiredThis is the web framework being instrumented.
opentelemetry-apirequiredRequired for core OpenTelemetry APIs.
opentelemetry-sdkrequiredRequired for OpenTelemetry SDK implementation (e.g., TracerProvider).