Registry / observability / opentelemetry-instrumentation-aiohttp-client

opentelemetry-instrumentation-aiohttp-client

JSON →
library0.65b0pypypi✓ verified 24d ago

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.

pip install opentelemetry-instrumentation-aiohttp-client aiohttp
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-aiohttp-client
observabilitypythonv0.65b0
Install
4.9s avg
Import
709ms
Disk
32MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.752s · 31.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.9s · import 0.666s · 34MB
32MB installed
● package 32MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AioHttpClientInstrumentor
from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor

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())
Debug
Known issues
gotchaThe 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.
affects: All versions < 1.0
breakingEnsure 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.
affects: All versions
gotchaOpenTelemetry 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.
affects: All versions
gotchaBy 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.
affects: All versions
gotchaTo 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'`).
affects: All versions
breakingThe OpenTelemetry SDK (`opentelemetry-sdk`) is a mandatory core dependency and must be installed for any OpenTelemetry instrumentation, including `opentelemetry-instrumentation-aiohttp-client`, to function.
fix
Install the OpenTelemetry SDK package: `pip install opentelemetry-sdk`
affects: All versions
breakingThe `opentelemetry-sdk` package, a core dependency for any OpenTelemetry instrumentation, must be installed in your environment. Failing to install this package will result in `ModuleNotFoundError`.
fix
Ensure `opentelemetry-sdk` is included in your project's dependencies (e.g., `pip install opentelemetry-sdk opentelemetry-api` or listed in `requirements.txt`). This package is distinct from `opentelemetry-instrumentation-aiohttp-client`.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
aiohttprequiredThe library being instrumented.
opentelemetry-apirequiredOpenTelemetry Python API for tracing.
opentelemetry-sdkrequiredOpenTelemetry Python SDK for trace processing.
Agent activity
14 hits · last 30 days
node
10
OpenAI (training)
2
Amazon
1
Resources