Sync docs from master to gh-pages

multi/multi__features.html

@@ -21,7 +21,9 @@ The default is as follows:
 (this is a Spring Boot feature for logback users).
 If you do not use SLF4J, this pattern is NOT automatically applied.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_introduction_to_brave" href="#_introduction_to_brave"></a>3.1&nbsp;Introduction to Brave</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Starting with version <code class="literal">2.0.0</code>, Spring Cloud Sleuth uses
 <a class="link" href="https://github.com/openzipkin/brave" target="_top">Brave</a> as the tracing library.
-For your convenience, we embed part of the Brave&#8217;s docs here.</p></td></tr></table></div><p>Brave is a library used to capture and report latency information about distributed operations to Zipkin.
+For your convenience, we embed part of the Brave&#8217;s docs here.</p></td></tr></table></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>In the vast majority of cases you need to just use the <code class="literal">Tracer</code>
+or <code class="literal">SpanCustomizer</code> beans from Brave that Sleuth provides. The documentation below contains
+a high overview of what Brave is and how it works.</p></td></tr></table></div><p>Brave is a library used to capture and report latency information about distributed operations to Zipkin.
 Most users do not use Brave directly. They use libraries or frameworks rather than employ Brave on their behalf.</p><p>This module includes a tracer that creates and joins spans that model the latency of potentially distributed work.
 It also includes libraries to propagate the trace context over network boundaries (for example, with HTTP headers).</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_tracing" href="#_tracing"></a>3.1.1&nbsp;Tracing</h3></div></div></div><p>Most importantly, you need a <code class="literal">brave.Tracer</code>, configured to <a class="link" href="https://github.com/openzipkin/zipkin-reporter-java" target="_top">report to Zipkin</a>.</p><p>The following example setup sends trace data (spans) to Zipkin over HTTP (as opposed to Kafka):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
 
@@ -111,4 +113,4 @@ oneWayReceive.start().flush();
 
 <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you should not modify this span anymore as it is complete. However,</span>
 <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you can create children to represent follow-up work.</span>
-next = tracer.newSpan(oneWayReceive.context()).name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"step2"</span>).start();</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The propagation logic shown in the preceding example is a simplified version of our [http handlers](<a class="link" href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server" target="_top">https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server</a>).</p></td></tr></table></div><p>You can find a working example of a one-way span [here](src/test/java/sleuth/features/async/OneWaySpanTest.java).</p></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__additional_resources.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="multi__sampling.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.&nbsp;Additional Resources&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-sleuth.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;4.&nbsp;Sampling</td></tr></table></div></body></html>
+next = tracer.newSpan(oneWayReceive.context()).name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"step2"</span>).start();</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The propagation logic shown in the preceding example is a simplified version of our <a class="link" href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server" target="_top">http handlers</a>.</p></td></tr></table></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__additional_resources.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="multi__sampling.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.&nbsp;Additional Resources&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-sleuth.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;4.&nbsp;Sampling</td></tr></table></div></body></html>

multi/multi__introduction.html

@@ -12,7 +12,7 @@ the request started, and where it ended. For learning purposes,
 however, we mark these events to highlight what kind
 of an action took place.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>cs</strong></span>: Client Sent. The client has made a request. This annotation indicates the start of the span.</li><li class="listitem"><span class="strong"><strong>sr</strong></span>: Server Received: The server side got the request and started processing it.
 Subtracting the <code class="literal">cs</code> timestamp from this timestamp reveals the network latency.</li><li class="listitem"><span class="strong"><strong>ss</strong></span>: Server Sent. Annotated upon completion of request processing (when the response got sent back to the client).
-Subtracting the <code class="literal">sr</code> timestamp from this timestamp reveals the time needed by the server side to process the request.</li><li class="listitem"><span class="strong"><strong>cr</strong></span>&gt; Client Received. Signifies the end of the span.
+Subtracting the <code class="literal">sr</code> timestamp from this timestamp reveals the time needed by the server side to process the request.</li><li class="listitem"><span class="strong"><strong>cr</strong></span>: Client Received. Signifies the end of the span.
 The client has successfully received the response from the server side.
 Subtracting the <code class="literal">cs</code> timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server.</li></ul></div><p>The following image shows how <span class="strong"><strong>Span</strong></span> and <span class="strong"><strong>Trace</strong></span> look in a system, together with the Zipkin annotations:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/trace-id.png" alt="Trace Info propagation"></div></div><p>Each color of a note signifies a span (there are seven spans - from <span class="strong"><strong>A</strong></span> to <span class="strong"><strong>G</strong></span>).
 Consider the following note:</p><pre class="screen">Trace Id = X

multi/multi__propagation.html

@@ -47,7 +47,7 @@ String countryCode = ExtraFieldPropagation.get(span.context(), <span xmlns:d="ht
 There are two properties to achieve this.
 With the <code class="literal">spring.sleuth.baggage-keys</code>, you set keys that get prefixed with <code class="literal">baggage-</code> for HTTP calls and <code class="literal">baggage_</code> for messaging.
 You can also use the <code class="literal">spring.sleuth.propagation-keys</code> property to pass a list of prefixed keys that are whitelisted without any prefix.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_extracting_a_propagated_context" href="#_extracting_a_propagated_context"></a>5.1.2&nbsp;Extracting a Propagated Context</h3></div></div></div><p>The <code class="literal">TraceContext.Extractor&lt;C&gt;</code> reads trace identifiers and sampling status from an incoming request or message.
-The carrier is usually a request object or headers.</p><p>This utility is used in standard instrumentation (such as <code class="literal">[HttpServerHandler](../instrumentation/http/src/main/java/sleuth/http/HttpServerHandler.java)</code>) but can also be used for custom RPC or messaging code.</p><p><code class="literal">TraceContextOrSamplingFlags</code> is usually used only with <code class="literal">Tracer.nextSpan(extracted)</code>, unless you are
+The carrier is usually a request object or headers.</p><p>This utility is used in standard instrumentation (such as <code class="literal">HttpServerHandler`</code>) but can also be used for custom RPC or messaging code.</p><p><code class="literal">TraceContextOrSamplingFlags</code> is usually used only with <code class="literal">Tracer.nextSpan(extracted)</code>, unless you are
 sharing span IDs between a client and a server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sharing_span_ids_between_client_and_server" href="#_sharing_span_ids_between_client_and_server"></a>5.1.3&nbsp;Sharing span IDs between Client and Server</h3></div></div></div><p>A normal instrumentation pattern is to create a span representing the server side of an RPC.
 <code class="literal">Extractor.extract</code> might return a complete trace context when applied to an incoming client request.
 <code class="literal">Tracer.joinSpan</code> attempts to continue this trace, using the same span ID if supported or creating a child span

single/spring-cloud-sleuth.html

@@ -12,7 +12,7 @@ the request started, and where it ended. For learning purposes,
 however, we mark these events to highlight what kind
 of an action took place.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>cs</strong></span>: Client Sent. The client has made a request. This annotation indicates the start of the span.</li><li class="listitem"><span class="strong"><strong>sr</strong></span>: Server Received: The server side got the request and started processing it.
 Subtracting the <code class="literal">cs</code> timestamp from this timestamp reveals the network latency.</li><li class="listitem"><span class="strong"><strong>ss</strong></span>: Server Sent. Annotated upon completion of request processing (when the response got sent back to the client).
-Subtracting the <code class="literal">sr</code> timestamp from this timestamp reveals the time needed by the server side to process the request.</li><li class="listitem"><span class="strong"><strong>cr</strong></span>&gt; Client Received. Signifies the end of the span.
+Subtracting the <code class="literal">sr</code> timestamp from this timestamp reveals the time needed by the server side to process the request.</li><li class="listitem"><span class="strong"><strong>cr</strong></span>: Client Received. Signifies the end of the span.
 The client has successfully received the response from the server side.
 Subtracting the <code class="literal">cs</code> timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server.</li></ul></div><p>The following image shows how <span class="strong"><strong>Span</strong></span> and <span class="strong"><strong>Trace</strong></span> look in a system, together with the Zipkin annotations:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/trace-id.png" alt="Trace Info propagation"></div></div><p>Each color of a note signifies a span (there are seven spans - from <span class="strong"><strong>A</strong></span> to <span class="strong"><strong>G</strong></span>).
 Consider the following note:</p><pre class="screen">Trace Id = X
@@ -253,7 +253,9 @@ The default is as follows:
 (this is a Spring Boot feature for logback users).
 If you do not use SLF4J, this pattern is NOT automatically applied.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_introduction_to_brave" href="#_introduction_to_brave"></a>3.1&nbsp;Introduction to Brave</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Starting with version <code class="literal">2.0.0</code>, Spring Cloud Sleuth uses
 <a class="link" href="https://github.com/openzipkin/brave" target="_top">Brave</a> as the tracing library.
-For your convenience, we embed part of the Brave&#8217;s docs here.</p></td></tr></table></div><p>Brave is a library used to capture and report latency information about distributed operations to Zipkin.
+For your convenience, we embed part of the Brave&#8217;s docs here.</p></td></tr></table></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>In the vast majority of cases you need to just use the <code class="literal">Tracer</code>
+or <code class="literal">SpanCustomizer</code> beans from Brave that Sleuth provides. The documentation below contains
+a high overview of what Brave is and how it works.</p></td></tr></table></div><p>Brave is a library used to capture and report latency information about distributed operations to Zipkin.
 Most users do not use Brave directly. They use libraries or frameworks rather than employ Brave on their behalf.</p><p>This module includes a tracer that creates and joins spans that model the latency of potentially distributed work.
 It also includes libraries to propagate the trace context over network boundaries (for example, with HTTP headers).</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_tracing" href="#_tracing"></a>3.1.1&nbsp;Tracing</h3></div></div></div><p>Most importantly, you need a <code class="literal">brave.Tracer</code>, configured to <a class="link" href="https://github.com/openzipkin/zipkin-reporter-java" target="_top">report to Zipkin</a>.</p><p>The following example setup sends trace data (spans) to Zipkin over HTTP (as opposed to Kafka):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
 
@@ -343,7 +345,7 @@ oneWayReceive.start().flush();
 
 <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you should not modify this span anymore as it is complete. However,</span>
 <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you can create children to represent follow-up work.</span>
-next = tracer.newSpan(oneWayReceive.context()).name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"step2"</span>).start();</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The propagation logic shown in the preceding example is a simplified version of our [http handlers](<a class="link" href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server" target="_top">https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server</a>).</p></td></tr></table></div><p>You can find a working example of a one-way span [here](src/test/java/sleuth/features/async/OneWaySpanTest.java).</p></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_sampling" href="#_sampling"></a>4.&nbsp;Sampling</h1></div></div></div><p>Sampling may be employed to reduce the data collected and reported out of process.
+next = tracer.newSpan(oneWayReceive.context()).name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"step2"</span>).start();</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The propagation logic shown in the preceding example is a simplified version of our <a class="link" href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server" target="_top">http handlers</a>.</p></td></tr></table></div></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_sampling" href="#_sampling"></a>4.&nbsp;Sampling</h1></div></div></div><p>Sampling may be employed to reduce the data collected and reported out of process.
 When a span is not sampled, it adds no overhead (a noop).</p><p>Sampling is an up-front decision, meaning that the decision to report data is made at the first operation in a trace and that decision is propagated downstream.</p><p>By default, a global sampler applies a single rate to all traced operations.
 <code class="literal">Tracer.Builder.sampler</code> controls this setting, and it defaults to tracing every request.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_declarative_sampling" href="#_declarative_sampling"></a>4.1&nbsp;Declarative sampling</h2></div></div></div><p>Some applications need to sample based on the type or annotations of a java method.</p><p>Most users use a framework interceptor to automate this sort of policy.
 The following example shows how that might work internally:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// derives a sample rate from an annotation on a java method</span>
@@ -423,7 +425,7 @@ String countryCode = ExtraFieldPropagation.get(span.context(), <span xmlns:d="ht
 There are two properties to achieve this.
 With the <code class="literal">spring.sleuth.baggage-keys</code>, you set keys that get prefixed with <code class="literal">baggage-</code> for HTTP calls and <code class="literal">baggage_</code> for messaging.
 You can also use the <code class="literal">spring.sleuth.propagation-keys</code> property to pass a list of prefixed keys that are whitelisted without any prefix.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_extracting_a_propagated_context" href="#_extracting_a_propagated_context"></a>5.1.2&nbsp;Extracting a Propagated Context</h3></div></div></div><p>The <code class="literal">TraceContext.Extractor&lt;C&gt;</code> reads trace identifiers and sampling status from an incoming request or message.
-The carrier is usually a request object or headers.</p><p>This utility is used in standard instrumentation (such as <code class="literal">[HttpServerHandler](../instrumentation/http/src/main/java/sleuth/http/HttpServerHandler.java)</code>) but can also be used for custom RPC or messaging code.</p><p><code class="literal">TraceContextOrSamplingFlags</code> is usually used only with <code class="literal">Tracer.nextSpan(extracted)</code>, unless you are
+The carrier is usually a request object or headers.</p><p>This utility is used in standard instrumentation (such as <code class="literal">HttpServerHandler`</code>) but can also be used for custom RPC or messaging code.</p><p><code class="literal">TraceContextOrSamplingFlags</code> is usually used only with <code class="literal">Tracer.nextSpan(extracted)</code>, unless you are
 sharing span IDs between a client and a server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sharing_span_ids_between_client_and_server" href="#_sharing_span_ids_between_client_and_server"></a>5.1.3&nbsp;Sharing span IDs between Client and Server</h3></div></div></div><p>A normal instrumentation pattern is to create a span representing the server side of an RPC.
 <code class="literal">Extractor.extract</code> might return a complete trace context when applied to an incoming client request.
 <code class="literal">Tracer.joinSpan</code> attempts to continue this trace, using the same span ID if supported or creating a child span

spring-cloud-sleuth.xml

@@ -52,7 +52,7 @@ Subtracting the <literal>cs</literal> timestamp from this timestamp reveals the
 Subtracting the <literal>sr</literal> timestamp from this timestamp reveals the time needed by the server side to process the request.</simpara>
 </listitem>
 <listitem>
-<simpara><emphasis role="strong">cr</emphasis>&gt; Client Received. Signifies the end of the span.
+<simpara><emphasis role="strong">cr</emphasis>: Client Received. Signifies the end of the span.
 The client has successfully received the response from the server side.
 Subtracting the <literal>cs</literal> timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server.</simpara>
 </listitem>
@@ -693,6 +693,11 @@ If you do not use SLF4J, this pattern is NOT automatically applied.</simpara>
 <link xl:href="https://github.com/openzipkin/brave">Brave</link> as the tracing library.
 For your convenience, we embed part of the Brave&#8217;s docs here.</simpara>
 </important>
+<important>
+<simpara>In the vast majority of cases you need to just use the <literal>Tracer</literal>
+or <literal>SpanCustomizer</literal> beans from Brave that Sleuth provides. The documentation below contains
+a high overview of what Brave is and how it works.</simpara>
+</important>
 <simpara>Brave is a library used to capture and report latency information about distributed operations to Zipkin.
 Most users do not use Brave directly. They use libraries or frameworks rather than employ Brave on their behalf.</simpara>
 <simpara>This module includes a tracer that creates and joins spans that model the latency of potentially distributed work.
@@ -835,9 +840,8 @@ oneWayReceive.start().flush();
 // you can create children to represent follow-up work.
 next = tracer.newSpan(oneWayReceive.context()).name("step2").start();</programlisting>
 <note>
-<simpara>The propagation logic shown in the preceding example is a simplified version of our [http handlers](<link xl:href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server">https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server</link>).</simpara>
+<simpara>The propagation logic shown in the preceding example is a simplified version of our <link xl:href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server">http handlers</link>.</simpara>
 </note>
-<simpara>You can find a working example of a one-way span [here](src/test/java/sleuth/features/async/OneWaySpanTest.java).</simpara>
 </section>
 </section>
 </section>
@@ -987,7 +991,7 @@ You can also use the <literal>spring.sleuth.propagation-keys</literal> property
 <title>Extracting a Propagated Context</title>
 <simpara>The <literal>TraceContext.Extractor&lt;C&gt;</literal> reads trace identifiers and sampling status from an incoming request or message.
 The carrier is usually a request object or headers.</simpara>
-<simpara>This utility is used in standard instrumentation (such as <literal>[HttpServerHandler](../instrumentation/http/src/main/java/sleuth/http/HttpServerHandler.java)</literal>) but can also be used for custom RPC or messaging code.</simpara>
+<simpara>This utility is used in standard instrumentation (such as <literal>HttpServerHandler`</literal>) but can also be used for custom RPC or messaging code.</simpara>
 <simpara><literal>TraceContextOrSamplingFlags</literal> is usually used only with <literal>Tracer.nextSpan(extracted)</literal>, unless you are
 sharing span IDs between a client and a server.</simpara>
 </section>