OpenTelemetry aiohttp Server Instrumentation

opentelemetry-instrumentation-aiohttp-server is an OpenTelemetry instrumentation library that automatically captures distributed tracing data for HTTP requests served by an aiohttp web application. Once enabled, every inbound request is wrapped in a span carrying HTTP method, target, route, and status-code attributes following OpenTelemetry semantic conventions.

It is part of the opentelemetry-python-contrib project and plugs into the standard OpenTelemetry API and SDK, so aiohttp server traces flow to any configured exporter (OTLP, Jaeger, Zipkin) alongside the rest of your service’s telemetry with no manual span management.

What You Get

• Automatic span creation for every inbound aiohttp server request
• HTTP semantic-convention attributes (method, target, route, status code) on each span
• Context propagation so upstream trace context continues through the aiohttp handler
• Integration with the OpenTelemetry API/SDK and any configured exporter
• A simple middleware-based enablement that requires no changes to request handlers

Common Use Cases

• Adding distributed tracing to an aiohttp-based microservice
• Measuring per-route latency and error rates for aiohttp endpoints
• Correlating aiohttp request spans with downstream database and HTTP client calls

Under The Hood

Architecture - The package lives at instrumentation/opentelemetry-instrumentation-aiohttp-server within the opentelemetry-python-contrib monorepo. It exposes an instrumentor under opentelemetry.instrumentation.aiohttp_server that installs aiohttp server middleware; the middleware starts a SERVER-kind span per request, extracts inbound propagation headers, sets HTTP semantic-convention attributes, and closes the span with the response status.

Tech Stack - Pure Python, depending on opentelemetry-api (~=1.12), opentelemetry-instrumentation, opentelemetry-semantic-conventions, opentelemetry-util-http, and wrapt for wrapping. It targets the aiohttp server and emits through whatever OpenTelemetry SDK and exporter the host application configures.

Code Quality - Maintained under the well-governed opentelemetry-python-contrib project (Apache-2.0), which enforces shared CI, linting, and a large cross-instrumentation test suite. The instrumentation module is small and focused, reusing common helpers from opentelemetry-util-http for URL and header handling.

API Design - Enabling tracing is a one-call operation via the instrumentor plus standard aiohttp middleware wiring; it follows the uniform BaseInstrumentor pattern shared across all contrib packages, so developers already using OpenTelemetry pick it up with no new concepts.