From 58fa7d2b372d22dd84e5e133f34f79b8f294b589 Mon Sep 17 00:00:00 2001 From: Roman Dzhabarov Date: Tue, 28 Feb 2017 13:09:39 -0800 Subject: [PATCH 1/4] init. --- docs/configuration/http_conn_man/headers.rst | 12 ++++++++++++ docs/intro/arch_overview/tracing.rst | 5 ++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/configuration/http_conn_man/headers.rst b/docs/configuration/http_conn_man/headers.rst index 212d44fb91d97..cbbbf6923b067 100644 --- a/docs/configuration/http_conn_man/headers.rst +++ b/docs/configuration/http_conn_man/headers.rst @@ -162,3 +162,15 @@ following features are available: ` runtime setting or via forced tracing using the :ref:`config_http_conn_man_headers_x-envoy-force-trace` and :ref:`config_http_conn_man_headers_x-client-trace-id` headers. + +.. _config_http_conn_man_headers_x-ot-span-context: + +x-ot-span-context +_________________ + +The *x-ot-span-context* HTTP header is used by Envoy to establish proper parent-child relationships +between tracing spans. Envoy relies on data from *x-ot-span-context* header to extract the parent +context for the current span. For example, an egress span is a child of ingress span (if there was an ingress call). +Envoy injects the *x-ot-span-context* header on ingress call and passes it to the local service and +then relies on the application to propagate *x-ot-span-context* on the egress call to an upstream. +See more on tracing :ref:`here `. diff --git a/docs/intro/arch_overview/tracing.rst b/docs/intro/arch_overview/tracing.rst index c58fc0ce3d624..e4a13e6f511f7 100644 --- a/docs/intro/arch_overview/tracing.rst +++ b/docs/intro/arch_overview/tracing.rst @@ -20,10 +20,13 @@ 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 the tracing functionality. + How to initiate a trace ----------------------- The HTTP connection manager that handles the request must have the :ref:`tracing -` object set. There are several ways tracing can be +` object set. There are several ways tracing can be initiated: * By an external client via the :ref:`config_http_conn_man_headers_x-client-trace-id` From d13ede5621798170f4066ef963e3eee9c52196b6 Mon Sep 17 00:00:00 2001 From: Roman Dzhabarov Date: Tue, 28 Feb 2017 14:36:02 -0800 Subject: [PATCH 2/4] fix. --- docs/configuration/http_conn_man/headers.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/configuration/http_conn_man/headers.rst b/docs/configuration/http_conn_man/headers.rst index cbbbf6923b067..7b24dfcded013 100644 --- a/docs/configuration/http_conn_man/headers.rst +++ b/docs/configuration/http_conn_man/headers.rst @@ -169,8 +169,8 @@ x-ot-span-context _________________ The *x-ot-span-context* HTTP header is used by Envoy to establish proper parent-child relationships -between tracing spans. Envoy relies on data from *x-ot-span-context* header to extract the parent -context for the current span. For example, an egress span is a child of ingress span (if there was an ingress call). -Envoy injects the *x-ot-span-context* header on ingress call and passes it to the local service and -then relies on the application to propagate *x-ot-span-context* on the egress call to an upstream. -See more on tracing :ref:`here `. +between tracing spans. Envoy relies on data from the *x-ot-span-context* header to extract the parent +context for the current span. For example, an egress span is a child of an ingress +span (if there was the ingress span). Envoy injects the *x-ot-span-context* header on ingress requests and +forwards it to the local service. Envoy relies on the application to propagate *x-ot-span-context* on +the egress call to an upstream. See more on tracing :ref:`here `. From d98c3e98b90240ff7ccedab3c8d0ea2c1f343766 Mon Sep 17 00:00:00 2001 From: Roman Dzhabarov Date: Tue, 28 Feb 2017 16:04:42 -0800 Subject: [PATCH 3/4] change. --- docs/configuration/http_conn_man/headers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/http_conn_man/headers.rst b/docs/configuration/http_conn_man/headers.rst index 7b24dfcded013..6a3bdb7d64adf 100644 --- a/docs/configuration/http_conn_man/headers.rst +++ b/docs/configuration/http_conn_man/headers.rst @@ -171,6 +171,6 @@ _________________ The *x-ot-span-context* HTTP header is used by Envoy to establish proper parent-child relationships between tracing spans. Envoy relies on data from the *x-ot-span-context* header to extract the parent context for the current span. For example, an egress span is a child of an ingress -span (if there was the ingress span). Envoy injects the *x-ot-span-context* header on ingress requests and +span (if the ingress span was present). Envoy injects the *x-ot-span-context* header on ingress requests and forwards it to the local service. Envoy relies on the application to propagate *x-ot-span-context* on the egress call to an upstream. See more on tracing :ref:`here `. From 5463c874ce771a5e1354c604776a7aa789c52724 Mon Sep 17 00:00:00 2001 From: Roman Dzhabarov Date: Thu, 2 Mar 2017 11:34:11 -0800 Subject: [PATCH 4/4] specify that it's LS specific. --- docs/configuration/http_conn_man/headers.rst | 4 +++- docs/intro/arch_overview/tracing.rst | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/configuration/http_conn_man/headers.rst b/docs/configuration/http_conn_man/headers.rst index 6a3bdb7d64adf..7594b7c042e8b 100644 --- a/docs/configuration/http_conn_man/headers.rst +++ b/docs/configuration/http_conn_man/headers.rst @@ -169,7 +169,9 @@ x-ot-span-context _________________ The *x-ot-span-context* HTTP header is used by Envoy to establish proper parent-child relationships -between tracing spans. Envoy relies on data from the *x-ot-span-context* header to extract the parent +between tracing spans for LightStep tracing. *x-ot-span-context* is a Base64 encoded +`binary OT `_ carrier. +Envoy relies on data from the *x-ot-span-context* header to extract the parent context for the current span. For example, an egress span is a child of an ingress span (if the ingress span was present). Envoy injects the *x-ot-span-context* header on ingress requests and forwards it to the local service. Envoy relies on the application to propagate *x-ot-span-context* on diff --git a/docs/intro/arch_overview/tracing.rst b/docs/intro/arch_overview/tracing.rst index e4a13e6f511f7..87a8c49606cbf 100644 --- a/docs/intro/arch_overview/tracing.rst +++ b/docs/intro/arch_overview/tracing.rst @@ -21,7 +21,7 @@ sources of latency. Envoy supports three features related to system wide tracing :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 the tracing functionality. +:ref:`config_http_conn_man_headers_x-ot-span-context` HTTP headers for LightStep tracing functionality. How to initiate a trace -----------------------