Tracing diagrams (#2748)

* Sketch blockdiag diagrams

* Update whitelist

* Tune diag

* Relax whitelist

docs/conf.py

@@ -53,6 +53,8 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
     'sphinxcontrib.asyncio',
+    'sphinxcontrib.asyncio',
+    'sphinxcontrib.blockdiag',
 ]
 
 

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

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

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