Tracing Reference

Added 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

digraph {

  start[shape=point, xlabel="start", width="0.1"];
  redirect[shape=box];
  end[shape=point, xlabel="end  ", width="0.1"];
  exception[shape=oval];

  acquire_connection[shape=box];
  headers_received[shape=box];
  headers_sent[shape=box];
  chunk_sent[shape=box];
  chunk_received[shape=box];

  start -> acquire_connection;
  acquire_connection -> headers_sent;
  headers_sent -> headers_received;
  headers_sent -> chunk_sent;
  chunk_sent -> chunk_sent;
  chunk_sent -> headers_received;
  headers_received -> chunk_received;
  chunk_received -> chunk_received;
  chunk_received -> end;
  headers_received -> redirect;
  headers_received -> end;
  redirect -> headers_sent;
  chunk_received -> exception;
  chunk_sent -> exception;
  headers_sent -> exception;

}

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

digraph {

  begin[shape=point, xlabel="begin", width="0.1"];
  end[shape=point, xlabel="end ", width="0.1"];
  exception[shape=oval];

  queued_start[shape=box];
  queued_end[shape=box];
  create_start[shape=box];
  create_end[shape=box];
  reuseconn[shape=box];
  resolve_dns[shape=box];
  sock_connect[shape=box];

  begin -> reuseconn;
  begin -> create_start;
  create_start -> resolve_dns;
  resolve_dns -> exception;
  resolve_dns -> sock_connect;
  sock_connect -> exception;
  sock_connect -> create_end -> end;
  begin -> queued_start;
  queued_start -> queued_end;
  queued_end -> reuseconn;
  queued_end -> create_start;
  reuseconn -> end;

}

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

digraph {

  begin[shape=point, xlabel="begin", width="0.1"];
  end[shape=point, xlabel="end", width="0.1"];
  exception[shape=oval];

  resolve_start[shape=box];
  resolve_end[shape=box];
  cache_hit[shape=box];
  cache_miss[shape=box];

  begin -> cache_hit -> end;
  begin -> cache_miss -> resolve_start;
  resolve_start -> resolve_end -> end;
  resolve_start -> exception;

}

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)[source]

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)[source]
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.

Added 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.

Added 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.

Added in version 3.8.

class aiohttp.TraceRequestStartParams[source]

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[source]

Added 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[source]

Added 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[source]

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[source]

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[source]

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[source]

See TraceConfig.on_connection_queued_start for details.

There are no attributes right now.

class aiohttp.TraceConnectionQueuedEndParams[source]

See TraceConfig.on_connection_queued_end for details.

There are no attributes right now.

class aiohttp.TraceConnectionCreateStartParams[source]

See TraceConfig.on_connection_create_start for details.

There are no attributes right now.

class aiohttp.TraceConnectionCreateEndParams[source]

See TraceConfig.on_connection_create_end for details.

There are no attributes right now.

class aiohttp.TraceConnectionReuseconnParams[source]

See TraceConfig.on_connection_reuseconn for details.

There are no attributes right now.

class aiohttp.TraceDnsResolveHostStartParams[source]

See TraceConfig.on_dns_resolvehost_start for details.

host

Host that will be resolved.

class aiohttp.TraceDnsResolveHostEndParams[source]

See TraceConfig.on_dns_resolvehost_end for details.

host

Host that has been resolved.

class aiohttp.TraceDnsCacheHitParams[source]

See TraceConfig.on_dns_cache_hit for details.

host

Host found in the cache.

class aiohttp.TraceDnsCacheMissParams[source]

See TraceConfig.on_dns_cache_miss for details.

host

Host didn’t find the cache.

class aiohttp.TraceRequestHeadersSentParams[source]

See TraceConfig.on_request_headers_sent for details.

Added 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.