diff --git a/docs/conf.py b/docs/conf.py index 60b4374ec5e..b5cfe2c55eb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,6 +53,8 @@ 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'sphinxcontrib.asyncio', + 'sphinxcontrib.asyncio', + 'sphinxcontrib.blockdiag', ] diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index f2478a6968e..9dada48f374 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -87,6 +87,7 @@ epoll Facebook facto fallback +fallbacks filename finalizers frontend @@ -217,8 +218,10 @@ request’s Request’s requote requoting +resolvehost resolvers reusage +reuseconn Runit sa Satisfiable diff --git a/docs/tracing_reference.rst b/docs/tracing_reference.rst index 4a606bb46cd..5cfaf09c527 100644 --- a/docs/tracing_reference.rst +++ b/docs/tracing_reference.rst @@ -11,6 +11,106 @@ 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"]; + got_response; + send_request; + + start -> acquire_connection; + acquire_connection -> send_request; + send_request -> got_response; + got_response -> redirect; + got_response -> end; + redirect -> send_request; + send_request -> 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 ----------- diff --git a/requirements/doc.txt b/requirements/doc.txt index 0ff1cc1d38f..700a3be7fc3 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -2,3 +2,4 @@ sphinx==1.7.0 sphinxcontrib-asyncio==0.2.0 pygments>=2.1 aiohttp-theme==0.1.4 +sphinxcontrib-blockdiag==1.5.5