# Tracing Reference

New in version 3.0.

A reference for client tracing API.

See also

Client Tracing for tracing usage instructions.

## Request life cycle

A request goes through the following stages and corresponding fallbacks.

### Overview

Name | Description
--- | ---
start | on_request_start
redirect | on_request_redirect
acquire_connection | Connection acquiring
headers_received |
exception | on_request_exception
end | on_request_end
headers_sent | on_request_headers_sent
chunk_sent | on_request_chunk_sent
chunk_received | on_response_chunk_received

### Connection acquiring

Name | Description
--- | ---
begin |
end |
queued_start | on_connection_queued_start
create_start | on_connection_create_start
reuseconn | on_connection_reuseconn
queued_end | on_connection_queued_end
create_end | on_connection_create_end
exception | Exception raised
resolve_dns | DNS resolving
sock_connect | Connection establishment

### DNS resolving

Name | Description
--- | ---
begin |
end |
exception | Exception raised
resolve_end | on_dns_resolvehost_end
resolve_start | on_dns_resolvehost_start
cache_hit | on_dns_cache_hit
cache_miss | on_dns_cache_miss

## Classes

class aiohttp.TraceConfig(trace_config_ctx_factory=SimpleNamespace)

  Trace config is the configuration object used to trace requests launched by a `ClientSession` object using different events related to different parts of the request flow.

  Parameters:

    trace_config_ctx_factory – factory used to create trace contexts, default class used `types.SimpleNamespace`

  trace_config_ctx(trace_request_ctx=None)
    Parameters:

      trace_request_ctx – Will be used to pass as a kw for the `trace_config_ctx_factory`.

    Build a new trace context from the config.

  Every signal handler should have the following signature:

      async def on_signal(session, context, params): ...

  where `session` is `ClientSession` instance, `context` is an object returned by `trace_config_ctx()` call and `params` is a data class with signal parameters. The type of `params` depends on subscribed signal and described below.

  on_request_start

    Property that gives access to the signals that will be executed when a request starts.

    `params` is `aiohttp.TraceRequestStartParams` instance.

  on_request_chunk_sent

    Property that gives access to the signals that will be executed when a chunk of request body is sent.

    `params` is `aiohttp.TraceRequestChunkSentParams` instance.

    New in version 3.1.

  on_response_chunk_received

    Property that gives access to the signals that will be executed when a chunk of response body is received.

    `params` is `aiohttp.TraceResponseChunkReceivedParams` instance.

    New in version 3.1.

  on_request_redirect

    Property that gives access to the signals that will be executed when a redirect happens during a request flow.

    `params` is `aiohttp.TraceRequestRedirectParams` instance.

  on_request_end

    Property that gives access to the signals that will be executed when a request ends.

    `params` is `aiohttp.TraceRequestEndParams` instance.

  on_request_exception

    Property that gives access to the signals that will be executed when a request finishes with an exception.

    `params` is `aiohttp.TraceRequestExceptionParams` instance.

  on_connection_queued_start

    Property that gives access to the signals that will be executed when a request has been queued waiting for an available connection.

    `params` is `aiohttp.TraceConnectionQueuedStartParams` instance.

  on_connection_queued_end

    Property that gives access to the signals that will be executed when a request that was queued already has an available connection.

    `params` is `aiohttp.TraceConnectionQueuedEndParams` instance.

  on_connection_create_start

    Property that gives access to the signals that will be executed when a request creates a new connection.

    `params` is `aiohttp.TraceConnectionCreateStartParams` instance.

  on_connection_create_end

    Property that gives access to the signals that will be executed when a request that created a new connection finishes its creation.

    `params` is `aiohttp.TraceConnectionCreateEndParams` instance.

  on_connection_reuseconn

    Property that gives access to the signals that will be executed when a request reuses a connection.

    `params` is `aiohttp.TraceConnectionReuseconnParams` instance.

  on_dns_resolvehost_start

    Property that gives access to the signals that will be executed when a request starts to resolve the domain related with the request.

    `params` is `aiohttp.TraceDnsResolveHostStartParams` instance.

  on_dns_resolvehost_end

    Property that gives access to the signals that will be executed when a request finishes to resolve the domain related with the request.

    `params` is `aiohttp.TraceDnsResolveHostEndParams` instance.

  on_dns_cache_hit

    Property that gives access to the signals that will be executed when a request was able to use a cached DNS resolution for the domain related with the request.

    `params` is `aiohttp.TraceDnsCacheHitParams` instance.

  on_dns_cache_miss

    Property that gives access to the signals that will be executed when a request was not able to use a cached DNS resolution for the domain related with the request.

    `params` is `aiohttp.TraceDnsCacheMissParams` instance.

  on_request_headers_sent

    Property that gives access to the signals that will be executed when request headers are sent.

    `params` is `aiohttp.TraceRequestHeadersSentParams` instance.

    New in version 3.8.

class aiohttp.TraceRequestStartParams

  See `TraceConfig.on_request_start` for details.

  method

    Method that will be used to make the request.

  url

    URL that will be used for the request.

  headers

    Headers that will be used for the request, can be mutated.

class aiohttp.TraceRequestChunkSentParams

  New in version 3.1.

  See `TraceConfig.on_request_chunk_sent` for details.

  method

    Method that will be used to make the request.

  url

    URL that will be used for the request.

  chunk

    Bytes of chunk sent

class aiohttp.TraceResponseChunkReceivedParams

  New in version 3.1.

  See `TraceConfig.on_response_chunk_received` for details.

  method

    Method that will be used to make the request.

  url

    URL that will be used for the request.

  chunk

    Bytes of chunk received

class aiohttp.TraceRequestEndParams

  See `TraceConfig.on_request_end` for details.

  method

    Method used to make the request.

  url

    URL used for the request.

  headers

    Headers used for the request.

  response

    Response `ClientResponse`.

class aiohttp.TraceRequestExceptionParams

  See `TraceConfig.on_request_exception` for details.

  method

    Method used to make the request.

  url

    URL used for the request.

  headers

    Headers used for the request.

  exception

    Exception raised during the request.

class aiohttp.TraceRequestRedirectParams

  See `TraceConfig.on_request_redirect` for details.

  method

    Method used to get this redirect request.

  url

    URL used for this redirect request.

  headers

    Headers used for this redirect.

  response

    Response `ClientResponse` got from the redirect.

class aiohttp.TraceConnectionQueuedStartParams

  See `TraceConfig.on_connection_queued_start` for details.

  There are no attributes right now.

class aiohttp.TraceConnectionQueuedEndParams

  See `TraceConfig.on_connection_queued_end` for details.

  There are no attributes right now.

class aiohttp.TraceConnectionCreateStartParams

  See `TraceConfig.on_connection_create_start` for details.

  There are no attributes right now.

class aiohttp.TraceConnectionCreateEndParams

  See `TraceConfig.on_connection_create_end` for details.

  There are no attributes right now.

class aiohttp.TraceConnectionReuseconnParams

  See `TraceConfig.on_connection_reuseconn` for details.

  There are no attributes right now.

class aiohttp.TraceDnsResolveHostStartParams

  See `TraceConfig.on_dns_resolvehost_start` for details.

  host

    Host that will be resolved.

class aiohttp.TraceDnsResolveHostEndParams

  See `TraceConfig.on_dns_resolvehost_end` for details.

  host

    Host that has been resolved.

class aiohttp.TraceDnsCacheHitParams

  See `TraceConfig.on_dns_cache_hit` for details.

  host

    Host found in the cache.

class aiohttp.TraceDnsCacheMissParams

  See `TraceConfig.on_dns_cache_miss` for details.

  host

    Host didn’t find the cache.

class aiohttp.TraceRequestHeadersSentParams

  See `TraceConfig.on_request_headers_sent` for details.

  New in version 3.8.

  method

    Method that will be used to make the request.

  url

    URL that will be used for the request.

  headers

    Headers that will be used for the request.