From 385581345459fa5a260d6fd1e2a300ef5e9535a6 Mon Sep 17 00:00:00 2001
From: Marcin Grzejszczak <mgrzejszczak@pivotal.io>
Date: Fri, 4 Nov 2016 18:16:00 +0100
Subject: [PATCH] Sync docs from master to gh-pages

---
 spring-cloud-sleuth.html | 169 ++++++++++++++++++++++++++++++---------
 1 file changed, 133 insertions(+), 36 deletions(-)

diff --git a/spring-cloud-sleuth.html b/spring-cloud-sleuth.html
index edbbd83cd..a2ed24c65 100644
--- a/spring-cloud-sleuth.html
+++ b/spring-cloud-sleuth.html
@@ -428,8 +428,24 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div id="toctitle">Table of Contents</div>
 <ul class="sectlevel2">
 <li><a href="#_terminology">Terminology</a></li>
-<li><a href="#_purpose">Purpose</a></li>
-<li><a href="#_adding_to_the_project">Adding to the project</a></li>
+<li><a href="#_purpose">Purpose</a>
+<ul class="sectlevel3">
+<li><a href="#_distributed_tracing_with_zipkin">Distributed tracing with Zipkin</a></li>
+<li><a href="#_log_correlation">Log correlation</a>
+<ul class="sectlevel4">
+<li><a href="#_json_logback_with_logstash">JSON Logback with Logstash</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#_adding_to_the_project">Adding to the project</a>
+<ul class="sectlevel3">
+<li><a href="#_only_sleuth_log_correlation">Only Sleuth (log correlation)</a></li>
+<li><a href="#_sleuth_with_zipkin_via_http">Sleuth with Zipkin via HTTP</a></li>
+<li><a href="#_sleuth_with_zipkin_via_spring_cloud_stream">Sleuth with Zipkin via Spring Cloud Stream</a></li>
+<li><a href="#_spring_cloud_sleuth_stream_zipkin_collector">Spring Cloud Sleuth Stream Zipkin Collector</a></li>
+</ul>
+</li>
 <li><a href="#_additional_resources">Additional resources</a></li>
 <li><a href="#_features">Features</a></li>
 <li><a href="#_sampling">Sampling</a></li>
@@ -465,12 +481,34 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#_integrations">Integrations</a>
 <ul class="sectlevel2">
 <li><a href="#_runnable_and_callable">Runnable and Callable</a></li>
-<li><a href="#_hystrix">Hystrix</a></li>
+<li><a href="#_hystrix">Hystrix</a>
+<ul class="sectlevel3">
+<li><a href="#_custom_concurrency_strategy">Custom Concurrency Strategy</a></li>
+<li><a href="#_manual_command_setting">Manual Command setting</a></li>
+</ul>
+</li>
 <li><a href="#_rxjava">RxJava</a></li>
-<li><a href="#_http_integration">HTTP integration</a></li>
-<li><a href="#_http_client_integration">HTTP client integration</a></li>
+<li><a href="#_http_integration">HTTP integration</a>
+<ul class="sectlevel3">
+<li><a href="#_http_filter">HTTP Filter</a></li>
+<li><a href="#_handlerinterceptor">HandlerInterceptor</a></li>
+<li><a href="#_async_servlet_support">Async Servlet support</a></li>
+</ul>
+</li>
+<li><a href="#_http_client_integration">HTTP client integration</a>
+<ul class="sectlevel3">
+<li><a href="#_synchronous_rest_template">Synchronous Rest Template</a></li>
+<li><a href="#_asynchronous_rest_template">Asynchronous Rest Template</a></li>
+</ul>
+</li>
 <li><a href="#_feign">Feign</a></li>
-<li><a href="#_asynchronous_communication">Asynchronous communication</a></li>
+<li><a href="#_asynchronous_communication">Asynchronous communication</a>
+<ul class="sectlevel3">
+<li><a href="#__async_annotated_methods">@Async annotated methods</a></li>
+<li><a href="#__scheduled_annotated_methods">@Scheduled annotated methods</a></li>
+<li><a href="#_executor_executorservice_and_scheduledexecutorservice">Executor, ExecutorService and ScheduledExecutorService</a></li>
+</ul>
+</li>
 <li><a href="#_messaging">Messaging</a></li>
 <li><a href="#_zuul">Zuul</a></li>
 </ul>
@@ -483,7 +521,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph">
-<p><strong>1.1.0.BUILD-SNAPSHOT</strong></p>
+<p><strong>1.2.0.BUILD-SNAPSHOT</strong></p>
 </div>
 <div class="paragraph">
 <p>Spring Cloud Sleuth implements a distributed tracing solution for <a href="http://cloud.spring.io">Spring Cloud</a>.</p>
@@ -1354,7 +1392,9 @@ fixed fraction of spans.</p>
 <td class="content">
 the <code>PercentageBasedSampler</code> is the default if you are using
 <code>spring-cloud-sleuth-zipkin</code> or <code>spring-cloud-sleuth-stream</code>. You can
-configure the exports using <code>spring.sleuth.sampler.percentage</code>.
+configure the exports using <code>spring.sleuth.sampler.percentage</code>. The passed
+value needs to be a double from <code>0.0</code> to <code>1.0</code> so it&#8217;s not a percentage.
+For backwards compatibility reasons we&#8217;re not changing the property name.
 </td>
 </tr>
 </table>
@@ -1642,7 +1682,7 @@ artificial like:</p>
 <div class="sect2">
 <h3 id="__spanname_annotation">@SpanName annotation</h3>
 <div class="paragraph">
-<p>You can do name the span explicitly via the <code>@SpanName</code> annotation.</p>
+<p>You can name the span explicitly via the <code>@SpanName</code> annotation.</p>
 </div>
 <div class="listingblock">
 <div class="content">
@@ -1754,19 +1794,13 @@ to your bean definition.</p>
 <div class="sect2">
 <h3 id="_http">HTTP</h3>
 <div class="paragraph">
-<p>For HTTP these are the beans responsible for creation of a Span from a <code>HttpServletRequest</code>
-  and filling in the <code>HttpServletResponse</code> with tracing information.</p>
+<p>For HTTP these are the beans responsible for creation of a Span from a <code>HttpServletRequest</code>.</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-java" data-lang="java">@Bean
 public SpanExtractor&lt;HttpServletRequest&gt; httpServletRequestSpanExtractor() {
     ...
-}
-
-@Bean
-public SpanInjector&lt;HttpServletResponse&gt; httpServletResponseSpanInjector() {
-    ...
 }</code></pre>
 </div>
 </div>
@@ -1796,35 +1830,101 @@ you have</p>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlight"><code class="language-java" data-lang="java">static class CustomHttpServletRequestSpanExtractor
-		implements SpanExtractor&lt;HttpServletRequest&gt; {
+<pre class="highlight"><code class="language-java" data-lang="java">static class CustomHttpSpanExtractor implements HttpSpanExtractor {
 
-	@Override
-	public Span joinTrace(HttpServletRequest carrier) {
-		long traceId = Span.hexToId(carrier.getHeader("correlationId"));
-		long spanId = Span.hexToId(carrier.getHeader("mySpanId"));
+	@Override public Span joinTrace(SpanTextMap carrier) {
+		Map&lt;String, String&gt; map = TextMapUtil.asMap(carrier);
+		long traceId = Span.hexToId(map.get("correlationid"));
+		long spanId = Span.hexToId(map.get("myspanid"));
 		// extract all necessary headers
 		Span.SpanBuilder builder = Span.builder().traceId(traceId).spanId(spanId);
 		// build rest of the Span
 		return builder.build();
 	}
+}
+
+static class CustomHttpSpanInjector implements HttpSpanInjector {
+
+	@Override
+	public void inject(Span span, SpanTextMap carrier) {
+		carrier.put("correlationId", Span.idToHex(span.getTraceId()));
+		carrier.put("mySpanId", Span.idToHex(span.getSpanId()));
+	}
 }</code></pre>
 </div>
 </div>
 <div class="paragraph">
-<p>The following <code>SpanInjector</code> could be created</p>
+<p>And you could register it like this:</p>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlight"><code class="language-java" data-lang="java">static class CustomHttpServletResponseSpanInjector
-		implements SpanInjector&lt;HttpServletResponse&gt; {
+<pre class="highlight"><code class="language-java" data-lang="java">@Bean
+HttpSpanInjector customHttpSpanInjector() {
+	return new CustomHttpSpanInjector();
+}
+
+@Bean
+HttpSpanExtractor customHttpSpanExtractor() {
+	return new CustomHttpSpanExtractor();
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Spring Cloud Sleuth does not add trace/span related headers to the Http Response for security reasons. If you need the headers then a custom <code>SpanInjector</code>
+that injects the headers into the Http Response and a Servlet filter which makes use of this can be added the following way:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">static class CustomHttpServletResponseSpanInjector extends ZipkinHttpSpanInjector {
 
 	@Override
-	public void inject(Span span, HttpServletResponse carrier) {
-		carrier.addHeader("correlationId", Span.idToHex(span.getTraceId()));
-		carrier.addHeader("mySpanId", Span.idToHex(span.getSpanId()));
-		// inject the rest of Span values to the header
+	public void inject(Span span, SpanTextMap carrier) {
+		super.inject(span, carrier);
+		carrier.put(Span.TRACE_ID_NAME, Span.idToHex(span.getTraceId()));
+		carrier.put(Span.SPAN_ID_NAME, Span.idToHex(span.getSpanId()));
 	}
+}
+
+static class HttpResponseInjectingTraceFilter extends GenericFilterBean {
+
+	private final Tracer tracer;
+	private final HttpSpanInjector spanInjector;
+
+	public HttpResponseInjectingTraceFilter(Tracer tracer, HttpSpanInjector spanInjector) {
+		this.tracer = tracer;
+		this.spanInjector = spanInjector;
+	}
+
+	@Override
+	public void doFilter(ServletRequest request, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
+		HttpServletResponse response = (HttpServletResponse) servletResponse;
+		Span currentSpan = this.tracer.getCurrentSpan();
+		this.spanInjector.inject(currentSpan, new HttpServletResponseTextMap(response));
+		filterChain.doFilter(request, response);
+	}
+
+	 class HttpServletResponseTextMap implements SpanTextMap {
+
+		 private final HttpServletResponse delegate;
+
+		 HttpServletResponseTextMap(HttpServletResponse delegate) {
+			 this.delegate = delegate;
+		 }
+
+		 @Override
+		 public Iterator&lt;Map.Entry&lt;String, String&gt;&gt; iterator() {
+			 Map&lt;String, String&gt; map = new HashMap&lt;&gt;();
+			 for (String header : this.delegate.getHeaderNames()) {
+				map.put(header, this.delegate.getHeader(header));
+			 }
+			 return map.entrySet().iterator();
+		 }
+
+		 @Override
+		 public void put(String key, String value) {
+			this.delegate.addHeader(key, value);
+		 }
+	 }
 }</code></pre>
 </div>
 </div>
@@ -1833,16 +1933,13 @@ you have</p>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlight"><code class="language-java" data-lang="java">@Bean
-@Primary
-SpanExtractor&lt;HttpServletRequest&gt; customHttpServletRequestSpanExtractor() {
-	return new CustomHttpServletRequestSpanExtractor();
+<pre class="highlight"><code class="language-java" data-lang="java">@Bean HttpSpanInjector customHttpServletResponseSpanInjector() {
+	return new CustomHttpServletResponseSpanInjector();
 }
 
 @Bean
-@Primary
-SpanInjector&lt;HttpServletResponse&gt; customHttpServletResponseSpanInjector() {
-	return new CustomHttpServletResponseSpanInjector();
+HttpResponseInjectingTraceFilter responseInjectingTraceFilter(Tracer tracer) {
+	return new HttpResponseInjectingTraceFilter(tracer, customHttpServletResponseSpanInjector());
 }</code></pre>
 </div>
 </div>