message: tracing: document zipkin headers that services need to propagate
diff: @@ -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.
  