diff --git a/docs/intro/arch_overview/tracing.rst b/docs/intro/arch_overview/tracing.rst index f92c76b67ed14..0891d7c4e653e 100644 --- a/docs/intro/arch_overview/tracing.rst +++ b/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 `_. - However other providers for systems such as `Zipkin `_ or `OpenTracing - `_ would not be difficult to add. + providers. Currently Envoy supports `LightStep `_ and `Zipkin `_. + 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 `. +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 ` (Zipkin). + +See tracing :ref:`configuration ` for more information on +how to setup tracing in Envoy.