OpenTelemetry aiohttp Client Instrumentation

Warnings

• gotcha 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.
  Fix: Consult the official OpenTelemetry Python Contrib CHANGELOG and documentation for each upgrade, especially for changes to semantic conventions.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha By default, HTTP request and response headers are not captured as span attributes due to potential sensitive information.
  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.
• gotcha 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.
  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'`).

Install

• pip install opentelemetry-instrumentation-aiohttp-client aiohttp Install library and aiohttp

Imports

• AioHttpClientInstrumentor

  from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor

Quickstart

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.

import asyncio
import aiohttp
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor

# 1. Initialize OpenTelemetry SDK (must happen before instrumenting libraries)
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter()) # Use OTLPSpanExporter for real usage
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 2. Instrument aiohttp client
AioHttpClientInstrumentor().instrument()

async def fetch_url(session, url):
    async with session.get(url) as response:
        # Accessing response.status and response.text() will also be part of the trace
        print(f"Fetched {url} with status {response.status}")
        return await response.text()

async def main():
    print("Making a traced aiohttp client request...")
    async with aiohttp.ClientSession() as session:
        # This request will be automatically traced
        await fetch_url(session, "http://httpbin.org/get?param=value")
    print("Request complete.")

if __name__ == "__main__":
    # Ensure an event loop is running for aiohttp
    asyncio.run(main())