From 4ea7bfb10c117afa9ea12c941bef82ce6378f3cf Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Sun, 18 Feb 2018 10:42:18 -0400 Subject: [PATCH 1/4] Sketch blockdiag diagrams --- docs/conf.py | 2 + docs/tracing_reference.rst | 84 ++++++++++++++++++++++++++++++++++++++ requirements/doc.txt | 1 + 3 files changed, 87 insertions(+) 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/tracing_reference.rst b/docs/tracing_reference.rst index 4a606bb46cd..e5e52952537 100644 --- a/docs/tracing_reference.rst +++ b/docs/tracing_reference.rst @@ -11,6 +11,90 @@ 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 { + 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"]; + + got_response; + send_request; + + start -> acquire_connection; + acquire_connection -> resolve_dns; + resolve_dns -> send_request; + send_request -> got_response; + got_response -> redirect; + got_response -> end; + redirect -> send_request; + send_request -> exception; + + } + + +Connection acquiring +^^^^^^^^^^^^^^^^^^^^ + +.. blockdiag:: + :desctable: + + blockdiag { + + begin[shape=beginpoint]; + end[shape=endpoint]; + exception[shape=flowchart.terminator]; + + 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"]; + + begin -> reuseconn -> end; + begin -> create_start; + create_start -> exception; + create_start -> create_end -> end; + begin -> queued_start; + queued_start -> queued_end -> end; + + } + +DNS resolving +^^^^^^^^^^^^^ + +.. blockdiag:: + :desctable: + + blockdiag { + dns_resolvehost_start; + dns_resolvehost_end; + dns_cache_hit; + dns_cache_miss; + + dns_request; + request_exception; + + dns_request -> dns_cache_hit; + dns_request -> dns_cache_miss -> dns_resolvehost_start; + dns_resolvehost_start -> dns_resolvehost_end; + dns_resolvehost_start -> request_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 From 06a65efea2d33d881c0efacb30ce8c12afcc02b4 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Sun, 18 Feb 2018 10:48:50 -0400 Subject: [PATCH 2/4] Update whitelist --- docs/spelling_wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index f2478a6968e..daccc4cd32c 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -87,6 +87,7 @@ epoll Facebook facto fallback +fallbacks filename finalizers frontend @@ -219,6 +220,7 @@ requote requoting resolvers reusage +reuseconn Runit sa Satisfiable From e7884f3da43449479843df26f83f039692f67330 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Sun, 18 Feb 2018 11:32:29 -0400 Subject: [PATCH 3/4] Tune diag --- docs/tracing_reference.rst | 54 ++++++++++++++++++++++++-------------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/docs/tracing_reference.rst b/docs/tracing_reference.rst index e5e52952537..5cfaf09c527 100644 --- a/docs/tracing_reference.rst +++ b/docs/tracing_reference.rst @@ -24,18 +24,21 @@ 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 -> resolve_dns; - resolve_dns -> send_request; + acquire_connection -> send_request; send_request -> got_response; got_response -> redirect; got_response -> end; @@ -52,10 +55,11 @@ Connection acquiring :desctable: blockdiag { + orientation = portrait; begin[shape=beginpoint]; end[shape=endpoint]; - exception[shape=flowchart.terminator]; + exception[shape=flowchart.terminator, description="Exception raised"]; queued_start[description="on_connection_queued_start"]; queued_end[description="on_connection_queued_end"]; @@ -63,12 +67,21 @@ Connection acquiring create_end[description="on_connection_create_end"]; reuseconn[description="on_connection_reuseconn"]; - begin -> reuseconn -> end; + resolve_dns[description="DNS resolving"]; + sock_connect[description="Connection establishment"]; + + begin -> reuseconn; begin -> create_start; - create_start -> exception; - create_start -> create_end -> end; + 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 -> end; + queued_start -> queued_end; + queued_end -> reuseconn; + queued_end -> create_start; + reuseconn -> end; } @@ -79,18 +92,21 @@ DNS resolving :desctable: blockdiag { - dns_resolvehost_start; - dns_resolvehost_end; - dns_cache_hit; - dns_cache_miss; - - dns_request; - request_exception; - - dns_request -> dns_cache_hit; - dns_request -> dns_cache_miss -> dns_resolvehost_start; - dns_resolvehost_start -> dns_resolvehost_end; - dns_resolvehost_start -> request_exception; + 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; } From 40e188f53a510956f5449715e184e8bf50bbb36c Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Sun, 18 Feb 2018 11:38:42 -0400 Subject: [PATCH 4/4] Relax whitelist --- docs/spelling_wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index daccc4cd32c..9dada48f374 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -218,6 +218,7 @@ request’s Request’s requote requoting +resolvehost resolvers reusage reuseconn