tracing: document zipkin headers that services need to propagate

docs/intro/arch_overview/tracing.rst

@@ -13,16 +13,24 @@ sources of latency. Envoy supports three features related to system wide tracing
   :ref:`config_http_conn_man_headers_x-request-id` HTTP header. Applications can forward the
   x-request-id header for unified logging as well as tracing.
 * **External trace service integration**: Envoy supports pluggable external trace visualization
-  providers. Currently the only supported provider is for `LightStep <http://lightstep.com/>`_.
-  However other providers for systems such as `Zipkin <http://zipkin.io/>`_ or `OpenTracing
-  <http://opentracing.io/>`_ would not be difficult to add.
+  providers. Currently Envoy supports `LightStep <http://lightstep.com/>`_ and `Zipkin <http://zipkin.io/>`_.
+  However, support for other tracing providers would not be not be difficult to add.
 * **Client trace ID joining**: The :ref:`config_http_conn_man_headers_x-client-trace-id` header can
   be used to join untrusted request IDs to the trusted internal
   :ref:`config_http_conn_man_headers_x-request-id`.
 
-Envoy relies on properly propagated :ref:`config_http_conn_man_headers_x-request-id` and
-:ref:`config_http_conn_man_headers_x-ot-span-context` HTTP headers for LightStep tracing
-functionality.
+When using the LightStep tracer, Envoy relies on a service to propagate
+:ref:`config_http_conn_man_headers_x-request-id` and
+:ref:`config_http_conn_man_headers_x-ot-span-context` HTTP headers
+while sending HTTP requests to other services. When using the Zipkin
+tracer, Envoy relies on the service to
+propagate :ref:`config_http_conn_man_headers_x-request-id`,
+:ref:`config_http_conn_man_headers_x-ot-span-context`,
+:ref:`config_http_conn_man_headers_x-b3-traceid`,
+:ref:`config_http_conn_man_headers_x-b3-spanid`,
+:ref:`config_http_conn_man_headers_x-b3-parentspanid`,
+:ref:`config_http_conn_man_headers_x-b3-sampled`, and
+:ref:`config_http_conn_man_headers_x-b3-flags` HTTP headers.
 
 How to initiate a trace
 -----------------------
@@ -39,10 +47,9 @@ initiated:
 
 What data each trace contains
 -----------------------------
-Traces from every service are aggregated using the :ref:`config_http_conn_man_headers_x-request-id`
-HTTP request header. Envoy automatically sends spans which compose a trace to tracing collectors. A
+An end-to-end trace is comprised of one or more spans. A
 span represents a logical unit of work that has a start time and duration and can contain metadata
-associated with it. Each Envoy span contains the following data:
+associated with it. Each span generated by Envoy contains the following data:
 
 * Originating service cluster set via :option:`--service-cluster`.
 * Start time and duration of the request.
@@ -51,5 +58,12 @@ associated with it. Each Envoy span contains the following data:
   header.
 * HTTP request line.
 * HTTP response code.
+* Tracing system-specific metadata.
 
-Tracing :ref:`configuration <config_tracing>`.
+Envoy automatically sends spans to tracing collectors. Depending on the tracing collector,
+multiple spans are stitched together using common information such as the globally unique
+request ID :ref:`config_http_conn_man_headers_x-request-id` (LightStep) or
+the trace ID :ref:`configuration <config_tracing>` (Zipkin).
+
+See tracing :ref:`configuration <config_tracing>` for more information on
+how to setup tracing in Envoy.