From 5b862099dd4f21d2616ef04b24add41f4121e1fb Mon Sep 17 00:00:00 2001
From: Adrian Cole <acole@pivotal.io>
Date: Wed, 11 Jan 2017 13:51:31 +0800
Subject: [PATCH] Adds diagram showing trace instrumentation's role in
 architecture

---
 pages/architecture.md | 55 +++++++++++++++++++++++++++++++++++++++++++
 public/css/zipkin.css |  6 +++++
 2 files changed, 61 insertions(+)

diff --git a/pages/architecture.md b/pages/architecture.md
index ab2d9be..38a319d 100644
--- a/pages/architecture.md
+++ b/pages/architecture.md
@@ -33,6 +33,61 @@ Here's a diagram describing this flow:
 To see if an instrumentation library already exists for your platform, see the
 list of [existing instrumentations]({{ site.github.url}}/pages/existing_instrumentations).
 
+Example flow
+-----------------------
+
+As mentioned in the overview, identifiers are sent in-band and details are sent
+out-of-band to Zipkin. In both cases, trace instrumentation is responsible for
+creating valid traces and rendering them properly. For example, a tracer ensures
+parity between the data it sends in-band (downstream) and out-of-band (async to
+Zipkin).
+
+Here's an example sequence of http tracing where "Application" calls the
+resource /foo. This results in a single span, sent asynchronously to Zipkin
+after call completes.
+
+```
+┌─────────────┐ ┌───────────────────────┐  ┌─────────────┐  ┌──────────────────┐
+│ Application │ │ Trace Instrumentation │  │ Http Client │  │ Zipkin Collector │
+└─────────────┘ └───────────────────────┘  └─────────────┘  └──────────────────┘
+       │                 │                         │                 │
+           ┌─────────┐
+       │ ──┤GET /foo ├─▶ │ ────┐                   │                 │
+           └─────────┘         │ record tags
+       │                 │ ◀───┘                   │                 │
+                           ────┐
+       │                 │     │ add trace headers │                 │
+                           ◀───┘
+       │                 │ ────┐                   │                 │
+                               │ record timestamp
+       │                 │ ◀───┘                   │                 │
+                             ┌─────────────────┐
+       │                 │ ──┤GET /foo         ├─▶ │                 │
+                             │X-B3-TraceId: aa │     ────┐
+       │                 │   │X-B3-SpanId: 6b  │   │     │           │
+                             └─────────────────┘         │ invoke
+       │                 │                         │     │ request   │
+                                                         │
+       │                 │                         │     │           │
+                                 ┌────────┐          ◀───┘
+       │                 │ ◀─────┤200 OK  ├─────── │                 │
+                           ────┐ └────────┘
+       │                 │     │ record duration   │                 │
+            ┌────────┐     ◀───┘
+       │ ◀──┤200 OK  ├── │                         │                 │
+            └────────┘       ┌────────────────────────────────┐
+       │                 │ ──┤ asynchronously report span     ├────▶ │
+                             │                                │
+                             │{                               │
+                             │  "traceId": "ab",              │
+                             │  "id": "6b",                   │
+                             │  "name": "get",                │
+                             │  "timestamp": 1483945573944000,│
+                             │  "duration": 386000,           │
+                             │  "annotations": [              │
+                             │--snip--                        │
+                             └────────────────────────────────┘
+```
 
 Transport
 ---------
diff --git a/public/css/zipkin.css b/public/css/zipkin.css
index f83e46e..720163b 100644
--- a/public/css/zipkin.css
+++ b/public/css/zipkin.css
@@ -35,6 +35,12 @@ figure.highlight pre code {
   overflow-x: auto;
   word-wrap: normal;
 }
+pre {
+  white-space: pre;
+  display: block;
+  overflow-x: auto;
+  word-wrap: normal;
+}
 
 /* Some tables need to be wide to make sense of them, even if it breaks the design and responsiveness */
 table.wide-table td {