{"id":4669,"library":"opentelemetry-instrumentation-aiohttp-server","title":"OpenTelemetry Aiohttp Server Instrumentation","description":"This library provides instrumentation for aiohttp servers, enabling automatic tracing of incoming HTTP requests and responses using OpenTelemetry. It's part of the `opentelemetry-python-contrib` project, currently at version `0.62b0`, and generally follows the release cadence of the broader OpenTelemetry Python Contrib repository, with frequent beta updates.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aiohttp-server","tags":["opentelemetry","tracing","observability","aiohttp","instrumentation","server","async"],"install":[{"cmd":"pip install opentelemetry-instrumentation-aiohttp-server opentelemetry-sdk aiohttp","lang":"bash","label":"Install core, sdk, and instrumentation"}],"dependencies":[{"reason":"This is the web framework being instrumented.","package":"aiohttp","optional":false},{"reason":"Required for core OpenTelemetry APIs.","package":"opentelemetry-api","optional":false},{"reason":"Required for OpenTelemetry SDK implementation (e.g., TracerProvider).","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"AiohttpServerInstrumentor","correct":"from opentelemetry.instrumentation.aiohttp_server import AiohttpServerInstrumentor"}],"quickstart":{"code":"import sys\nimport asyncio\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.aiohttp_server import AiohttpServerInstrumentor\nfrom aiohttp import web\n\n# 1. Configure OpenTelemetry Tracer Provider\nresource = Resource.create({\"service.name\": \"aiohttp-server-app\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter(sys.stdout))\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument the aiohttp server\nAiohttpServerInstrumentor().instrument()\n\n# 3. Define a simple aiohttp application\nasync def hello_handler(request):\n    tracer = trace.get_tracer(__name__)\n    with tracer.start_as_current_span(\"hello-endpoint-logic\"): \n        await asyncio.sleep(0.05) # Simulate some async work\n        return web.Response(text=\"Hello, OpenTelemetry aiohttp!\")\n\nasync def health_check_handler(request):\n    return web.Response(text=\"OK\")\n\napp = web.Application()\napp.router.add_get(\"/\", hello_handler)\napp.router.add_get(\"/health\", health_check_handler)\n\n# 4. Run the aiohttp server\nif __name__ == '__main__':\n    print(\"Server starting on http://localhost:8080\")\n    print(\"Try: curl http://localhost:8080\")\n    web.run_app(app, host=\"localhost\", port=8080)\n","lang":"python","description":"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."},"warnings":[{"fix":"Always review the release notes when upgrading to new beta versions. Pin your dependency versions to prevent unexpected updates (`opentelemetry-instrumentation-aiohttp-server==0.62b0`).","message":"This 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.","severity":"gotcha","affected_versions":"All `0.x.xb0` versions"},{"fix":"Ensure `AiohttpServerInstrumentor().instrument()` is called early in your application's lifecycle, before the `aiohttp` application is fully initialized or starts processing requests.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always 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.","message":"OpenTelemetry 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Place 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.","message":"In 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}