Tracing Reference

.. currentmodule:: aiohttp

.. versionadded:: 3.0

A reference for client tracing API.

.. seealso:: :ref:`aiohttp-client-tracing` for tracing usage instructions.

Request life cycle

A request goes through the following stages and corresponding fallbacks.

Overview

.. blockdiag::
   :desctable:


   blockdiag {
     orientation = portrait;

     start[shape=beginpoint, description="on_request_start"];
     redirect[description="on_request_redirect"];
     end[shape=endpoint, description="on_request_end"];
     exception[shape=flowchart.terminator, description="on_request_exception"];

     acquire_connection[description="Connection acquiring"];
     headers_received;
     headers_sent;
     chunk_sent[description="on_request_chunk_sent"];
     chunk_received[description="on_response_chunk_received"];

     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;

   }

Connection acquiring

.. blockdiag::
   :desctable:

   blockdiag {
     orientation = portrait;

     begin[shape=beginpoint];
     end[shape=endpoint];
     exception[shape=flowchart.terminator, description="Exception raised"];

     queued_start[description="on_connection_queued_start"];
     queued_end[description="on_connection_queued_end"];
     create_start[description="on_connection_create_start"];
     create_end[description="on_connection_create_end"];
     reuseconn[description="on_connection_reuseconn"];

     resolve_dns[description="DNS resolving"];
     sock_connect[description="Connection establishment"];

     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;

   }

DNS resolving

.. blockdiag::
   :desctable:

   blockdiag {
     orientation = portrait;

     begin[shape=beginpoint];
     end[shape=endpoint];
     exception[shape=flowchart.terminator, description="Exception raised"];

     resolve_start[description="on_dns_resolvehost_start"];
     resolve_end[description="on_dns_resolvehost_end"];
     cache_hit[description="on_dns_cache_hit"];
     cache_miss[description="on_dns_cache_miss"];

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

   }

TraceConfig

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

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

.. method:: trace_config_ctx(trace_request_ctx=None)

   :param 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 :class:`ClientSession` instance, context is an object returned by :meth:`trace_config_ctx` call and params is a data class with signal parameters. The type of params depends on subscribed signal and described below.

.. attribute:: on_request_start

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

   ``params`` is :class:`aiohttp.TraceRequestStartParams` instance.

.. attribute:: 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 :class:`aiohttp.TraceRequestChunkSentParams` instance.

   .. versionadded:: 3.1

.. attribute:: 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 :class:`aiohttp.TraceResponseChunkReceivedParams` instance.

   .. versionadded:: 3.1

.. attribute:: on_request_redirect

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

   ``params`` is :class:`aiohttp.TraceRequestRedirectParams` instance.

.. attribute:: on_request_end

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

   ``params`` is :class:`aiohttp.TraceRequestEndParams` instance.

.. attribute:: on_request_exception

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

   ``params`` is :class:`aiohttp.TraceRequestExceptionParams` instance.

.. attribute:: 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 :class:`aiohttp.TraceConnectionQueuedStartParams`
   instance.

.. attribute:: 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 :class:`aiohttp.TraceConnectionQueuedEndParams`
   instance.

.. attribute:: on_connection_create_start

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

   ``params`` is :class:`aiohttp.TraceConnectionCreateStartParams`
   instance.

.. attribute:: 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 :class:`aiohttp.TraceConnectionCreateEndParams`
   instance.

.. attribute:: on_connection_reuseconn

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

   ``params`` is :class:`aiohttp.TraceConnectionReuseconnParams`
   instance.

.. attribute:: 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 :class:`aiohttp.TraceDnsResolveHostStartParams`
   instance.

.. attribute:: 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 :class:`aiohttp.TraceDnsResolveHostEndParams` instance.

.. attribute:: 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 :class:`aiohttp.TraceDnsCacheHitParams` instance.

.. attribute:: 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 :class:`aiohttp.TraceDnsCacheMissParams` instance.

TraceRequestStartParams

See :attr:`TraceConfig.on_request_start` for details.

.. attribute:: method

    Method that will be used  to make the request.

.. attribute:: url

    URL that will be used  for the request.

.. attribute:: headers

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

TraceRequestChunkSentParams

.. versionadded:: 3.1

See :attr:`TraceConfig.on_request_chunk_sent` for details.

.. attribute:: method

    Method that will be used  to make the request.

.. attribute:: url

    URL that will be used  for the request.

.. attribute:: chunk

    Bytes of chunk sent

TraceResponseChunkReceivedParams

.. versionadded:: 3.1

See :attr:`TraceConfig.on_response_chunk_received` for details.

.. attribute:: method

    Method that will be used  to make the request.

.. attribute:: url

    URL that will be used  for the request.

.. attribute:: chunk

    Bytes of chunk received

TraceRequestEndParams

See :attr:`TraceConfig.on_request_end` for details.

.. attribute:: method

    Method used to make the request.

.. attribute:: url

    URL used for the request.

.. attribute:: headers

    Headers used for the request.

.. attribute:: response

    Response :class:`ClientResponse`.

TraceRequestExceptionParams

See :attr:`TraceConfig.on_request_exception` for details.

.. attribute:: method

    Method used to make the request.

.. attribute:: url

    URL used for the request.

.. attribute:: headers

    Headers used for the request.

.. attribute:: exception

    Exception raised during the request.

TraceRequestRedirectParams

See :attr:`TraceConfig.on_request_redirect` for details.

.. attribute:: method

    Method used to get this redirect request.

.. attribute:: url

    URL used for this redirect request.

.. attribute:: headers

    Headers used for this redirect.

.. attribute:: response

    Response :class:`ClientResponse` got from the redirect.