OpenTelemetry aiohttp client Instrumentation

The opentelemetry-instrumentation-aiohttp-client package allows tracing HTTP requests made by the aiohttp client library.


Explicitly instrumenting a single client session:

import aiohttp
from opentelemetry.instrumentation.aiohttp_client import (
import yarl

def strip_query_params(url: yarl.URL) -> str:
    return str(url.with_query(None))

async with aiohttp.ClientSession(trace_configs=[create_trace_config(
        # Remove all query params from the URL attribute on the span.
        # Use the URL's path as the span name.
)]) as session:
    async with session.get(url) as response:
        await response.text()

Instrumenting all client sessions:

import aiohttp
from opentelemetry.instrumentation.aiohttp_client import (

# Enable instrumentation

# Create a session and make an HTTP get request
async with aiohttp.ClientSession() as session:
    async with session.get(url) as response:
        await response.text()


Request/Response hooks

Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request.

def request_hook(span: Span, params: aiohttp.TraceRequestStartParams):
   if span and span.is_recording():
         span.set_attribute("custom_user_attribute_from_request_hook", "some-value")

def response_hook(span: Span, params: typing.Union[
     if span and span.is_recording():
         span.set_attribute("custom_user_attribute_from_response_hook", "some-value")

AioHttpClientInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)



Extract a span name from the request URL path.

A simple callable to extract the path portion of the requested URL for use as the span name.


params (aiohttp.TraceRequestStartParams) – Parameters describing the traced request.


The URL path.

Return type


opentelemetry.instrumentation.aiohttp_client.create_trace_config(url_filter=None, request_hook=None, response_hook=None, tracer_provider=None)[source]

Create an aiohttp-compatible trace configuration.

One span is created for the entire HTTP request, including initial TCP/TLS setup if the connection doesn’t exist.

By default the span name is set to the HTTP request method.

Example usage:

import aiohttp
from opentelemetry.instrumentation.aiohttp_client import create_trace_config

async with aiohttp.ClientSession(trace_configs=[create_trace_config()]) as session:
    async with session.get(url) as response:
        await response.text()
  • url_filter (Optional[Callable[[str], str]]) – A callback to process the requested URL prior to adding it as a span attribute. This can be useful to remove sensitive data such as API keys or user personal information.

  • request_hook (Callable) – Optional callback that can modify span name and request params.

  • response_hook (Callable) – Optional callback that can modify span name and response params.

  • tracer_provider (Optional[TracerProvider]) – optional TracerProvider from which to get a Tracer


An object suitable for use with aiohttp.ClientSession.

Return type


class opentelemetry.instrumentation.aiohttp_client.AioHttpClientInstrumentor(*args, **kwargs)[source]

Bases: opentelemetry.instrumentation.instrumentor.BaseInstrumentor

An instrumentor for aiohttp client sessions

See BaseInstrumentor


Return a list of python packages with versions that the will be instrumented.

The format should be the same as used in requirements.txt or

For example, if an instrumentation instruments requests 1.x, this method should look like:

def instrumentation_dependencies(self) -> Collection[str]:

return [‘requests ~= 1.0’]

This will ensure that the instrumentation will only be used when the specified library is present in the environment.

Return type


static uninstrument_session(client_session)[source]

Disables instrumentation for the given session