{"library":"opentelemetry-instrumentation-aiohttp-client","title":"OpenTelemetry aiohttp Client Instrumentation","description":"The `opentelemetry-instrumentation-aiohttp-client` package enables distributed tracing for HTTP requests made using the `aiohttp` client library. It is part of the `opentelemetry-python-contrib` project, currently at version `0.61b0`, and follows a monthly release cadence, aligned with the broader OpenTelemetry Python Contrib releases.","status":"active","version":"0.61b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","tracing","instrumentation","aiohttp","client","observability","asyncio"],"install":[{"cmd":"pip install opentelemetry-instrumentation-aiohttp-client aiohttp","lang":"bash","label":"Install library and aiohttp"}],"dependencies":[{"reason":"The library being instrumented.","package":"aiohttp"},{"reason":"OpenTelemetry Python API for tracing.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry Python SDK for trace processing.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"AioHttpClientInstrumentor","correct":"from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor"}],"quickstart":{"code":"import asyncio\nimport aiohttp\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor\nfrom opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor\n\n# 1. Initialize OpenTelemetry SDK (must happen before instrumenting libraries)\nprovider = TracerProvider()\nprocessor = BatchSpanProcessor(ConsoleSpanExporter()) # Use OTLPSpanExporter for real usage\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument aiohttp client\nAioHttpClientInstrumentor().instrument()\n\nasync def fetch_url(session, url):\n    async with session.get(url) as response:\n        # Accessing response.status and response.text() will also be part of the trace\n        print(f\"Fetched {url} with status {response.status}\")\n        return await response.text()\n\nasync def main():\n    print(\"Making a traced aiohttp client request...\")\n    async with aiohttp.ClientSession() as session:\n        # This request will be automatically traced\n        await fetch_url(session, \"http://httpbin.org/get?param=value\")\n    print(\"Request complete.\")\n\nif __name__ == \"__main__\":\n    # Ensure an event loop is running for aiohttp\n    asyncio.run(main())\n","lang":"python","description":"This example demonstrates how to set up the OpenTelemetry SDK with a console exporter and then automatically instrument all `aiohttp.ClientSession` requests. The `AioHttpClientInstrumentor().instrument()` call should occur after the SDK is initialized to ensure proper tracing."},"warnings":[{"fix":"Consult the official OpenTelemetry Python Contrib CHANGELOG and documentation for each upgrade, especially for changes to semantic conventions.","message":"The library is currently in beta (`0.61b0`). While functional, its API and semantic conventions may undergo breaking changes in future releases before reaching a stable 1.0 version.","severity":"gotcha","affected_versions":"All versions < 1.0"},{"fix":"Always initialize your OpenTelemetry SDK at the earliest possible point in your application's lifecycle, typically at startup, before any instrumented libraries are used or configured.","message":"Ensure the OpenTelemetry SDK (`opentelemetry-sdk`) is fully initialized, including setting a `TracerProvider` and `SpanProcessor`, *before* calling `AioHttpClientInstrumentor().instrument()` to prevent missing telemetry or errors. Improper initialization order is a common cause of no telemetry data.","severity":"breaking","affected_versions":"All versions"},{"fix":"Regularly review the OpenTelemetry Python Contrib documentation and the OpenTelemetry semantic conventions specification for HTTP to stay updated on current and deprecated attributes. Consider using schema URL configuration if supported by your collector.","message":"OpenTelemetry semantic conventions for HTTP are subject to evolution and migration. Attribute names (e.g., `http.method`, `http.url`) may change across versions, potentially breaking dashboards or alerts relying on older conventions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To enable header capture, set environment variables like `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST='Content-Type,X-Custom-Header'` and `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE='Content-Type,Server'`. To redact sensitive header values, use `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS='Authorization,Cookie,Set-Cookie'` with a comma-delimited list of header names/regex patterns.","message":"By default, HTTP request and response headers are not captured as span attributes due to potential sensitive information.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the environment variable `OTEL_PYTHON_AIOHTTP_CLIENT_EXCLUDED_URLS` (specific to aiohttp client) or `OTEL_PYTHON_EXCLUDED_URLS` (global for Python instrumentations) to a comma-delimited string of regular expressions that match the URLs to be excluded (e.g., `'^.*/healthcheck,^.*/metrics'`).","message":"To exclude specific URLs from being traced, which is useful for health checks or high-volume non-critical endpoints, you need to configure an exclusion list.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}