OpenTelemetry Aiohttp Server Instrumentation

Warnings

• gotcha 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.
  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`).
• gotcha 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.
  Fix: Ensure `AiohttpServerInstrumentor().instrument()` is called early in your application's lifecycle, before the `aiohttp` application is fully initialized or starts processing requests.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install opentelemetry-instrumentation-aiohttp-server opentelemetry-sdk aiohttp Install core, sdk, and instrumentation

Imports

• AiohttpServerInstrumentor

  from opentelemetry.instrumentation.aiohttp_server import AiohttpServerInstrumentor

Quickstart

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)