Update description of B3 header usage (#552)

Signed-off-by: Gary Brown <gary@brownuk.com>

docs/root/configuration/http_conn_man/headers.rst

@@ -347,7 +347,7 @@ x-ot-span-context
 -----------------
 
 The *x-ot-span-context* HTTP header is used by Envoy to establish proper parent-child relationships
-between tracing spans. This header can be used with both LightStep and Zipkin tracers.
+between tracing spans when used with the LightStep tracer.
 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
@@ -391,7 +391,7 @@ x-b3-sampled
 ------------
 
 The *x-b3-sampled* HTTP header is used by the Zipkin tracer in Envoy.
-When the Sampled flag is 1, the soan will be reported to the tracing
+When the Sampled flag is either not specified or set to 1, the span will be reported to the tracing
 system. Once Sampled is set to 0 or 1, the same
 value should be consistently sent downstream. See more on zipkin tracing
 `here <https://github.com/openzipkin/b3-propagation>`.

docs/root/intro/arch_overview/tracing.rst

@@ -60,20 +60,15 @@ Alternatively the trace context can be manually propagated by the service:
   :ref:`config_http_conn_man_headers_x-ot-span-context` HTTP header
   while sending HTTP requests to other services.
 
-* When using the Zipkin tracer, Envoy relies on the service to propagate either the
+* When using the Zipkin tracer, Envoy relies on the service to propagate the
-  official B3 HTTP headers (
+  B3 HTTP headers (
   :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`) or for convenience it is
+  :ref:`config_http_conn_man_headers_x-b3-flags`). The :ref:`config_http_conn_man_headers_x-b3-sampled`
-  also possible to just propagate the
+  header can also be supplied by an external client to either enable or disable tracing for a particular
-  :ref:`config_http_conn_man_headers_x-ot-span-context` HTTP header.
+  request.
-
-NOTE: Work is currently underway in the distributed tracing community to define a standard for trace
-context propagation. Once a suitable approach has been adopted, the use of the non-standard single
-header :ref:`config_http_conn_man_headers_x-ot-span-context` for propagating Zipkin trace context
-will be replaced.
 
 What data each trace contains
 -----------------------------

docs/root/intro/version_history.rst

@@ -7,6 +7,12 @@ Version history
   <envoy_api_field_core.HttpProtocolOptions.idle_timeout>`.
 * health check: added setting for :ref:`no-traffic
   interval<envoy_api_field_core.HealthCheck.no_traffic_interval>`.
+* tracing: when using the zipkin tracer, it is now possible for clients to specify the sampling decision (using
+  the :ref:`x-b3-sampled <config_http_conn_man_headers_x-b3-sampled>` header) and have the decision
+  propagated through to subsequently invoked services.
+* tracing: when using the zipkin tracer, it is no longer necessary to propagate the
+  :ref:`x-ot-span-context <config_http_conn_man_headers_x-ot-span-context>` header.
+  See more on trace context propagation :ref:`here <arch_overview_tracing>`.
 
 1.5.0
 =====