From 4bdd92a4dcebc1aa9324b398e000077406404ad9 Mon Sep 17 00:00:00 2001 From: Shriram Rajagopalan Date: Sun, 14 May 2017 18:33:48 -0400 Subject: [PATCH 1/3] document zipkin headers that services need to propagate --- docs/intro/arch_overview/tracing.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/intro/arch_overview/tracing.rst b/docs/intro/arch_overview/tracing.rst index f92c76b67ed14..a52d86b1efc88 100644 --- a/docs/intro/arch_overview/tracing.rst +++ b/docs/intro/arch_overview/tracing.rst @@ -20,9 +20,18 @@ sources of latency. Envoy supports three features related to system wide tracing 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 ----------------------- From fe114f446942c1a13cb19c66d9062a224ee504be Mon Sep 17 00:00:00 2001 From: Shriram Rajagopalan Date: Sun, 14 May 2017 23:10:28 -0400 Subject: [PATCH 2/3] generalize tracing architecture discussion --- docs/intro/arch_overview/tracing.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/intro/arch_overview/tracing.rst b/docs/intro/arch_overview/tracing.rst index a52d86b1efc88..dcdc1dde2a888 100644 --- a/docs/intro/arch_overview/tracing.rst +++ b/docs/intro/arch_overview/tracing.rst @@ -13,9 +13,8 @@ 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 the 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`. @@ -48,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. @@ -60,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. From 75e87733df2dd1d7a0cd5818244d3c2b57a56781 Mon Sep 17 00:00:00 2001 From: Shriram Rajagopalan Date: Mon, 15 May 2017 13:15:44 -0400 Subject: [PATCH 3/3] fix typo --- docs/intro/arch_overview/tracing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro/arch_overview/tracing.rst b/docs/intro/arch_overview/tracing.rst index dcdc1dde2a888..0891d7c4e653e 100644 --- a/docs/intro/arch_overview/tracing.rst +++ b/docs/intro/arch_overview/tracing.rst @@ -13,7 +13,7 @@ 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 Envoy supports `LightStep `_ and `Zipkin `_. + 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