diff --git a/2.0.x/images/callouts/1.png b/2.0.x/images/callouts/1.png new file mode 100644 index 000000000..7d473430b Binary files /dev/null and b/2.0.x/images/callouts/1.png differ diff --git a/2.0.x/images/callouts/2.png b/2.0.x/images/callouts/2.png new file mode 100644 index 000000000..5d09341b2 Binary files /dev/null and b/2.0.x/images/callouts/2.png differ diff --git a/2.0.x/images/callouts/3.png b/2.0.x/images/callouts/3.png new file mode 100644 index 000000000..ef7b70047 Binary files /dev/null and b/2.0.x/images/callouts/3.png differ diff --git a/2.0.x/images/trace-id.png b/2.0.x/images/trace-id.png index 0603bb085..8d72b2cd8 100644 Binary files a/2.0.x/images/trace-id.png and b/2.0.x/images/trace-id.png differ diff --git a/2.0.x/index.html b/2.0.x/index.html index 4767d56bf..bc8f5b535 100644 --- a/2.0.x/index.html +++ b/2.0.x/index.html @@ -90,7 +90,7 @@ $(addBlockSwitches);
-

2.0.0.BUILD-SNAPSHOT

+

2.0.1.BUILD-SNAPSHOT

diff --git a/2.0.x/multi/images/callouts/1.png b/2.0.x/multi/images/callouts/1.png new file mode 100644 index 000000000..7d473430b Binary files /dev/null and b/2.0.x/multi/images/callouts/1.png differ diff --git a/2.0.x/multi/images/callouts/2.png b/2.0.x/multi/images/callouts/2.png new file mode 100644 index 000000000..5d09341b2 Binary files /dev/null and b/2.0.x/multi/images/callouts/2.png differ diff --git a/2.0.x/multi/images/callouts/3.png b/2.0.x/multi/images/callouts/3.png new file mode 100644 index 000000000..ef7b70047 Binary files /dev/null and b/2.0.x/multi/images/callouts/3.png differ diff --git a/2.0.x/multi/multi__additional_resources.html b/2.0.x/multi/multi__additional_resources.html index 657916079..244fa2c6d 100644 --- a/2.0.x/multi/multi__additional_resources.html +++ b/2.0.x/multi/multi__additional_resources.html @@ -1,3 +1,4 @@ - 2. Additional resources
2. Additional resources
Prev   Next

2. Additional resources

Marcin Grzejszczak talking about Spring Cloud Sleuth and Zipkin

click here to see the video

Prev   Next
1. Introduction Home 3. Features
\ No newline at end of file + 2. Additional Resources
2. Additional Resources
Prev   Next

2. Additional Resources

You can watch a video of Reshmi Krishna and Marcin Grzejszczak talking about Spring Cloud +Sleuth and Zipkin by clicking here.

You can check different setups of Sleuth and Brave in the openzipkin/sleuth-webmvc-example repository.

Prev   Next
1. Introduction Home 3. Features
\ No newline at end of file diff --git a/2.0.x/multi/multi__current_span.html b/2.0.x/multi/multi__current_span.html new file mode 100644 index 000000000..6df2346f9 --- /dev/null +++ b/2.0.x/multi/multi__current_span.html @@ -0,0 +1,19 @@ + + + 7. Current Span
7. Current Span
Prev   Next

7. Current Span

Brave supports a "current span" concept which represents the in-flight operation. +You can use Tracer.currentSpan() to add custom tags to a span and Tracer.nextSpan() to create a child of whatever is in-flight.

[Important]Important

In Sleuth, you can autowire the Tracer bean to retrieve the current span via +tracer.currentSpan() method. To retrieve the current context just call +tracer.currentSpan().context(). To get the current trace id as String +you can use the traceIdString() method like this: tracer.currentSpan().context().traceIdString().

7.1 Setting a span in scope manually

When writing new instrumentation, it is important to place a span you created in scope as the current span. +Not only does doing so let users access it with Tracer.currentSpan(), but it also allows customizations such as SLF4J MDC to see the current trace IDs.

Tracer.withSpanInScope(Span) facilitates this and is most conveniently employed by using the try-with-resources idiom. +Whenever external code might be invoked (such as proceeding an interceptor or otherwise), place the span in scope, as shown in the following example:

@Autowired Tracer tracer;
+
+try (SpanInScope ws = tracer.withSpanInScope(span)) {
+  return inboundRequest.invoke();
+} finally { // note the scope is independent of the span
+  span.finish();
+}

In edge cases, you may need to clear the current span temporarily (for example, launching a task that should not be associated with the current request). To do tso, pass null to withSpanInScope, as shown in the following example:

@Autowired Tracer tracer;
+
+try (SpanInScope cleared = tracer.withSpanInScope(null)) {
+  startBackgroundThread();
+}
Prev   Next
6. Current Tracing Component Home 8. Instrumentation
\ No newline at end of file diff --git a/2.0.x/multi/multi__current_tracing_component.html b/2.0.x/multi/multi__current_tracing_component.html new file mode 100644 index 000000000..75511b6ac --- /dev/null +++ b/2.0.x/multi/multi__current_tracing_component.html @@ -0,0 +1,7 @@ + + + 6. Current Tracing Component
6. Current Tracing Component
Prev   Next

6. Current Tracing Component

Brave supports a "current tracing component" concept, which should only be used when you have no other way to get a reference. +This was made for JDBC connections, as they often initialize prior to the tracing component.

The most recent tracing component instantiated is available through Tracing.current(). +You can also use Tracing.currentTracer() to get only the tracer. +If you use either of these methods, do not cache the result. +Instead, look them up each time you need them.

Prev   Next
5. Propagation Home 7. Current Span
\ No newline at end of file diff --git a/2.0.x/multi/multi__customizations.html b/2.0.x/multi/multi__customizations.html index 618062712..0b804d6c2 100644 --- a/2.0.x/multi/multi__customizations.html +++ b/2.0.x/multi/multi__customizations.html @@ -1,136 +1,71 @@ - 9. Customizations
9. Customizations
Prev   Next

9. Customizations

Thanks to the SpanInjector and SpanExtractor you can customize the way spans -are created and propagated.

There are currently two built-in ways to pass tracing information between processes:

Span ids are extracted from Zipkin-compatible (B3) headers (either Message -or HTTP headers), to start or join an existing trace. Trace information is -injected into any outbound requests so the next hop can extract them.

The key change in comparison to the previous versions of Sleuth is that Sleuth is implementing -the Open Tracing’s TextMap notion. In Sleuth it’s called SpanTextMap. Basically the idea -is that any means of communication (e.g. message, http request, etc.) can be abstracted via -a SpanTextMap. This abstraction defines how one can insert data into the carrier and -how to retrieve it from there. Thanks to this if you want to instrument a new HTTP library -that uses a FooRequest as a mean of sending HTTP requests then you have to create an -implementation of a SpanTextMap that delegates calls to FooRequest in terms of retrieval -and insertion of HTTP headers.

9.1 Spring Integration

For Spring Integration there are 2 interfaces responsible for creation of a Span from a Message. -These are:

  • MessagingSpanTextMapExtractor
  • MessagingSpanTextMapInjector

You can override them by providing your own implementation.

9.2 HTTP

For HTTP there are 2 interfaces responsible for creation of a Span from a Message. -These are:

  • HttpSpanExtractor
  • HttpSpanInjector

You can override them by providing your own implementation.

9.3 Example

Let’s assume that instead of the standard Zipkin compatible tracing HTTP header names -you have

  • for trace id - correlationId
  • for span id - mySpanId

This is a an example of a SpanExtractor

static class CustomHttpSpanExtractor implements HttpSpanExtractor {
+   12. Customizations
12. Customizations
Prev   Next
12. Customizations
12.1 HTTP
If a customization of client / server parsing of the HTTP related spans is required,
+just register a bean of type brave.http.HttpClientParser or
+brave.http.HttpServerParser. If client /server sampling is required, just
+register a bean of type brave.http.HttpSampler and name the bean
+ sleuthClientSampler for client sampler and sleuthServerSampler for server sampler.
+ For your convenience the @ClientSampler and @ServerSampler
+ annotations can be used to inject the proper beans or to
+ reference the bean names via their static String NAME fields.
Check out Brave’s code to see an example of how to make a path-based sampler
+https://github.com/openzipkin/brave/tree/master/instrumentation/http#sampling-policy
If you want to completely rewrite the HttpTracing bean you can use the SkipPatternProvider
+interface to retrieve the URL Pattern for spans that should be not sampled. Below you can see
+an example of usage of SkipPatternProvider inside a server side, HttpSampler.
@Configuration
+class Config {
+  @Bean(name = ServerSampler.NAME)
+  HttpSampler myHttpSampler(SkipPatternProvider provider) {
+  	Pattern pattern = provider.skipPattern();
+  	return new HttpSampler() {
 
-	@Override public Span joinTrace(SpanTextMap carrier) {
-		Map<String, String> 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.traceIdString());
-		carrier.put("mySpanId", Span.idToHex(span.getSpanId()));
-	}
-}
And you could register it like this:
@Bean
-HttpSpanInjector customHttpSpanInjector() {
-	return new CustomHttpSpanInjector();
-}
-
-@Bean
-HttpSpanExtractor customHttpSpanExtractor() {
-	return new CustomHttpSpanExtractor();
-}
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 SpanInjector
-that injects the headers into the Http Response and a Servlet filter which makes use of this can be added the following way:
static class CustomHttpServletResponseSpanInjector extends ZipkinHttpSpanInjector {
-
-	@Override
-	public void inject(Span span, SpanTextMap carrier) {
-		super.inject(span, carrier);
-		carrier.put(Span.TRACE_ID_NAME, span.traceIdString());
-		carrier.put(Span.SPAN_ID_NAME, Span.idToHex(span.getSpanId()));
-	}
-}
-
-static class HttpResponseInjectingTraceFilter extends GenericFilterBean {
+  		@Override public <Req> Boolean trySample(HttpAdapter<Req, ?> adapter, Req request) {
+  			String url = adapter.path(request);
+  			boolean shouldSkip = pattern.matcher(url).matches();
+  			if (shouldSkip) {
+  				return false;
+  			}
+  			return null;
+  		}
+  	};
+  }
+}
12.2 TracingFilter
You can also modify the behavior of the TracingFilter, which is the component that is responsible for processing the input HTTP request and adding tags basing on the HTTP response.
+You can customize the tags or modify the response headers by registering your own instance of the TracingFilter bean.
In the following example, we register the TracingFilter bean, add the ZIPKIN-TRACE-ID response header containing the current Span’s trace id, and add a tag with key custom and a value tag to the span.
@Component
+@Order(TraceWebServletAutoConfiguration.TRACING_FILTER_ORDER + 1)
+class MyFilter extends GenericFilterBean {
 
 	private final Tracer tracer;
-	private final HttpSpanInjector spanInjector;
 
-	public HttpResponseInjectingTraceFilter(Tracer tracer, HttpSpanInjector spanInjector) {
+	MyFilter(Tracer tracer) {
 		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);
+	@Override public void doFilter(ServletRequest request, ServletResponse response,
+			FilterChain chain) throws IOException, ServletException {
+		Span currentSpan = this.tracer.currentSpan();
+		if (currentSpan == null) {
+			chain.doFilter(request, response);
+			return;
+		}
+		// for readability we're returning trace id in a hex form
+		((HttpServletResponse) response)
+				.addHeader("ZIPKIN-TRACE-ID",
+						currentSpan.context().traceIdString());
+		// we can also add some custom tags
+		currentSpan.tag("custom", "tag");
+		chain.doFilter(request, response);
 	}
-
-	 class HttpServletResponseTextMap implements SpanTextMap {
-
-		 private final HttpServletResponse delegate;
-
-		 HttpServletResponseTextMap(HttpServletResponse delegate) {
-			 this.delegate = delegate;
-		 }
-
-		 @Override
-		 public Iterator<Map.Entry<String, String>> iterator() {
-			 Map<String, String> map = new HashMap<>();
-			 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);
-		 }
-	 }
-}
And you could register them like this:
@Bean HttpSpanInjector customHttpServletResponseSpanInjector() {
-	return new CustomHttpServletResponseSpanInjector();
+}
12.3 Custom service name
By default, Sleuth assumes that, when you send a span to Zipkin, you want the span’s service name to be equal to the value of the spring.application.name property.
+That is not always the case, though.
+There are situations in which you want to explicitly provide a different service name for all spans coming from your application.
+To achieve that, you can pass the following property to your application to override that value (the example is for a service named myService):
spring.zipkin.service.name: myService
12.4 Customization of Reported Spans
Before reporting spans (for example, to Zipkin) you may want to modify that span in some way.
+You can do so by using the SpanAdjuster interface.
In Sleuth, we generate spans with a fixed name.
+Some users want to modify the name depending on values of tags.
+You can implement the SpanAdjuster interface to alter that name.
The following example shows how to register two beans that implement SpanAdjuster:
@Bean SpanAdjuster adjusterOne() {
+	return span -> span.toBuilder().name("foo").build();
 }
 
-@Bean
-HttpResponseInjectingTraceFilter responseInjectingTraceFilter(Tracer tracer) {
-	return new HttpResponseInjectingTraceFilter(tracer, customHttpServletResponseSpanInjector());
-}
9.4 TraceFilter
You can also modify the behaviour of the TraceFilter - the component that is responsible
-for processing the input HTTP request and adding tags basing on the HTTP response. You can customize
-the tags, or modify the response headers by registering your own instance of the TraceFilter bean.
In the following example we will register the TraceFilter bean and we will add the
-ZIPKIN-TRACE-ID response header containing the current Span’s trace id. Also we will
-add to the Span a tag with key custom and a value tag.
@Bean
-TraceFilter myTraceFilter(BeanFactory beanFactory, final Tracer tracer) {
-	return new TraceFilter(beanFactory) {
-		@Override protected void addResponseTags(HttpServletResponse response,
-				Throwable e) {
-			// execute the default behaviour
-			super.addResponseTags(response, e);
-			// for readability we're returning trace id in a hex form
-			response.addHeader("ZIPKIN-TRACE-ID",
-					Span.idToHex(tracer.getCurrentSpan().getTraceId()));
-			// we can also add some custom tags
-			tracer.addTag("custom", "tag");
-		}
-	};
-}
9.5 Custom SA tag in Zipkin
Sometimes you want to create a manual Span that will wrap a call to an external service which is not instrumented.
-What you can do is to create a span with the peer.service tag that will contain a value of the service that you want to call.
-Below you can see an example of a call to Redis that is wrapped in such a span.
Unresolved directive in spring-cloud-sleuth.adoc - include::../../../..//spring-cloud-sleuth-zipkin-legacy/src/test/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporterTest.java[tags=service_name,indent=0]
[Important]Important
Remember not to add both peer.service tag and the SA tag! You have to add only peer.service.
9.6 Custom service name
By default Sleuth assumes that when you send a span to Zipkin, you want the span’s service name
- to be equal to spring.application.name value. That’s not always the case though. There
- are situations in which you want to explicitly provide a different service name for all spans coming
- from your application. To achieve that it’s enough to just pass the following property
- to your application to override that value (example for foo service name):
spring.zipkin.service.name: foo
9.7 Customization of reported spans
Before reporting spans to e.g. Zipkin you can be interested in modifying that span in some way.
- You can achieve that by using the SpanAdjuster interface.
Example of usage:
In Sleuth we’re generating spans with a fixed name. Some users want to modify the name depending on values
-of tags. Implementation of the SpanAdjuster interface can be used to alter that name. Example:
@Bean
-SpanAdjuster customSpanAdjuster() {
-    return span -> span.toBuilder().name(scrub(span.getName())).build();
-}
This will lead in changing the name of the reported span just before it gets sent to Zipkin.
[Important]Important
Your SpanReporter should inject the SpanAdjuster and
- allow span manipulation before the actual reporting is done.
9.8 Host locator
In order to define the host that is corresponding to a particular span we need to resolve the host name
-and port. The default approach is to take it from server properties. If those for some reason are not set
-then we’re trying to retrieve the host name from the network interfaces.
If you have the discovery client enabled and prefer to retrieve the host address from the registered
-instance in a service registry then you have to set the property (it’s applicable for both HTTP and
-Stream based span reporting).
spring.zipkin.locator.discovery.enabled: true
Prev   Next
8. Managing spans with annotations Home 10. Sending spans to Zipkin

\ No newline at end of file
+@Bean SpanAdjuster adjusterTwo() {
+	return span -> span.toBuilder().name(span.name() + " bar").build();
+}

The preceding example results in changing the name of the reported span to foo bar, just before it gets reported (for example, to Zipkin).

12.5 Host Locator

[Important]Important

This section is about defining host from service discovery. +It is NOT about finding Zipkin through service discovery.

To define the host that corresponds to a particular span, we need to resolve the host name and port. +The default approach is to take these values from server properties. +If those are not set, we try to retrieve the host name from the network interfaces.

If you have the discovery client enabled and prefer to retrieve the host address from the registered instance in a service registry, you have to set the spring.zipkin.locator.discovery.enabled property (it is applicable for both HTTP-based and Stream-based span reporting), as follows:

spring.zipkin.locator.discovery.enabled: true
Prev   Next
11. Managing Spans with Annotations Home 13. Sending Spans to Zipkin
\ No newline at end of file diff --git a/2.0.x/multi/multi__features.html b/2.0.x/multi/multi__features.html index bb705d5d4..6c2740f7c 100644 --- a/2.0.x/multi/multi__features.html +++ b/2.0.x/multi/multi__features.html @@ -1,20 +1,126 @@ - 3. Features
3. Features
Prev   Next

3. Features

[Caution]Caution

spring-cloud-sleuth-stream is deprecated and should no longer be used.

[Important]Important

If you use Zipkin, configure the probability of spans exported by setting spring.sleuth.sampler.probability +(default: 0.1, which is 10 percent). Otherwise, you might think that Sleuth is not working be cause it omits some spans.

[Note]Note

The SLF4J MDC is always set and logback users immediately see the trace and span IDs in logs per the example +shown earlier. +Other logging systems have to configure their own formatter to get the same result. +The default is as follows: +logging.pattern.level set to %5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}] +(this is a Spring Boot feature for logback users). +If you do not use SLF4J, this pattern is NOT automatically applied.

3.1 Introduction to Brave

[Important]Important

Starting with version 2.0.0, Spring Cloud Sleuth uses +Brave as the tracing library. +For your convenience, we embed part of the Brave’s docs here.

[Important]Important

In the vast majority of cases you need to just use the Tracer +or SpanCustomizer beans from Brave that Sleuth provides. The documentation below contains +a high overview of what Brave is and how it works.

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.

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).

3.1.1 Tracing

Most importantly, you need a brave.Tracer, configured to report to Zipkin.

The following example setup sends trace data (spans) to Zipkin over HTTP (as opposed to Kafka):

class MyClass {
+
+    private final Tracer tracer;
+
+    // Tracer will be autowired
+    MyClass(Tracer tracer) {
+        this.tracer = tracer;
+    }
+
+    void doSth() {
+        Span span = tracer.newTrace().name("encode").start();
+        // ...
+    }
+}
[Important]Important

If your span contains a name longer than 50 chars, then that name is truncated to 50 chars. +Your names have to be explicit and concrete. +Big names lead to latency issues and sometimes even thrown exceptions.

The tracer creates and joins spans that model the latency of potentially distributed work. +It can employ sampling to reduce overhead during the process, to reduce the amount of data sent to Zipkin, or both.

Spans returned by a tracer report data to Zipkin when finished or do nothing if unsampled. +After starting a span, you can annotate events of interest or add tags containing details or lookup keys.

Spans have a context that includes trace identifiers that place the span at the correct spot in the tree representing the distributed operation.

3.1.2 Local Tracing

When tracing local code, you can run it inside a span, as shown in the following example:

@Autowired Tracer tracer;
+
+Span span = tracer.newTrace().name("encode").start();
+try {
+  doSomethingExpensive();
+} finally {
+  span.finish();
+}

In the preceding example, the span is the root of the trace. +In many cases, the span is part of an existing trace. +When this is the case, call newChild instead of newTrace, as shown in the following example:

@Autowired Tracer tracer;
+
+Span span = tracer.newChild(root.context()).name("encode").start();
+try {
+  doSomethingExpensive();
+} finally {
+  span.finish();
+}

3.1.3 Customizing Spans

Once you have a span, you can add tags to it. +The tags can be used as lookup keys or details. +For example, you might add a tag with your runtime version, as shown in the following example:

span.tag("clnt/finagle.version", "6.36.0");

When exposing the ability to customize spans to third parties, prefer brave.SpanCustomizer as opposed to brave.Span. +The former is simpler to understand and test and does not tempt users with span lifecycle hooks.

interface MyTraceCallback {
+  void request(Request request, SpanCustomizer customizer);
+}

Since brave.Span implements brave.SpanCustomizer, you can pass it to users, as shown in the following example:

for (MyTraceCallback callback : userCallbacks) {
+  callback.request(request, span);
+}

3.1.4 Implicitly Looking up the Current Span

Sometimes, you do not know if a trace is in progress or not, and you do not want users to do null checks. +brave.CurrentSpanCustomizer handles this problem by adding data to any span that’s in progress or drops, as shown in the following example:

Ex.

// The user code can then inject this without a chance of it being null.
+@Autowired SpanCustomizer span;
+
+void userCode() {
+  span.annotate("tx.started");
+  ...
+}

3.1.5 RPC tracing

[Tip]Tip

Check for instrumentation written here and Zipkin’s list before rolling your own RPC instrumentation.

RPC tracing is often done automatically by interceptors. Behind the scenes, they add tags and events that relate to their role in an RPC operation.

The following example shows how to add a client span:

@Autowired Tracer tracer;
+
+// before you send a request, add metadata that describes the operation
+span = tracer.newTrace().name("get").type(CLIENT);
+span.tag("clnt/finagle.version", "6.36.0");
+span.tag(TraceKeys.HTTP_PATH, "/api");
+span.remoteEndpoint(Endpoint.builder()
+    .serviceName("backend")
+    .ipv4(127 << 24 | 1)
+    .port(8080).build());
+
+// when the request is scheduled, start the span
+span.start();
+
+// if you have callbacks for when data is on the wire, note those events
+span.annotate(Constants.WIRE_SEND);
+span.annotate(Constants.WIRE_RECV);
+
+// when the response is complete, finish the span
+span.finish();

One-Way tracing

Sometimes, you need to model an asynchronous operation where there is a +request but no response. In normal RPC tracing, you use span.finish() +to indicate that the response was received. In one-way tracing, you use +span.flush() instead, as you do not expect a response.

The following example shows how a client might model a one-way operation:

@Autowired Tracer tracer;
+
+// start a new span representing a client request
+oneWaySend = tracer.newSpan(parent).kind(Span.Kind.CLIENT);
+
+// Add the trace context to the request, so it can be propagated in-band
+tracing.propagation().injector(Request::addHeader)
+                     .inject(oneWaySend.context(), request);
+
+// fire off the request asynchronously, totally dropping any response
+request.execute();
+
+// start the client side and flush instead of finish
+oneWaySend.start().flush();

The following example shows how a server might handle a one-way operation:

@Autowired Tracing tracing;
+@Autowired Tracer tracer;
+
+// pull the context out of the incoming request
+extractor = tracing.propagation().extractor(Request::getHeader);
+
+// convert that context to a span which you can name and add tags to
+oneWayReceive = nextSpan(tracer, extractor.extract(request))
+    .name("process-request")
+    .kind(SERVER)
+    ... add tags etc.
+
+// start the server side and flush instead of finish
+oneWayReceive.start().flush();
+
+// you should not modify this span anymore as it is complete. However,
+// you can create children to represent follow-up work.
+next = tracer.newSpan(oneWayReceive.context()).name("step2").start();
Prev   Next
2. Additional Resources Home 4. Sampling
\ No newline at end of file diff --git a/2.0.x/multi/multi__instrumentation.html b/2.0.x/multi/multi__instrumentation.html index 77cf9b176..82c1d45de 100644 --- a/2.0.x/multi/multi__instrumentation.html +++ b/2.0.x/multi/multi__instrumentation.html @@ -1,18 +1,6 @@ - 5. Instrumentation
5. Instrumentation
Prev   Next

5. Instrumentation

Spring Cloud Sleuth instruments all your Spring application -automatically, so you shouldn’t have to do anything to activate -it. The instrumentation is added using a variety of technologies -according to the stack that is available, e.g. for a servlet web -application we use a Filter, and for Spring Integration we use -ChannelInterceptors.

You can customize the keys used in span tags. To limit the volume of -span data, by default an HTTP request will be tagged only with a -handful of metadata like the status code, host and URL. You can add -request headers by configuring spring.sleuth.keys.http.headers (a -list of header names).

[Note]Note

Remember that tags are only collected and exported if there is a -Sampler that allows it (by default there is not, so there is no -danger of accidentally collecting too much data without configuring -something).

[Note]Note

Currently the instrumentation in Spring Cloud Sleuth is eager - it means that -we’re actively trying to pass the tracing context between threads. Also timing events -are captured even when sleuth isn’t exporting data to a tracing system. -This approach may change in the future towards being lazy on this matter.

Prev   Next
4. Sampling Home 6. Span lifecycle
\ No newline at end of file + 8. Instrumentation
8. Instrumentation
Prev   Next

8. Instrumentation

Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it. +The instrumentation is added by using a variety of technologies according to the stack that is available. For example, for a servlet web application, we use a Filter, and, for Spring Integration, we use ChannelInterceptors.

You can customize the keys used in span tags. +To limit the volume of span data, an HTTP request is, by default, tagged only with a handful of metadata, such as the status code, the host, and the URL. +You can add request headers by configuring spring.sleuth.keys.http.headers (a list of header names).

[Note]Note

Tags are collected and exported only if there is a Sampler that allows it. By default, there is no such Sampler, to ensure that there is no danger of accidentally collecting too much data without configuring something).

Prev   Next
7. Current Span Home 9. Span lifecycle
\ No newline at end of file diff --git a/2.0.x/multi/multi__integrations.html b/2.0.x/multi/multi__integrations.html index 94def53ee..aa2def57b 100644 --- a/2.0.x/multi/multi__integrations.html +++ b/2.0.x/multi/multi__integrations.html @@ -1,6 +1,8 @@ - 13. Integrations
13. Integrations
Prev   Next

13. Integrations

13.1 Runnable and Callable

If you’re wrapping your logic in Runnable or Callable it’s enough to wrap those classes in their Sleuth representative.

Example for Runnable:

Runnable runnable = new Runnable() {
+   15. Integrations
15. Integrations
Prev   Next
15. Integrations
15.1 OpenTracing
Spring Cloud Sleuth is compatible with OpenTracing.
+If you have OpenTracing on the classpath, we automatically register the OpenTracing Tracer bean.
+If you wish to disable this, set spring.sleuth.opentracing.enabled to false
15.2 Runnable and Callable
If you wrap your logic in Runnable or Callable, you can wrap those classes in their Sleuth representative, as shown in the following example for Runnable:
Runnable runnable = new Runnable() {
 	@Override
 	public void run() {
 		// do some work
@@ -12,10 +14,11 @@
 	}
 };
 // Manual `TraceRunnable` creation with explicit "calculateTax" Span name
-Runnable traceRunnable = new TraceRunnable(tracer, spanNamer, runnable, "calculateTax");
-// Wrapping `Runnable` with `Tracer`. The Span name will be taken either from the
-// `@SpanName` annotation or from `toString` method
-Runnable traceRunnableFromTracer = tracer.wrap(runnable);
Example for Callable:
Callable<String> callable = new Callable<String>() {
+Runnable traceRunnable = new TraceRunnable(tracing, spanNamer, runnable,
+		"calculateTax");
+// Wrapping `Runnable` with `Tracing`. That way the current span will be available
+// in the thread of `Runnable`
+Runnable traceRunnableFromTracer = tracing.currentTraceContext().wrap(runnable);
The following example shows how to do so for Callable:
Callable<String> callable = new Callable<String>() {
 	@Override
 	public String call() throws Exception {
 		return someLogic();
@@ -27,82 +30,64 @@ Runnable traceRunnableFromTracer = tracer.wrap(runnable);
Example for // Manual `TraceCallable` creation with explicit "calculateTax" Span name
-Callable<String> traceCallable = new TraceCallable<>(tracer, spanNamer, callable, "calculateTax");
-// Wrapping `Callable` with `Tracer`. The Span name will be taken either from the
-// `@SpanName` annotation or from `toString` method
-Callable<String> traceCallableFromTracer = tracer.wrap(callable);

That way you will ensure that a new Span is created and closed for each execution.

13.2 Hystrix

13.2.1 Custom Concurrency Strategy

We’re registering a custom HystrixConcurrencyStrategy -that wraps all Callable instances into their Sleuth representative - -the TraceCallable. The strategy either starts or continues a span depending on the fact whether tracing was already going -on before the Hystrix command was called. To disable the custom Hystrix Concurrency Strategy set the spring.sleuth.hystrix.strategy.enabled to false.

13.2.2 Manual Command setting

Assuming that you have the following HystrixCommand:

HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) {
+Callable<String> traceCallable = new TraceCallable<>(tracing, spanNamer, callable,
+		"calculateTax");
+// Wrapping `Callable` with `Tracing`. That way the current span will be available
+// in the thread of `Callable`
+Callable<String> traceCallableFromTracer = tracing.currentTraceContext().wrap(callable);

That way, you ensure that a new span is created and closed for each execution.

15.3 Hystrix

15.3.1 Custom Concurrency Strategy

We register a custom HystrixConcurrencyStrategy called TraceCallable that wraps all Callable instances in their Sleuth representative. +The strategy either starts or continues a span, depending on whether tracing was already going on before the Hystrix command was called. +To disable the custom Hystrix Concurrency Strategy, set the spring.sleuth.hystrix.strategy.enabled to false.

15.3.2 Manual Command setting

Assume that you have the following HystrixCommand:

HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) {
 	@Override
 	protected String run() throws Exception {
 		return someLogic();
 	}
-};

In order to pass the tracing information you have to wrap the same logic in the Sleuth version of the HystrixCommand which is the -TraceCommand:

TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, traceKeys, setter) {
+};

To pass the tracing information, you have to wrap the same logic in the Sleuth version of the HystrixCommand, which is called +TraceCommand, as shown in the following example:

TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, setter) {
 	@Override
 	public String doRun() throws Exception {
 		return someLogic();
 	}
-};

13.3 RxJava

We’re registering a custom RxJavaSchedulersHook -that wraps all Action0 instances into their Sleuth representative - -the TraceAction. The hook either starts or continues a span depending on the fact whether tracing was already going -on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the spring.sleuth.rxjava.schedulers.hook.enabled to false.

You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list -of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property.

13.4 HTTP integration

Features from this section can be disabled by providing the spring.sleuth.web.enabled property with value equal to false.

13.4.1 HTTP Filter

Via the TraceFilter all sampled incoming requests result in creation of a Span. That Span’s name is http: + the path to which - the request was sent. E.g. if the request was sent to /foo/bar then the name will be http:/foo/bar. You can configure which URIs you would - like to skip via the spring.sleuth.web.skipPattern property. If you have ManagementServerProperties on classpath then - its value of contextPath gets appended to the provided skip pattern.

13.4.2 HandlerInterceptor

Since we want the span names to be precise we’re using a TraceHandlerInterceptor that either wraps an - existing HandlerInterceptor or is added directly to the list of existing HandlerInterceptors. The - TraceHandlerInterceptor adds a special request attribute to the given HttpServletRequest. If the - the TraceFilter doesn’t see this attribute set it will create a "fallback" span which is an additional - span created on the server side so that the trace is presented properly in the UI. Seeing that most likely - signifies that there is a missing instrumentation. In that case please file an issue in Spring Cloud Sleuth.

13.4.3 Async Servlet support

If your controller returns a Callable or a WebAsyncTask Spring Cloud Sleuth will continue the existing span instead of creating a new one.

13.4.4 WebFlux support

Via the TraceWebFilter all sampled incoming requests result in creation of a Span. That Span’s name is http: + the path to which - the request was sent. E.g. if the request was sent to /foo/bar then the name will be http:/foo/bar. You can configure which URIs you would - like to skip via the spring.sleuth.web.skipPattern property. If you have ManagementServerProperties on classpath then - its value of contextPath gets appended to the provided skip pattern.

13.5 HTTP client integration

13.5.1 Synchronous Rest Template

We’re injecting a RestTemplate interceptor that ensures that all the tracing information is passed to the requests. Each time a -call is made a new Span is created. It gets closed upon receiving the response. In order to block the synchronous RestTemplate features -just set spring.sleuth.web.client.enabled to false.

[Important]Important

You have to register RestTemplate as a bean so that the interceptors will get injected. -If you create a RestTemplate instance with a new keyword then the instrumentation WILL NOT work.

13.5.2 Asynchronous Rest Template

[Important]Important

A traced version of an AsyncRestTemplate bean is registered for you out of the box. If you -have your own bean you have to wrap it in a TraceAsyncRestTemplate representation. The best solution -is to only customize the ClientHttpRequestFactory and / or AsyncClientHttpRequestFactory. -If you have your own AsyncRestTemplate and you don’t wrap it your calls WILL NOT GET TRACED.

Custom instrumentation is set to create and close Spans upon sending and receiving requests. You can customize the ClientHttpRequestFactory -and the AsyncClientHttpRequestFactory by registering your beans. Remember to use tracing compatible implementations (e.g. don’t forget to -wrap ThreadPoolTaskScheduler in a TraceAsyncListenableTaskExecutor). Example of custom request factories:

@EnableAutoConfiguration
-@Configuration
-public static class TestConfiguration {
-
-	@Bean
-	ClientHttpRequestFactory mySyncClientFactory() {
-		return new MySyncClientHttpRequestFactory();
-	}
-
-	@Bean
-	AsyncClientHttpRequestFactory myAsyncClientFactory() {
-		return new MyAsyncClientHttpRequestFactory();
-	}
-}

To block the AsyncRestTemplate features set spring.sleuth.web.async.client.enabled to false. -To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapper set spring.sleuth.web.async.client.factory.enabled -to false. If you don’t want to create AsyncRestClient at all set spring.sleuth.web.async.client.template.enabled to false.

Multiple Asynchronous Rest Templates

Sometimes you need to use multiple implementations of Asynchronous Rest Template. In the following snippet you -can see an example of how to set up such a custom AsyncRestTemplate.

@Configuration
+};

15.4 RxJava

We registering a custom RxJavaSchedulersHook that wraps all Action0 instances in their Sleuth representative, which is called TraceAction. +The hook either starts or continues a span, depending on whether tracing was already going on before the Action was scheduled. +To disable the custom RxJavaSchedulersHook, set the spring.sleuth.rxjava.schedulers.hook.enabled to false.

You can define a list of regular expressions for thread names for which you do not want spans to be created. +To do so, provide a comma-separated list of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property.

[Important]Important

The suggest approach to reactive programming and Sleuth is to use +the Reactor support.

15.5 HTTP integration

Features from this section can be disabled by setting the spring.sleuth.web.enabled property with value equal to false.

15.5.1 HTTP Filter

Through the TracingFilter, all sampled incoming requests result in creation of a Span. +That Span’s name is http: + the path to which the request was sent. +For example, if the request was sent to /this/that then the name will be http:/this/that. +You can configure which URIs you would like to skip by setting the spring.sleuth.web.skipPattern property. +If you have ManagementServerProperties on classpath, its value of contextPath gets appended to the provided skip pattern. +If you want to reuse the Sleuth’s default skip patterns and just append your own, pass those patterns by using the spring.sleuth.web.additionalSkipPattern.

15.5.2 HandlerInterceptor

Since we want the span names to be precise, we use a TraceHandlerInterceptor that either wraps an existing HandlerInterceptor or is added directly to the list of existing HandlerInterceptors. +The TraceHandlerInterceptor adds a special request attribute to the given HttpServletRequest. +If the the TracingFilter does not see this attribute, it creates a "fallback" span, which is an additional span created on the server side so that the trace is presented properly in the UI. +If that happens, there is probably missing instrumentation. +In that case, please file an issue in Spring Cloud Sleuth.

15.5.3 Async Servlet support

If your controller returns a Callable or a WebAsyncTask, Spring Cloud Sleuth continues the existing span instead of creating a new one.

15.5.4 WebFlux support

Through TraceWebFilter, all sampled incoming requests result in creation of a Span. +That Span’s name is http: + the path to which the request was sent. +For example, if the request was sent to /this/that, the name is http:/this/that. +You can configure which URIs you would like to skip by using the spring.sleuth.web.skipPattern property. +If you have ManagementServerProperties on the classpath, its value of contextPath gets appended to the provided skip pattern. +If you want to reuse Sleuth’s default skip patterns and append your own, pass those patterns by using the spring.sleuth.web.additionalSkipPattern.

15.5.5 Dubbo RPC support

Via the integration with Brave, Spring Cloud Sleuth supports Dubbo. +It’s enough to add the brave-instrumentation-dubbo-rpc dependency:

<dependency>
+    <groupId>io.zipkin.brave</groupId>
+    <artifactId>brave-instrumentation-dubbo-rpc</artifactId>
+</dependency>

You need to also set a dubbo.properties file with the following contents:

dubbo.provider.filter=tracing
+dubbo.consumer.filter=tracing

You can read more about Brave - Dubbo integration here. +An example of Spring Cloud Sleuth and Dubbo can be found here.

15.6 HTTP Client Integration

15.6.1 Synchronous Rest Template

We inject a RestTemplate interceptor to ensure that all the tracing information is passed to the requests. +Each time a call is made, a new Span is created. +It gets closed upon receiving the response. +To block the synchronous RestTemplate features, set spring.sleuth.web.client.enabled to false.

[Important]Important

You have to register RestTemplate as a bean so that the interceptors get injected. +If you create a RestTemplate instance with a new keyword, the instrumentation does NOT work.

15.6.2 Asynchronous Rest Template

[Important]Important

Starting with Sleuth 2.0.0, we no longer register a bean of AsyncRestTemplate type. +It is up to you to create such a bean. +Then we instrument it.

To block the AsyncRestTemplate features, set spring.sleuth.web.async.client.enabled to false. +To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapper, set spring.sleuth.web.async.client.factory.enabled +to false. +If you do not want to create AsyncRestClient at all, set spring.sleuth.web.async.client.template.enabled to false.

Multiple Asynchronous Rest Templates

Sometimes you need to use multiple implementations of the Asynchronous Rest Template. +In the following snippet, you can see an example of how to set up such a custom AsyncRestTemplate:

@Configuration
 @EnableAutoConfiguration
 static class Config {
-	@Autowired Tracer tracer;
-	@Autowired HttpTraceKeysInjector httpTraceKeysInjector;
-	@Autowired HttpSpanInjector spanInjector;
 
 	@Bean(name = "customAsyncRestTemplate")
-	public AsyncRestTemplate traceAsyncRestTemplate(@Qualifier("customHttpRequestFactoryWrapper")
-			TraceAsyncClientHttpRequestFactoryWrapper wrapper, ErrorParser errorParser) {
-		return new TraceAsyncRestTemplate(wrapper, this.tracer, errorParser);
-	}
-
-	@Bean(name = "customHttpRequestFactoryWrapper")
-	public TraceAsyncClientHttpRequestFactoryWrapper traceAsyncClientHttpRequestFactory() {
-		return new TraceAsyncClientHttpRequestFactoryWrapper(this.tracer,
-				this.spanInjector,
-				asyncClientFactory(),
-				clientHttpRequestFactory(),
-				this.httpTraceKeysInjector);
+	public AsyncRestTemplate traceAsyncRestTemplate() {
+		return new AsyncRestTemplate(asyncClientFactory(), clientHttpRequestFactory());
 	}
 
 	private ClientHttpRequestFactory clientHttpRequestFactory() {
@@ -116,32 +101,32 @@ can see an example of how to set up such a custom AsyncRes
 		//CUSTOMIZE HERE
 		return factory;
 	}
-}

13.5.3 WebClient

We inject a ExchangeFilterFunction implementation that creates a span and via on success and on -error callbacks takes care of closing client side spans.

[Important]Important

You have to register WebClient as a bean so that the tracing instrumention gets applied. -If you create a WebClient instance with a new keyword then the instrumentation WILL NOT work.

13.5.4 Traverson

If you’re using the Traverson library -it’s enough for you to inject a RestTemplate as a bean into your Traverson object. Since RestTemplate -is already intercepted, you will get full support of tracing in your client. Below you can find a pseudo code -of how to do that:

@Autowired RestTemplate restTemplate;
+}

15.6.3 WebClient

We inject a ExchangeFilterFunction implementation that creates a span and, through on-success and on-error callbacks, takes care of closing client-side spans.

To block this feature, set spring.sleuth.web.client.enabled to false.

[Important]Important

You have to register WebClient as a bean so that the tracing instrumentation gets applied. +If you create a WebClient instance with a new keyword, the instrumentation does NOT work.

15.6.4 Traverson

If you use the Traverson library, you can inject a RestTemplate as a bean into your Traverson object. +Since RestTemplate is already intercepted, you get full support for tracing in your client. The following pseudo code +shows how to do that:

@Autowired RestTemplate restTemplate;
 
 Traverson traverson = new Traverson(URI.create("http://some/address"),
     MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate);
-// use Traverson

13.6 Feign

By default Spring Cloud Sleuth provides integration with feign via the TraceFeignClientAutoConfiguration. You can disable it entirely -by setting spring.sleuth.feign.enabled to false. If you do so then no Feign related instrumentation will take place.

Part of Feign instrumentation is done via a FeignBeanPostProcessor. You can disable it by providing the spring.sleuth.feign.processor.enabled equal to false. -If you set it like this then Spring Cloud Sleuth will not instrument any of your custom Feign components. All the default instrumentation -however will be still there.

13.7 Asynchronous communication

13.7.1 @Async annotated methods

In Spring Cloud Sleuth we’re instrumenting async related components so that the tracing information is passed between threads. -You can disable this behaviour by setting the value of spring.sleuth.async.enabled to false.

If you annotate your method with @Async then we’ll automatically create a new Span with the following characteristics:

  • if the method is annotated with @SpanName then the value of the annotation will be the Span’s name
  • if the method is not annotated with @SpanName the Span name will be the annotated method name
  • the Span will be tagged with that method’s class name and the method name too

13.7.2 @Scheduled annotated methods

In Spring Cloud Sleuth we’re instrumenting scheduled method execution so that the tracing information is passed between threads. You can disable this behaviour -by setting the value of spring.sleuth.scheduled.enabled to false.

If you annotate your method with @Scheduled then we’ll automatically create a new Span with the following characteristics:

  • the Span name will be the annotated method name
  • the Span will be tagged with that method’s class name and the method name too

If you want to skip Span creation for some @Scheduled annotated classes you can set the -spring.sleuth.scheduled.skipPattern with a regular expression that will match the fully qualified name of the -@Scheduled annotated class.

[Tip]Tip

If you are using spring-cloud-sleuth-stream and spring-cloud-netflix-hystrix-stream together, Span will be created for each Hystrix metrics and sent to Zipkin. This may be annoying. You can prevent this by setting spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask

13.7.3 Executor, ExecutorService and ScheduledExecutorService

We’re providing LazyTraceExecutor, TraceableExecutorService and TraceableScheduledExecutorService. Those implementations -are creating Spans each time a new task is submitted, invoked or scheduled.

Here you can see an example of how to pass tracing information with TraceableExecutorService when working with CompletableFuture:

CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
+// use Traverson

15.6.5 Apache HttpClientBuilder and HttpAsyncClientBuilder

We instrument the HttpClientBuilder and HttpAsyncClientBuilder so that +tracing context gets injected to the sent requests.

To block these features, set spring.sleuth.web.client.enabled to false.

15.6.6 Netty HttpClient

We instrument the Netty’s HttpClient.

To block this feature, set spring.sleuth.web.client.enabled to false.

[Important]Important

You have to register HttpClient as a bean so that the instrumentation happens. +If you create a HttpClient instance with a new keyword, the instrumentation does NOT work.

15.6.7 UserInfoRestTemplateCustomizer

We instrument the Spring Security’s UserInfoRestTemplateCustomizer.

To block this feature, set spring.sleuth.web.client.enabled to false.

15.7 Feign

By default, Spring Cloud Sleuth provides integration with Feign through TraceFeignClientAutoConfiguration. +You can disable it entirely by setting spring.sleuth.feign.enabled to false. +If you do so, no Feign-related instrumentation take place.

Part of Feign instrumentation is done through a FeignBeanPostProcessor. +You can disable it by setting spring.sleuth.feign.processor.enabled to false. +If you set it to false, Spring Cloud Sleuth does not instrument any of your custom Feign components. +However, all the default instrumentation is still there.

15.8 Asynchronous Communication

15.8.1 @Async Annotated methods

In Spring Cloud Sleuth, we instrument async-related components so that the tracing information is passed between threads. +You can disable this behavior by setting the value of spring.sleuth.async.enabled to false.

If you annotate your method with @Async, we automatically create a new Span with the following characteristics:

  • If the method is annotated with @SpanName, the value of the annotation is the Span’s name.
  • If the method is not annotated with @SpanName, the Span name is the annotated method name.
  • The span is tagged with the method’s class name and method name.

15.8.2 @Scheduled Annotated Methods

In Spring Cloud Sleuth, we instrument scheduled method execution so that the tracing information is passed between threads. +You can disable this behavior by setting the value of spring.sleuth.scheduled.enabled to false.

If you annotate your method with @Scheduled, we automatically create a new span with the following characteristics:

  • The span name is the annotated method name.
  • The span is tagged with the method’s class name and method name.

If you want to skip span creation for some @Scheduled annotated classes, you can set the spring.sleuth.scheduled.skipPattern with a regular expression that matches the fully qualified name of the @Scheduled annotated class. +If you use spring-cloud-sleuth-stream and spring-cloud-netflix-hystrix-stream together, a span is created for each Hystrix metrics and sent to Zipkin. +This behavior may be annoying. That’s why, by default, spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask.

15.8.3 Executor, ExecutorService, and ScheduledExecutorService

We provide LazyTraceExecutor, TraceableExecutorService, and TraceableScheduledExecutorService. Those implementations create spans each time a new task is submitted, invoked, or scheduled.

The following example shows how to pass tracing information with TraceableExecutorService when working with CompletableFuture:

CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
 	// perform some logic
 	return 1_000_000L;
-}, new TraceableExecutorService(executorService,
+}, new TraceableExecutorService(beanFactory, executorService,
 		// 'calculateTax' explicitly names the span - this param is optional
-		tracer, traceKeys, spanNamer, "calculateTax"));
[Important]Important

Sleuth doesn’t work with parallelStream() out of the box. If you want -to have the tracing information propagated through the stream you have to use the -approach with supplyAsync(...) as presented above.

Customization of Executors

Sometimes you need to set up a custom instance of the AsyncExecutor. In the following snippet you -can see an example of how to set up such a custom Executor.

@Configuration
+		"calculateTax"));
[Important]Important

Sleuth does not work with parallelStream() out of the box. +If you want to have the tracing information propagated through the stream, you have to use the approach with supplyAsync(...), as shown earlier.

Customization of Executors

Sometimes, you need to set up a custom instance of the AsyncExecutor. +The following example shows how to set up such a custom Executor:

@Configuration
 @EnableAutoConfiguration
 @EnableAsync
 static class CustomExecutorConfig extends AsyncConfigurerSupport {
@@ -159,9 +144,13 @@ can see an example of how to set up such a custom Executor
 		executor.initialize();
 		return new LazyTraceExecutor(this.beanFactory, executor);
 	}
-}

13.8 Messaging

Spring Cloud Sleuth integrates with Spring Integration. It creates spans for publish and -subscribe events. To disable Spring Integration instrumentation, set spring.sleuth.integration.enabled to false.

You can provide the spring.sleuth.integration.patterns pattern to explicitly -provide the names of channels that you want to include for tracing. By default all channels -are included.

[Important]Important

When using the Executor to build a Spring Integration IntegrationFlow remember to use the untraced version of the Executor. -Decorating Spring Integration Executor Channel with TraceableExecutorService will cause the spans to be improperly closed.

13.9 Zuul

We’re registering Zuul filters to propagate the tracing information (the request header is enriched with tracing data). -To disable Zuul support set the spring.sleuth.zuul.enabled property to false.

Prev   Next
12. Metrics Home 14. Running examples
\ No newline at end of file +}

15.9 Messaging

Features from this section can be disabled by setting the spring.sleuth.messaging.enabled property with value equal to false.

15.9.1 Spring Integration and Spring Cloud Stream

Spring Cloud Sleuth integrates with Spring Integration. +It creates spans for publish and subscribe events. +To disable Spring Integration instrumentation, set spring.sleuth.integration.enabled to false.

You can provide the spring.sleuth.integration.patterns pattern to explicitly provide the names of channels that you want to include for tracing. +By default, all channels but hystrixStreamOutput channel are included.

[Important]Important

When using the Executor to build a Spring Integration IntegrationFlow, you must use the untraced version of the Executor. +Decorating the Spring Integration Executor Channel with TraceableExecutorService causes the spans to be improperly closed.

15.9.2 Spring RabbitMq

We instrument the RabbitTemplate so that tracing headers get injected +into the message.

To block this feature, set spring.sleuth.messaging.rabbit.enabled to false.

15.9.3 Spring Kafka

We instrument the Spring Kafka’s ProducerFactory and ConsumerFactory +so that tracing headers get injected into the created Spring Kafka’s +Producer and Consumer.

To block this feature, set spring.sleuth.messaging.kafka.enabled to false.

[Note]Note

We do not support context propagation via @KafkaListener annotation. +Check this issue for more information.

15.10 Zuul

We instrument the Zuul Ribbon integration by enriching the Ribbon requests with tracing information. +To disable Zuul support, set the spring.sleuth.zuul.enabled property to false.

Prev   Next
14. Zipkin Stream Span Consumer Home 16. Running examples
\ No newline at end of file diff --git a/2.0.x/multi/multi__introduction.html b/2.0.x/multi/multi__introduction.html index 0e1416cb8..081976882 100644 --- a/2.0.x/multi/multi__introduction.html +++ b/2.0.x/multi/multi__introduction.html @@ -1,52 +1,59 @@ - 1. Introduction
1. Introduction
Prev   Next

1. Introduction

Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud.

1.1 Terminology

Spring Cloud Sleuth borrows Dapper’s terminology.

Span: The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an -RPC. Span’s are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span -is a part of. Spans also have other data, such as descriptions, timestamped events, key-value -annotations (tags), the ID of the span that caused them, and process ID’s (normally IP address).

Spans are started and stopped, and they keep track of their timing information. Once you create a -span, you must stop it at some point in the future.

[Tip]Tip

The initial span that starts a trace is called a root span. The value of span id -of that span is equal to trace id.

Trace: A set of spans forming a tree-like structure. For example, if you are running a distributed -big-data store, a trace might be formed by a put request.

Annotation: is used to record existence of an event in time. Some of the core annotations used to define -the start and stop of a request are:

  • cs - Client Sent - The client has made a request. This annotation depicts the start of the span.
  • sr - Server Received - The server side got the request and will start processing it. -If one subtracts the cs timestamp from this timestamp one will receive the network latency.
  • ss - Server Sent - Annotated upon completion of request processing (when the response -got sent back to the client). If one subtracts the sr timestamp from this timestamp one -will receive the time needed by the server side to process the request.
  • cr - Client Received - Signifies the end of the span. The client has successfully received the -response from the server side. If one subtracts the cs timestamp from this timestamp one -will receive the whole time needed by the client to receive the response from the server.

Visualization of what Span and Trace will look in a system together with the Zipkin annotations:

Trace Info propagation

Each color of a note signifies a span (7 spans - from A to G). If you have such information in the note:

Trace Id = X
+   1. Introduction
1. Introduction
Prev   Next
1. Introduction
Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud.
1.1 Terminology
Spring Cloud Sleuth borrows Dapper’s terminology.
Span: The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an RPC.
+Spans are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span is a part of.
+Spans also have other data, such as descriptions, timestamped events, key-value annotations (tags), the ID of the span that caused them, and process IDs (normally IP addresses).
Spans can be started and stopped, and they keep track of their timing information.
+Once you create a span, you must stop it at some point in the future.
[Tip]Tip
The initial span that starts a trace is called a root span. The value of the ID
+of that span is equal to the trace ID.
Trace: A set of spans forming a tree-like structure.
+For example, if you run a distributed big-data store, a trace might be formed by a PUT request.
Annotation:  Used to record the existence of an event in time. With
+Brave instrumentation, we no longer need to set special events
+for Zipkin to understand who the client and server are, where
+the request started, and where it ended. For learning purposes,
+however, we mark these events to highlight what kind
+of an action took place.
  • cs: Client Sent. The client has made a request. This annotation indicates the start of the span.
  • sr: Server Received: The server side got the request and started processing it.
+Subtracting the cs timestamp from this timestamp reveals the network latency.
  • ss: Server Sent. Annotated upon completion of request processing (when the response got sent back to the client).
+Subtracting the sr timestamp from this timestamp reveals the time needed by the server side to process the request.
  • cr: Client Received. Signifies the end of the span.
+The client has successfully received the response from the server side.
+Subtracting the cs timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server.
The following image shows how Span and Trace look in a system, together with the Zipkin annotations:
Trace Info propagation
Each color of a note signifies a span (there are seven spans - from A to G).
+Consider the following note:
Trace Id = X
 Span Id = D
-Client Sent
That means that the current span has Trace-Id set to X, Span-Id set to D. It also has emitted
- Client Sent event.
This is how the visualization of the parent / child relationship of spans would look like:
Parent child relationship
1.2 Purpose
In the following sections the example from the image above will be taken into consideration.
1.2.1 Distributed tracing with Zipkin
Altogether there are 7 spans . If you go to traces in Zipkin you will see this number in the second trace:
Traces
However if you pick a particular trace then you will see 4 spans:
Traces Info propagation
[Note]Note
When picking a particular trace you will see merged spans. That means that if there were 2 spans sent to
-Zipkin with Server Received and Server Sent / Client Received and Client Sent
-annotations then they will presented as a single span.
Why is there a difference between the 7 and 4 spans in this case?
  • 2 spans come from http:/start span. It has the Server Received (SR) and Server Sent (SS) annotations.
  • 2 spans come from the RPC call from service1 to service2 to the http:/foo endpoint. It has the Client Sent (CS)
-and Client Received (CR) annotations on service1 side. It also has Server Received (SR) and Server Sent (SS) annotations
-on the service2 side. Physically there are 2 spans but they form 1 logical span related to an RPC call.
  • 2 spans come from the RPC call from service2 to service3 to the http:/bar endpoint. It has the Client Sent (CS)
-and Client Received (CR) annotations on service2 side. It also has Server Received (SR) and Server Sent (SS) annotations
-on the service3 side. Physically there are 2 spans but they form 1 logical span related to an RPC call.
  • 2 spans come from the RPC call from service2 to service4 to the http:/baz endpoint. It has the Client Sent (CS)
-and Client Received (CR) annotations on service2 side. It also has Server Received (SR) and Server Sent (SS) annotations
-on the service4 side. Physically there are 2 spans but they form 1 logical span related to an RPC call.
So if we count the physical spans we have 1 from http:/start, 2 from service1 calling service2, 2 form service2
-calling service3 and 2 from service2 calling service4. Altogether 7 spans.
Logically we see the information of Total Spans: 4 because we have 1 span related to the incoming request
-to service1 and 3 spans related to RPC calls.
1.2.2 Visualizing errors
Zipkin allows you to visualize errors in your trace. When an exception was thrown and wasn’t caught then we’re
-setting proper tags on the span which Zipkin can properly colorize. You could see in the list of traces one
-  trace that was in red color. That’s because there was an exception thrown.
If you click that trace then you’ll see a similar picture
Error Traces
Then if you click on one of the spans you’ll see the following
Error Traces Info propagation
As you can see you can easily see the reason for an error and the whole stacktrace related to it.
1.2.3 Live examples
Figure 1.1. Click Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

The dependency graph in Zipkin would look like this:
Dependencies
Figure 1.2. Click Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

1.2.4 Log correlation
When grepping the logs of those four applications by trace id equal to e.g. 2485ec27856c56f4 one would get the following:
service1.log:2016-02-26 11:15:47.561  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Hello from service1. Calling service2
+Client Sent
This note indicates that the current span has Trace Id set to X and Span Id set to D.
+Also, the Client Sent event took place.
The following image shows how parent-child relationships of spans look:
Parent child relationship
1.2 Purpose
The following sections refer to the example shown in the preceding image.
1.2.1 Distributed Tracing with Zipkin
This example has seven spans.
+If you go to traces in Zipkin, you can see this number in the second trace, as shown in the following image:
Traces
However, if you pick a particular trace, you can see four spans, as shown in the following image:
Traces Info propagation
[Note]Note
When you pick a particular trace, you see merged spans.
+That means that, if there were two spans sent to Zipkin with Server Received and Server Sent or Client Received and Client Sent annotations, they are presented as a single span.
Why is there a difference between the seven and four spans in this case?
  • Two spans come from the http:/start span. It has the Server Received (sr) and Server Sent (ss) annotations.
  • Two spans come from the RPC call from service1 to service2 to the http:/foo endpoint.
+The Client Sent (cs) and Client Received (cr) events took place on the service1 side.
+Server Received (sr) and Server Sent (ss) events took place on the service2 side.
+These two spans form one logical span related to an RPC call.
  • Two spans come from the RPC call from service2 to service3 to the http:/bar endpoint.
+The Client Sent (cs) and Client Received (cr) events took place on the service2 side.
+The Server Received (sr) and Server Sent (ss) events took place on the service3 side.
+These two spans form one logical span related to an RPC call.
  • Two spans come from the RPC call from service2 to service4 to the http:/baz endpoint.
+The Client Sent (cs) and Client Received (cr) events took place on the service2 side.
+Server Received (sr) and Server Sent (ss) events took place on the service4 side.
+These two spans form one logical span related to an RPC call.
So, if we count the physical spans, we have one from http:/start, two from service1 calling service2, two from service2
+calling service3, and two from service2 calling service4. In sum, we have a total of seven spans.
Logically, we see the information of four total Spans because we have one span related to the incoming request
+to service1 and three spans related to RPC calls.
1.2.2 Visualizing errors
Zipkin lets you visualize errors in your trace.
+When an exception was thrown and was not caught, we set proper tags on the span, which Zipkin can then properly colorize.
+You could see in the list of traces one trace that is red. That appears because an exception was thrown.
If you click that trace, you see a similar picture, as follows:
Error Traces
If you then click on one of the spans, you see the following
Error Traces Info propagation
The span shows the reason for the error and the whole stack trace related to it.
1.2.3 Distributed Tracing with Brave
Starting with version 2.0.0, Spring Cloud Sleuth uses Brave as the tracing library.
+Consequently, Sleuth no longer takes care of storing the context but delegates that work to Brave.
Due to the fact that Sleuth had different naming and tagging conventions than Brave, we decided to follow Brave’s conventions from now on.
+However, if you want to use the legacy Sleuth approaches, you can set the spring.sleuth.http.legacy.enabled property to true.
1.2.4 Live examples
Figure 1.1. Click the Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

Click here to see it live!
The dependency graph in Zipkin should resemble the following image:
Dependencies
Figure 1.2. Click the Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

Click here to see it live!
1.2.5 Log correlation
When using grep to read the logs of those four applications by scanning for a trace ID equal to (for example) 2485ec27856c56f4, you get output resembling the following:
service1.log:2016-02-26 11:15:47.561  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Hello from service1. Calling service2
 service2.log:2016-02-26 11:15:47.710  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Hello from service2. Calling service3 and then service4
 service3.log:2016-02-26 11:15:47.895  INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application   : Hello from service3
 service2.log:2016-02-26 11:15:47.924  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service3 [Hello from service3]
 service4.log:2016-02-26 11:15:48.134  INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application   : Hello from service4
 service2.log:2016-02-26 11:15:48.156  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service4 [Hello from service4]
-service1.log:2016-02-26 11:15:48.182  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]
If you’re using a log aggregating tool like Kibana,
-Splunk etc. you can order the events that took place. An example of
-Kibana would look like this:
Log correlation with Kibana
If you want to use Logstash here is the Grok pattern for Logstash:
filter {
+service1.log:2016-02-26 11:15:48.182  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]
If you use a log aggregating tool (such as Kibana, Splunk, and others), you can order the events that took place.
+An example from Kibana would resemble the following image:
Log correlation with Kibana
If you want to use Logstash, the following listing shows the Grok pattern for Logstash:
filter {
        # pattern matching logback pattern
        grok {
               match => { "message" => "%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
        }
-}
[Note]Note
If you want to use Grok together with the logs from Cloud Foundry you have to use this pattern:
filter {
+}
[Note]Note
If you want to use Grok together with the logs from Cloud Foundry, you have to use the following pattern:
filter {
        # pattern matching logback pattern
        grok {
               match => { "message" => "(?m)OUT\s+%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
        }
-}
JSON Logback with Logstash
Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability
-we’re passing the dependencies in the groupId:artifactId:version notation.
Dependencies setup
  • Ensure that Logback is on the classpath (ch.qos.logback:logback-core)
  • Add Logstash Logback encode - example for version 4.6 : net.logstash.logback:logstash-logback-encoder:4.6
Logback setup
Below you can find an example of a Logback configuration (file named logback-spring.xml) that:
  • logs information from the application in a JSON format to a build/${spring.application.name}.json file
  • has commented out two additional appenders - console and standard log file
  • has the same logging pattern as the one presented in the previous section
<?xml version="1.0" encoding="UTF-8"?>
+}
JSON Logback with Logstash
Often, you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick.
+To do so, you have to do the following (for readability, we pass the dependencies in the groupId:artifactId:version notation).
Dependencies Setup
  1. Ensure that Logback is on the classpath (ch.qos.logback:logback-core).
  2. Add Logstash Logback encode. For example, to use version 4.6, add net.logstash.logback:logstash-logback-encoder:4.6.
Logback Setup
Consider the following example of a Logback configuration file (named logback-spring.xml).
<?xml version="1.0" encoding="UTF-8"?>
 <configuration>
 	<include resource="org/springframework/boot/logging/logback/defaults.xml"/>
 	​
@@ -121,44 +128,51 @@ we’re passing the dependencies in the groupId:artifa
 		<!--<appender-ref ref="logstash"/>-->
 		<!--<appender-ref ref="flatfile"/>-->
 	</root>
-</configuration>
[Note]Note
If you’re using a custom logback-spring.xml then you have to pass the spring.application.name in
-bootstrap instead of application property file. Otherwise your custom logback file won’t read the property properly.
1.2.5 Propagating Span Context
The span context is the state that must get propagated to any child Spans across process boundaries.
+</configuration>

That Logback configuration file:

  • Logs information from the application in a JSON format to a build/${spring.application.name}.json file.
  • Has commented out two additional appenders: console and standard log file.
  • Has the same logging pattern as the one presented in the previous section.
[Note]Note

If you use a custom logback-spring.xml, you must pass the spring.application.name in the bootstrap rather than the application property file. +Otherwise, your custom logback file does not properly read the property.

1.2.6 Propagating Span Context

The span context is the state that must get propagated to any child spans across process boundaries. Part of the Span Context is the Baggage. The trace and span IDs are a required part of the span context. -Baggage is an optional part.

Baggage is a set of key:value pairs stored in the span context. Baggage travels together with the trace -and is attached to every span. Spring Cloud Sleuth will understand that a header is baggage related if the HTTP - header is prefixed with baggage- and for messaging it starts with baggage_.

[Important]Important

There’s currently no limitation of the count or size of baggage items. However, keep in mind that -too many can decrease system throughput or increase RPC latency. In extreme cases, it could crash the app due -to exceeding transport-level message or header capacity.

Example of setting baggage on a span:

Span initialSpan = this.tracer.createSpan("span");
-initialSpan.setBaggageItem("foo", "bar");
-initialSpan.setBaggageItem("UPPER_CASE", "someValue");

Baggage vs. Span Tags

Baggage travels with the trace (i.e. every child span contains the baggage of its parent). Zipkin has no knowledge of -baggage and will not even receive that information.

Tags are attached to a specific span - they are presented for that particular span only. However you -can search by tag to find the trace, where there exists a span having the searched tag value.

If you want to be able to lookup a span based on baggage, you should add corresponding entry as a tag in the root span.

@Autowired Tracer tracer;
-
-Span span = tracer.getCurrentSpan();
-String baggageKey = "key";
-String baggageValue = "foo";
-span.setBaggageItem(baggageKey, baggageValue);
-tracer.addTag(baggageKey, baggageValue);

1.3 Adding to the project

[Important]Important

To ensure that your application name is properly displayed in Zipkin - set the spring.application.name property in bootstrap.yml.

1.3.1 Only Sleuth (log correlation)

If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add -the spring-cloud-starter-sleuth module to your project.

Maven.  +Baggage is an optional part.

Baggage is a set of key:value pairs stored in the span context. +Baggage travels together with the trace and is attached to every span. +Spring Cloud Sleuth understands that a header is baggage-related if the HTTP header is prefixed with baggage- and, for messaging, it starts with baggage_.

[Important]Important

There is currently no limitation of the count or size of baggage items. +However, keep in mind that too many can decrease system throughput or increase RPC latency. +In extreme cases, too much baggage can crash the application, due to exceeding transport-level message or header capacity.

The following example shows setting baggage on a span:

Span initialSpan = this.tracer.nextSpan().name("span").start();
+try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(initialSpan)) {
+	ExtraFieldPropagation.set("foo", "bar");
+	ExtraFieldPropagation.set("UPPER_CASE", "someValue");
+}

Baggage versus Span Tags

Baggage travels with the trace (every child span contains the baggage of its parent). +Zipkin has no knowledge of baggage and does not receive that information.

[Important]Important

Starting from Sleuth 2.0.0 you have to pass the baggage key names explicitly +in your project configuration. Read more about that setup here

Tags are attached to a specific span. In other words, they are presented only for that particular span. +However, you can search by tag to find the trace, assuming a span having the searched tag value exists.

If you want to be able to lookup a span based on baggage, you should add a corresponding entry as a tag in the root span.

[Important]Important

The span must be in scope.

The following listing shows integration tests that use baggage:

The setup.  +

spring.sleuth:
+  baggage-keys:
+    - baz
+    - bizarrecase
+  propagation-keys:
+    - foo
+    - upper_case

+

The code.  +

initialSpan.tag("foo",
+		ExtraFieldPropagation.get(initialSpan.context(), "foo"));
+initialSpan.tag("UPPER_CASE",
+		ExtraFieldPropagation.get(initialSpan.context(), "UPPER_CASE"));

+

1.3 Adding Sleuth to the Project

This section addresses how to add Sleuth to your project with either Maven or Gradle.

[Important]Important

To ensure that your application name is properly displayed in Zipkin, set the spring.application.name property in bootstrap.yml.

1.3.1 Only Sleuth (log correlation)

If you want to use only Spring Cloud Sleuth without the Zipkin integration, add the spring-cloud-starter-sleuth module to your project.

The following example shows how to add Sleuth with Maven:

Maven.  

<dependencyManagement> 1
-         <dependencies>
-             <dependency>
-                 <groupId>org.springframework.cloud</groupId>
-                 <artifactId>spring-cloud-dependencies</artifactId>
-                 <version>${release.train.version}</version>
-                 <type>pom</type>
-                 <scope>import</scope>
-             </dependency>
-         </dependencies>
-   </dependencyManagement>
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>${release.train.version}</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
 
-   <dependency> 2
-       <groupId>org.springframework.cloud</groupId>
-       <artifactId>spring-cloud-starter-sleuth</artifactId>
-   </dependency>

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-sleuth

Gradle.  +<dependency> 2 + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-sleuth</artifactId> +</dependency>

+

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-sleuth.

The following example shows how to add Sleuth with Gradle:

Gradle.  

dependencyManagement { 1
     imports {
         mavenBom "org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"
@@ -168,26 +182,24 @@ the Spring BOM
2
     compile "org.springframework.cloud:spring-cloud-starter-sleuth"
 }

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-sleuth

1.3.2 Sleuth with Zipkin via HTTP

If you want both Sleuth and Zipkin just add the spring-cloud-starter-zipkin dependency.

Maven.  +

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-sleuth.

1.3.2 Sleuth with Zipkin via HTTP

If you want both Sleuth and Zipkin, add the spring-cloud-starter-zipkin dependency.

The following example shows how to do so for Maven:

Maven.  

<dependencyManagement> 1
-         <dependencies>
-             <dependency>
-                 <groupId>org.springframework.cloud</groupId>
-                 <artifactId>spring-cloud-dependencies</artifactId>
-                 <version>${release.train.version}</version>
-                 <type>pom</type>
-                 <scope>import</scope>
-             </dependency>
-         </dependencies>
-   </dependencyManagement>
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>${release.train.version}</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
 
-   <dependency> 2
-       <groupId>org.springframework.cloud</groupId>
-       <artifactId>spring-cloud-starter-zipkin</artifactId>
-   </dependency>

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin

Gradle.  +<dependency> 2 + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-zipkin</artifactId> +</dependency>

+

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-zipkin.

The following example shows how to do so for Gradle:

Gradle.  

dependencyManagement { 1
     imports {
         mavenBom "org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"
@@ -197,32 +209,30 @@ the Spring BOM
2
     compile "org.springframework.cloud:spring-cloud-starter-zipkin"
 }

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin

1.3.3 Sleuth with Zipkin via RabbitMQ or Kafka

If you want to use RabbitMQ or Kafka instead of http, add the spring-rabbit or spring-kafka -dependencies. The default destination name is zipkin.

Note: spring-cloud-sleuth-stream is deprecated and incompatible with these destinations

If you want Sleuth over RabbitMQ add the spring-cloud-starter-zipkin and spring-rabbit -dependencies.

Maven.  +

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-zipkin.

1.3.3 Sleuth with Zipkin over RabbitMQ or Kafka

If you want to use RabbitMQ or Kafka instead of HTTP, add the spring-rabbit or spring-kafka dependency. +The default destination name is zipkin.

If using Kafka, you must set the property spring.zipkin.sender.type property accordingly:

spring.zipkin.sender.type: kafka
[Caution]Caution

spring-cloud-sleuth-stream is deprecated and incompatible with these destinations.

If you want Sleuth over RabbitMQ, add the spring-cloud-starter-zipkin and spring-rabbit +dependencies.

The following example shows how to do so for Gradle:

Maven.  

<dependencyManagement> 1
-         <dependencies>
-             <dependency>
-                 <groupId>org.springframework.cloud</groupId>
-                 <artifactId>spring-cloud-dependencies</artifactId>
-                 <version>${release.train.version}</version>
-                 <type>pom</type>
-                 <scope>import</scope>
-             </dependency>
-         </dependencies>
-   </dependencyManagement>
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>${release.train.version}</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
 
-   <dependency> 2
-       <groupId>org.springframework.cloud</groupId>
-       <artifactId>spring-cloud-starter-zipkin</artifactId>
-   </dependency>
-   <dependency> 3
-       <groupId>org.springframework.amqp</groupId>
-       <artifactId>spring-rabbit</artifactId>
-   </dependency>

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin - that way all dependent dependencies will be downloaded

3

To automatically configure rabbit, simply add the spring-rabbit dependency

Gradle.  +<dependency> 2 + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-zipkin</artifactId> +</dependency> +<dependency> 3 + <groupId>org.springframework.amqp</groupId> + <artifactId>spring-rabbit</artifactId> +</dependency>

+

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-zipkin. That way, all nested dependencies get downloaded.

3

To automatically configure RabbitMQ, add the spring-rabbit dependency.

Gradle.  

dependencyManagement { 1
     imports {
         mavenBom "org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"
@@ -233,5 +243,4 @@ dependencies {
     compile "org.springframework.cloud:spring-cloud-starter-zipkin" 2
     compile "org.springframework.amqp:spring-rabbit" 3
 }

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin - that way all dependent dependencies will be downloaded

3

To automatically configure rabbit, simply add the spring-rabbit dependency

Prev   Next
 Home 2. Additional resources
\ No newline at end of file +

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-zipkin. That way, all nested dependencies get downloaded.

3

To automatically configure RabbitMQ, add the spring-rabbit dependency.

Prev   Next
 Home 2. Additional Resources
\ No newline at end of file diff --git a/2.0.x/multi/multi__managing_spans_with_annotations.html b/2.0.x/multi/multi__managing_spans_with_annotations.html index 4820f37f8..2b8601f0a 100644 --- a/2.0.x/multi/multi__managing_spans_with_annotations.html +++ b/2.0.x/multi/multi__managing_spans_with_annotations.html @@ -1,47 +1,43 @@ - 8. Managing spans with annotations
8. Managing spans with annotations
Prev   Next

8. Managing spans with annotations

8.1 Rationale

The main arguments for this features are

  • api-agnostic means to collaborate with a span

    • use of annotations allows users to add to a span with no library dependency on a span api. -This allows Sleuth to change its core api less impact to user code.

  • reduced surface area for basic span operations.

    • without this feature one has to use the span api, which has lifecycle commands that -could be used incorrectly. By only exposing scope, tag and log functionality, users can -collaborate without accidentally breaking span lifecycle.

  • collaboration with runtime generated code

    • with libraries such as Spring Data / Feign the implementations of interfaces are generated -at runtime thus span wrapping of objects was tedious. Now you can provide annotations - over interfaces and arguments of those interfaces

8.2 Creating new spans

If you really don’t want to take care of creating local spans manually you can profit from the -@NewSpan annotation. Also we give you the @SpanTag annotation to add tags in an automated -fashion.

Let’s look at some examples of usage.

@NewSpan
-void testMethod();

Annotating the method without any parameter will lead to a creation of a new span whose name -will be equal to annotated method name.

@NewSpan("customNameOnTestMethod4")
-void testMethod4();

If you provide the value in the annotation (either directly or via the name parameter) then -the created span will have the name as the provided value.

// method declaration
+   11. Managing Spans with Annotations
11. Managing Spans with Annotations
Prev   Next
11. Managing Spans with Annotations
You can manage spans with a variety of annotations.
11.1 Rationale
There are a number of good reasons to manage spans with annotations, including:
  • API-agnostic means to collaborate with a span. Use of annotations lets users add to a span with no library dependency on a span api.
+Doing so lets Sleuth change its core API to create less impact to user code.
  • Reduced surface area for basic span operations. Without this feature, you must use the span api, which has lifecycle commands that could be used incorrectly.
+By only exposing scope, tag, and log functionality, you can collaborate without accidentally breaking span lifecycle.
  • Collaboration with runtime generated code. With libraries such as Spring Data and Feign, the implementations of interfaces are generated at runtime.
+Consequently, span wrapping of objects was tedious.
+Now you can provide annotations over interfaces and the arguments of those interfaces.
11.2 Creating New Spans
If you do not want to create local spans manually, you can use the @NewSpan annotation.
+Also, we provide the @SpanTag annotation to add tags in an automated fashion.
Now we can consider some examples of usage.
@NewSpan
+void testMethod();
Annotating the method without any parameter leads to creating a new span whose name equals the annotated method name.
@NewSpan("customNameOnTestMethod4")
+void testMethod4();
If you provide the value in the annotation (either directly or by setting the name parameter), the created span has the provided value as the name.
// method declaration
 @NewSpan(name = "customNameOnTestMethod5")
 void testMethod5(@SpanTag("testTag") String param);
 
 // and method execution
-this.testBean.testMethod5("test");
You can combine both the name and a tag. Let’s focus on the latter. In this case whatever the value of
-the annotated method’s parameter runtime value will be - that will be the value of the tag. In our sample
-the tag key will be testTag and the tag value will be test.
@NewSpan(name = "customNameOnTestMethod3")
+this.testBean.testMethod5("test");
You can combine both the name and a tag. Let’s focus on the latter.
+In this case, the value of the annotated method’s parameter runtime value becomes the value of the tag.
+In our sample, the tag key is testTag, and the tag value is test.
@NewSpan(name = "customNameOnTestMethod3")
 @Override
 public void testMethod3() {
-}
You can place the @NewSpan annotation on both the class and an interface. If you override the
-interface’s method and provide a different value of the @NewSpan annotation then the most
-concrete one wins (in this case customNameOnTestMethod3 will be set).
8.3 Continuing spans
If you want to just add tags and annotations to an existing span it’s enough
-to use the @ContinueSpan annotation as presented below. Note that in contrast
-with the @NewSpan annotation you can also add logs via the log parameter:
// method declaration
+}
You can place the @NewSpan annotation on both the class and an interface.
+If you override the interface’s method and provide a different value for the @NewSpan annotation, the most
+concrete one wins (in this case customNameOnTestMethod3 is set).
11.3 Continuing Spans
If you want to add tags and annotations to an existing span, you can use the @ContinueSpan annotation, as shown in the following example:
// method declaration
 @ContinueSpan(log = "testMethod11")
 void testMethod11(@SpanTag("testTag11") String param);
 
 // method execution
-this.testBean.testMethod11("test");
That way the span will get continued and:
  • logs with name testMethod11.before and testMethod11.after will be created
  • if an exception will be thrown a log testMethod11.afterFailure will also be created
  • tag with key testTag11 and value test will be created
8.4 More advanced tag setting
There are 3 different ways to add tags to a span. All of them are controlled by the SpanTag annotation.
-Precedence is:
  • try with the bean of TagValueResolver type and provided name
  • if one hasn’t provided the bean name, try to evaluate an expression. We’re searching for a TagValueExpressionResolver bean.
-The default implementation uses SPEL expression resolution.
  • if one hasn’t provided any expression to evaluate just return a toString() value of the parameter
8.4.1 Custom extractor
The value of the tag for following method will be computed by an implementation of TagValueResolver interface.
-Its class name has to be passed as the value of the resolver attribute.
Having such an annotated method:
@NewSpan
+this.testBean.testMethod11("test");
+this.testBean.testMethod13();
(Note that, in contrast with the @NewSpan annotation ,you can also add logs with the log parameter.)
That way, the span gets continued and:
  • Log entries named testMethod11.before and testMethod11.after are created.
  • If an exception is thrown, a log entry named testMethod11.afterFailure is also created.
  • A tag with a key of testTag11 and a value of test is created.
11.4 Advanced Tag Setting
There are 3 different ways to add tags to a span. All of them are controlled by the SpanTag annotation.
+The precedence is as follows:
  1. Try with a bean of TagValueResolver type and a provided name.
  2. If the bean name has not been provided, try to evaluate an expression.
+We search for a TagValueExpressionResolver bean.
+The default implementation uses SPEL expression resolution.
+IMPORTANT You can only reference properties from the SPEL expression. Method execution is not allowed due to security constraints.
  3. If we do not find any expression to evaluate, return the toString() value of the parameter.
11.4.1 Custom extractor
The value of the tag for the following method is computed by an implementation of TagValueResolver interface.
+Its class name has to be passed as the value of the resolver attribute.
Consider the following annotated method:
@NewSpan
 public void getAnnotationForTagValueResolver(@SpanTag(key = "test", resolver = TagValueResolver.class) String test) {
-}
and such a TagValueResolver bean implementation
@Bean(name = "myCustomTagValueResolver")
+}
Now further consider the following TagValueResolver bean implementation:
@Bean(name = "myCustomTagValueResolver")
 public TagValueResolver tagValueResolver() {
 	return parameter -> "Value from myCustomTagValueResolver";
-}
Will lead to setting of a tag value equal to Value from myCustomTagValueResolver.
8.4.2 Resolving expressions for value
Having such an annotated method:
@NewSpan
-public void getAnnotationForTagValueExpression(@SpanTag(key = "test", expression = "length() + ' characters'") String test) {
-}
and no custom implementation of a TagValueExpressionResolver will lead to evaluation of the SPEL expression and a tag with value 4 characters will be set on the span.
-If you want to use some other expression resolution mechanism you can create your own implementation
-of the bean.
8.4.3 Using toString method
Having such an annotated method:
@NewSpan
+}
The two preceding examples lead to setting a tag value equal to Value from myCustomTagValueResolver.
11.4.2 Resolving Expressions for a Value
Consider the following annotated method:
@NewSpan
+public void getAnnotationForTagValueExpression(@SpanTag(key = "test", expression = "'hello' + ' characters'") String test) {
+}
No custom implementation of a TagValueExpressionResolver leads to evaluation of the SPEL expression, and a tag with a value of 4 characters is set on the span.
+If you want to use some other expression resolution mechanism, you can create your own implementation of the bean.
11.4.3 Using the toString() method
Consider the following annotated method:
@NewSpan
 public void getAnnotationForArgumentToString(@SpanTag("test") Long param) {
-}
if executed with a value of 15 will lead to setting of a tag with a String value of "15".
Prev   Next
7. Naming spans Home 9. Customizations

\ No newline at end of file
+}

Running the preceding method with a value of 15 leads to setting a tag with a String value of "15".

Prev   Next
10. Naming spans Home 12. Customizations
\ No newline at end of file diff --git a/2.0.x/multi/multi__naming_spans.html b/2.0.x/multi/multi__naming_spans.html index 3ce9a30d9..abfa42cf2 100644 --- a/2.0.x/multi/multi__naming_spans.html +++ b/2.0.x/multi/multi__naming_spans.html @@ -1,19 +1,20 @@ - 7. Naming spans
7. Naming spans
Prev   Next

7. Naming spans

Picking a span name is not a trivial task. Span name should depict an operation name. The name should -be low cardinality (e.g. not include identifiers).

Since there is a lot of instrumentation going on some of the span names will be -artificial like:

  • controller-method-name when received by a Controller with a method name conrollerMethodName
  • async for asynchronous operations done via wrapped Callable and Runnable.
  • @Scheduled annotated methods will return the simple name of the class.

Fortunately, for the asynchronous processing you can provide explicit naming.

7.1 @SpanName annotation

You can name the span explicitly via the @SpanName annotation.

@SpanName("calculateTax")
+   10. Naming spans
10. Naming spans
Prev   Next
10. Naming spans
Picking a span name is not a trivial task. A span name should depict an operation name.
+The name should be low cardinality, so it should not include identifiers.
Since there is a lot of instrumentation going on, some span names are artificial:
  • controller-method-name when received by a Controller with a method name of controllerMethodName
  • async for asynchronous operations done with wrapped Callable and Runnable interfaces.
  • Methods annotated with @Scheduled return the simple name of the class.
Fortunately, for asynchronous processing, you can provide explicit naming.
10.1 @SpanName Annotation
You can name the span explicitly by using the @SpanName annotation, as shown in the following example:
@SpanName("calculateTax")
 class TaxCountingRunnable implements Runnable {
 
 	@Override public void run() {
 		// perform logic
 	}
-}
In this case, when processed in the following manner:
Runnable runnable = new TraceRunnable(tracer, spanNamer, new TaxCountingRunnable());
+}
In this case, when processed in the following manner, the span is named calculateTax:
Runnable runnable = new TraceRunnable(tracing, spanNamer,
+		new TaxCountingRunnable());
 Future<?> future = executorService.submit(runnable);
 // ... some additional logic ...
-future.get();
The span will be named calculateTax.
7.2 toString() method
It’s pretty rare to create separate classes for Runnable or Callable. Typically one creates an anonymous
-instance of those classes. You can’t annotate such classes thus to override that, if there is no @SpanName annotation present,
-we’re checking if the class has a custom implementation of the toString() method.
So executing such code:
Runnable runnable = new TraceRunnable(tracer, spanNamer, new Runnable() {
+future.get();
10.2 toString() method
It is pretty rare to create separate classes for Runnable or Callable.
+Typically, one creates an anonymous instance of those classes.
+You cannot annotate such classes.
+To overcome that limitation, if there is no @SpanName annotation present, we check whether the class has a custom implementation of the toString() method.
Running such code leads to creating a span named calculateTax, as shown in the following example:
Runnable runnable = new TraceRunnable(tracing, spanNamer, new Runnable() {
 	@Override public void run() {
 		// perform logic
 	}
@@ -24,4 +25,4 @@ we’re checking if the class has a custom implementation of the // ... some additional logic ...
-future.get();
will lead in creating a span named calculateTax.
Prev   Next
6. Span lifecycle Home 8. Managing spans with annotations

\ No newline at end of file
+future.get();
Prev   Next
9. Span lifecycle Home 11. Managing Spans with Annotations
\ No newline at end of file diff --git a/2.0.x/multi/multi__propagation.html b/2.0.x/multi/multi__propagation.html new file mode 100644 index 000000000..e00d22cfc --- /dev/null +++ b/2.0.x/multi/multi__propagation.html @@ -0,0 +1,92 @@ + + + 5. Propagation
5. Propagation
Prev   Next

5. Propagation

Propagation is needed to ensure activities originating from the same root are collected together in the same trace. +The most common propagation approach is to copy a trace context from a client by sending an RPC request to a server receiving it.

For example, when a downstream HTTP call is made, its trace context is encoded as request headers and sent along with it, as shown in the following image:

   Client Span                                                Server Span
+┌──────────────────┐                                       ┌──────────────────┐
+│                  │                                       │                  │
+│   TraceContext   │           Http Request Headers        │   TraceContext   │
+│ ┌──────────────┐ │          ┌───────────────────┐        │ ┌──────────────┐ │
+│ │ TraceId      │ │          │ X─B3─TraceId      │        │ │ TraceId      │ │
+│ │              │ │          │                   │        │ │              │ │
+│ │ ParentSpanId │ │ Extract  │ X─B3─ParentSpanId │ Inject │ │ ParentSpanId │ │
+│ │              ├─┼─────────>│                   ├────────┼>│              │ │
+│ │ SpanId       │ │          │ X─B3─SpanId       │        │ │ SpanId       │ │
+│ │              │ │          │                   │        │ │              │ │
+│ │ Sampled      │ │          │ X─B3─Sampled      │        │ │ Sampled      │ │
+│ └──────────────┘ │          └───────────────────┘        │ └──────────────┘ │
+│                  │                                       │                  │
+└──────────────────┘                                       └──────────────────┘

The names above are from B3 Propagation, which is built-in to Brave and has implementations in many languages and frameworks.

Most users use a framework interceptor to automate propagation. +The next two examples show how that might work for a client and a server.

The following example shows how client-side propagation might work:

@Autowired Tracing tracing;
+
+// configure a function that injects a trace context into a request
+injector = tracing.propagation().injector(Request.Builder::addHeader);
+
+// before a request is sent, add the current span's context to it
+injector.inject(span.context(), request);

The following example shows how server-side propagation might work:

@Autowired Tracing tracing;
+@Autowired Tracer tracer;
+
+// configure a function that extracts the trace context from a request
+extractor = tracing.propagation().extractor(Request::getHeader);
+
+// when a server receives a request, it joins or starts a new trace
+span = tracer.nextSpan(extractor.extract(request));

5.1 Propagating extra fields

Sometimes you need to propagate extra fields, such as a request ID or an alternate trace context. +For example, if you are in a Cloud Foundry environment, you might want to pass the request ID, as shown in the following example:

// when you initialize the builder, define the extra field you want to propagate
+Tracing.newBuilder().propagationFactory(
+  ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-vcap-request-id")
+);
+
+// later, you can tag that request ID or use it in log correlation
+requestId = ExtraFieldPropagation.get("x-vcap-request-id");

You may also need to propagate a trace context that you are not using. +For example, you may be in an Amazon Web Services environment but not be reporting data to X-Ray. +To ensure X-Ray can co-exist correctly, pass-through its tracing header, as shown in the following example:

tracingBuilder.propagationFactory(
+  ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-amzn-trace-id")
+);
[Tip]Tip

In Spring Cloud Sleuth all elements of the tracing builder Tracing.newBuilder() +are defined as beans. So if you want to pass a custom PropagationFactory, it’s enough +for you to create a bean of that type and we will set it in the Tracing bean.

5.1.1 Prefixed fields

If they follow a common pattern, you can also prefix fields. +The following example shows how to propagate x-vcap-request-id the field as-is but send the country-code and user-id fields on the wire as x-baggage-country-code and x-baggage-user-id, respectively:

Tracing.newBuilder().propagationFactory(
+  ExtraFieldPropagation.newFactoryBuilder(B3Propagation.FACTORY)
+                       .addField("x-vcap-request-id")
+                       .addPrefixedFields("baggage-", Arrays.asList("country-code", "user-id"))
+                       .build()
+);

Later, you can call the following code to affect the country code of the current trace context:

ExtraFieldPropagation.set("country-code", "FO");
+String countryCode = ExtraFieldPropagation.get("country-code");

Alternatively, if you have a reference to a trace context, you can use it explicitly, as shown in the following example:

ExtraFieldPropagation.set(span.context(), "country-code", "FO");
+String countryCode = ExtraFieldPropagation.get(span.context(), "country-code");
[Important]Important

A difference from previous versions of Sleuth is that, with Brave, you must pass the list of baggage keys. +There are two properties to achieve this. +With the spring.sleuth.baggage-keys, you set keys that get prefixed with baggage- for HTTP calls and baggage_ for messaging. +You can also use the spring.sleuth.propagation-keys property to pass a list of prefixed keys that are whitelisted without any prefix.

5.1.2 Extracting a Propagated Context

The TraceContext.Extractor<C> reads trace identifiers and sampling status from an incoming request or message. +The carrier is usually a request object or headers.

This utility is used in standard instrumentation (such as HttpServerHandler`) but can also be used for custom RPC or messaging code.

TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are +sharing span IDs between a client and a server.

5.1.3 Sharing span IDs between Client and Server

A normal instrumentation pattern is to create a span representing the server side of an RPC. +Extractor.extract might return a complete trace context when applied to an incoming client request. +Tracer.joinSpan attempts to continue this trace, using the same span ID if supported or creating a child span +if not. When the span ID is shared, the reported data includes a flag saying so.

The following image shows an example of B3 propagation:

                              ┌───────────────────┐      ┌───────────────────┐
+ Incoming Headers             │   TraceContext    │      │   TraceContext    │
+┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │
+│ X─B3-TraceId      │─────────┼─┼> TraceId      │ │──────┼─┼> TraceId      │ │
+│                   │         │ │               │ │      │ │               │ │
+│ X─B3-ParentSpanId │─────────┼─┼> ParentSpanId │ │──────┼─┼> ParentSpanId │ │
+│                   │         │ │               │ │      │ │               │ │
+│ X─B3-SpanId       │─────────┼─┼> SpanId       │ │──────┼─┼> SpanId       │ │
+└───────────────────┘         │ │               │ │      │ │               │ │
+                              │ │               │ │      │ │  Shared: true │ │
+                              │ └───────────────┘ │      │ └───────────────┘ │
+                              └───────────────────┘      └───────────────────┘

Some propagation systems forward only the parent span ID, detected when Propagation.Factory.supportsJoin() == false. +In this case, a new span ID is always provisioned, and the incoming context determines the parent ID.

The following image shows an example of AWS propagation:

                              ┌───────────────────┐      ┌───────────────────┐
+ x-amzn-trace-id              │   TraceContext    │      │   TraceContext    │
+┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │
+│ Root              │─────────┼─┼> TraceId      │ │──────┼─┼> TraceId      │ │
+│                   │         │ │               │ │      │ │               │ │
+│ Parent            │─────────┼─┼> SpanId       │ │──────┼─┼> ParentSpanId │ │
+└───────────────────┘         │ └───────────────┘ │      │ │               │ │
+                              └───────────────────┘      │ │  SpanId: New  │ │
+                                                         │ └───────────────┘ │
+                                                         └───────────────────┘

Note: Some span reporters do not support sharing span IDs. +For example, if you set Tracing.Builder.spanReporter(amazonXrayOrGoogleStackdrive), you should disable join by setting Tracing.Builder.supportsJoin(false). +Doing so forces a new child span on Tracer.joinSpan().

5.1.4 Implementing Propagation

TraceContext.Extractor<C> is implemented by a Propagation.Factory plugin. +Internally, this code creates the union type, TraceContextOrSamplingFlags, with one of the following: +* TraceContext if trace and span IDs were present. +* TraceIdContext if a trace ID was present but span IDs were not present. +* SamplingFlags if no identifiers were present.

Some Propagation implementations carry extra data from the point of extraction (for example, reading incoming headers) to injection (for example, writing outgoing headers). +For example, it might carry a request ID. +When implementations have extra data, they handle it as follows: +* If a TraceContext were extracted, add the extra data as TraceContext.extra(). +* Otherwise, add it as TraceContextOrSamplingFlags.extra(), which Tracer.nextSpan handles.

Prev   Next
4. Sampling Home 6. Current Tracing Component
\ No newline at end of file diff --git a/2.0.x/multi/multi__running_examples.html b/2.0.x/multi/multi__running_examples.html index ca327869e..6da03204d 100644 --- a/2.0.x/multi/multi__running_examples.html +++ b/2.0.x/multi/multi__running_examples.html @@ -1,3 +1,7 @@ - 14. Running examples
14. Running examples
Prev   

14. Running examples

You can find the running examples deployed in the Pivotal Web Services. Check them out in the following links:

Prev   
13. Integrations Home 
\ No newline at end of file + 16. Running examples
16. Running examples
Prev   

16. Running examples

You can see the running examples deployed in the Pivotal Web Services. +Check them out at the following links:

Prev   
15. Integrations Home 
\ No newline at end of file diff --git a/2.0.x/multi/multi__sampling.html b/2.0.x/multi/multi__sampling.html index 3d4a50e92..115979dc0 100644 --- a/2.0.x/multi/multi__sampling.html +++ b/2.0.x/multi/multi__sampling.html @@ -1,26 +1,40 @@ - 4. Sampling
4. Sampling
Prev   Next

4. Sampling

In distributed tracing the data volumes can be very high so sampling -can be important (you usually don’t need to export all spans to get a -good picture of what is happening). Spring Cloud Sleuth has a -Sampler strategy that you can implement to take control of the -sampling algorithm. Samplers do not stop span (correlation) ids from -being generated, but they do prevent the tags and events being -attached and exported. By default you get a strategy that continues to -trace if a span is already active, but new ones are always marked as -non-exportable. If all your apps run with this sampler you will see -traces in logs, but not in any remote store. For testing the default -is often enough, and it probably is all you need if you are only using -the logs (e.g. with an ELK aggregator). If you are exporting span data -to Zipkin or Spring Cloud Stream, there is also an AlwaysSampler -that exports everything and a PercentageBasedSampler that samples a -fixed fraction of spans.

[Note]Note

the PercentageBasedSampler is the default if you are using -spring-cloud-sleuth-zipkin or spring-cloud-sleuth-stream. You can -configure the exports using spring.sleuth.sampler.percentage. The passed -value needs to be a double from 0.0 to 1.0 so it’s not a percentage. -For backwards compatibility reasons we’re not changing the property name.

A sampler can be installed just by creating a bean definition, e.g:

@Bean
+   4. Sampling
4. Sampling
Prev   Next
4. Sampling
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).
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.
By default, a global sampler applies a single rate to all traced operations.
+Tracer.Builder.sampler controls this setting, and it defaults to tracing every request.
4.1 Declarative sampling
Some applications need to sample based on the type or annotations of a java method.
Most users use a framework interceptor to automate this sort of policy.
+The following example shows how that might work internally:
@Autowired Tracing tracing;
+
+// derives a sample rate from an annotation on a java method
+DeclarativeSampler<Traced> sampler = DeclarativeSampler.create(Traced::sampleRate);
+
+@Around("@annotation(traced)")
+public Object traceThing(ProceedingJoinPoint pjp, Traced traced) throws Throwable {
+  Span span = tracing.tracer().newTrace(sampler.sample(traced))...
+  try {
+    return pjp.proceed();
+  } finally {
+    span.finish();
+  }
+}
4.2 Custom sampling
Depending on what the operation is, you may want to apply different policies.
+For example, you might not want to trace requests to static resources such as images, or you might want to trace all requests to a new api.
Most users use a framework interceptor to automate this sort of policy.
+The following example shows how that might work internally:
@Autowired Tracer tracer;
+
+Span newTrace(Request input) {
+  SamplingFlags flags = SamplingFlags.NONE;
+  if (input.url().startsWith("/experimental")) {
+    flags = SamplingFlags.SAMPLED;
+  } else if (input.url().startsWith("/static")) {
+    flags = SamplingFlags.NOT_SAMPLED;
+  }
+  return tracer.newTrace(flags);
+}
4.3 Sampling in Spring Cloud Sleuth
By default Spring Cloud Sleuth sets all spans to non-exportable.
+That means that traces appear in logs but not in any remote store.
+For testing the default is often enough, and it probably is all you need if you use only the logs (for example, with an ELK aggregator).
+If you export span data to Zipkin, there is also an Sampler.ALWAYS_SAMPLE setting that exports everything and a ProbabilityBasedSampler setting that samples a fixed fraction of spans.
[Note]Note
The ProbabilityBasedSampler is the default if you use spring-cloud-sleuth-zipkin.
+You can configure the exports by setting spring.sleuth.sampler.probability.
+The passed value needs to be a double from 0.0 to 1.0.
A sampler can be installed by creating a bean definition, as shown in the following example:
@Bean
 public Sampler defaultSampler() {
-	return new AlwaysSampler();
-}
[Tip]Tip
You can set the HTTP header X-B3-Flags to 1 or when doing messaging you can
-set spanFlags header to 1. Then the current span will be forced to be exportable
-regardless of the sampling decision.
Prev   Next
3. Features Home 5. Instrumentation

\ No newline at end of file
+	return Sampler.ALWAYS_SAMPLE;
+}
[Tip]Tip

You can set the HTTP header X-B3-Flags to 1, or, when doing messaging, you can set the spanFlags header to 1. +Doing so forces the current span to be exportable regardless of the sampling decision.

Prev   Next
3. Features Home 5. Propagation
\ No newline at end of file diff --git a/2.0.x/multi/multi__sending_spans_to_zipkin.html b/2.0.x/multi/multi__sending_spans_to_zipkin.html index c63c7f4f7..d302fee54 100644 --- a/2.0.x/multi/multi__sending_spans_to_zipkin.html +++ b/2.0.x/multi/multi__sending_spans_to_zipkin.html @@ -1,7 +1,28 @@ - 10. Sending spans to Zipkin
10. Sending spans to Zipkin
Prev   Next

10. Sending spans to Zipkin

By default if you add spring-cloud-starter-zipkin as a dependency to your project, -when the span is closed, it will be sent to Zipkin over HTTP. The communication -is asynchronous. You can configure the URL by setting the spring.zipkin.baseUrl -property as follows:

spring.zipkin.baseUrl: http://192.168.99.100:9411/

If you want to find Zipkin via service discovery it’s enough to pass the -Zipkin’s service id inside the URL (example for zipkinserver service id)

spring.zipkin.baseUrl: http://zipkinserver/
Prev   Next
9. Customizations Home 11. Span Data as Messages
\ No newline at end of file + 13. Sending Spans to Zipkin
13. Sending Spans to Zipkin
Prev   Next

13. Sending Spans to Zipkin

By default, if you add spring-cloud-starter-zipkin as a dependency to your project, when the span is closed, it is sent to Zipkin over HTTP. +The communication is asynchronous. +You can configure the URL by setting the spring.zipkin.baseUrl property, as follows:

spring.zipkin.baseUrl: http://192.168.99.100:9411/

If you want to find Zipkin through service discovery, you can pass the Zipkin’s service ID inside the URL, as shown in the following example for zipkinserver service ID:

spring.zipkin.baseUrl: http://zipkinserver/

To disable this feature just set spring.zipkin.discoveryClientEnabled to `false.

When the Discovery Client feature is enabled, Sleuth uses +LoadBalancerClient to find the URL of the Zipkin Server. It means +that you can set up the load balancing configuration e.g. via Ribbon.

zipkinserver:
+  ribbon:
+    ListOfServers: host1,host2

If you have web, rabbit, or kafka together on the classpath, you might need to pick the means by which you would like to send spans to zipkin. +To do so, set web, rabbit, or kafka to the spring.zipkin.sender.type property. +The following example shows setting the sender type for web:

spring.zipkin.sender.type: web

To customize the RestTemplate that sends spans to Zipkin via HTTP, you can register +the ZipkinRestTemplateCustomizer bean.

@Configuration
+class MyConfig {
+	@Bean ZipkinRestTemplateCustomizer myCustomizer() {
+		return new ZipkinRestTemplateCustomizer() {
+			@Override
+			void customize(RestTemplate restTemplate) {
+				// customize the RestTemplate
+			}
+		};
+	}
+}

If, however, you would like to control the full process of creating the RestTemplate +object, you will have to create a bean of zipkin2.reporter.Sender type.

	@Bean Sender myRestTemplateSender(ZipkinProperties zipkin,
+			ZipkinRestTemplateCustomizer zipkinRestTemplateCustomizer) {
+		RestTemplate restTemplate = mySuperCustomRestTemplate();
+		zipkinRestTemplateCustomizer.customize(restTemplate);
+		return myCustomSender(zipkin, restTemplate);
+	}
Prev   Next
12. Customizations Home 14. Zipkin Stream Span Consumer
\ No newline at end of file diff --git a/2.0.x/multi/multi__span_lifecycle.html b/2.0.x/multi/multi__span_lifecycle.html index 5d06ae5d2..f68933a72 100644 --- a/2.0.x/multi/multi__span_lifecycle.html +++ b/2.0.x/multi/multi__span_lifecycle.html @@ -1,63 +1,59 @@ - 6. Span lifecycle
6. Span lifecycle
Prev   Next

6. Span lifecycle

You can do the following operations on the Span by means of org.springframework.cloud.sleuth.Tracer interface:

  • start - when you start a span its name is assigned and start timestamp is recorded.
  • close - the span gets finished (the end time of the span is recorded) and if -the span is exportable then it will be eligible for collection to Zipkin. -The span is also removed from the current thread.
  • continue - a new instance of span will be created whereas it will be a copy of the -one that it continues.
  • detach - the span doesn’t get stopped or closed. It only gets removed from the current thread.
  • create with explicit parent - you can create a new span and set an explicit parent to it
[Tip]Tip

Spring creates the instance of Tracer for you. In order to use it all you need is to just autowire it.

6.1 Creating and closing spans

You can manually create spans by using the Tracer interface.

// Start a span. If there was a span present in this thread it will become
+   9. Span lifecycle
9. Span lifecycle
Prev   Next
9. Span lifecycle
You can do the following operations on the Span by means of brave.Tracer:
  • start: When you start a span, its name is assigned and the start timestamp is recorded.
  • close: The span gets finished (the end time of the span is recorded) and, if the span is sampled, it is eligible for collection (for example, to Zipkin).
  • continue: A new instance of span is created.
+It is a copy of the one that it continues.
  • detach: The span does not get stopped or closed.
+It only gets removed from the current thread.
  • create with explicit parent: You can create a new span and set an explicit parent for it.
[Tip]Tip
Spring Cloud Sleuth creates an instance of Tracer for you. In order to use it, you can autowire it.
9.1 Creating and finishing spans
You can manually create spans by using the Tracer, as shown in the following example:
// Start a span. If there was a span present in this thread it will become
 // the `newSpan`'s parent.
-Span newSpan = this.tracer.createSpan("calculateTax");
-try {
+Span newSpan = this.tracer.nextSpan().name("calculateTax");
+try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(newSpan.start())) {
 	// ...
 	// You can tag a span
-	this.tracer.addTag("taxValue", taxValue);
+	newSpan.tag("taxValue", taxValue);
 	// ...
 	// You can log an event on a span
-	newSpan.logEvent("taxCalculated");
+	newSpan.annotate("taxCalculated");
 } finally {
-	// Once done remember to close the span. This will allow collecting
+	// Once done remember to finish the span. This will allow collecting
 	// the span to send it to Zipkin
-	this.tracer.close(newSpan);
-}
In this example we could see how to create a new instance of span. Assuming that there already
-was a span present in this thread then it would become the parent of that span.
[Important]Important
Always clean after you create a span! Don’t forget to close a span if you want to send it to Zipkin.
[Important]Important
If your span contains a name greater than 50 chars, then that name will
-be truncated to 50 chars. Your names have to be explicit and concrete. Big names lead to
-latency issues and sometimes even thrown exceptions.
6.2 Continuing spans
Sometimes you don’t want to create a new span but you want to continue one. Example of such a
-situation might be (of course it all depends on the use-case):
  • AOP - If there was already a span created before an aspect was reached then you might not want to create a new span.
  • Hystrix - executing a Hystrix command is most likely a logical part of the current processing. It’s in fact
-only a technical implementation detail that you wouldn’t necessarily want to reflect in tracing as a separate being.
The continued instance of span is equal to the one that it continues:
Span continuedSpan = this.tracer.continueSpan(spanToContinue);
-assertThat(continuedSpan).isEqualTo(spanToContinue);
To continue a span you can use the Tracer interface.
// let's assume that we're in a thread Y and we've received
+	newSpan.finish();
+}
In the preceding example, we could see how to create a new instance of the span.
+If there is already a span in this thread, it becomes the parent of the new span.
[Important]Important
Always clean after you create a span. Also, always finish any span that you want to send to Zipkin.
[Important]Important
If your span contains a name greater than 50 chars, that name is truncated to 50 chars.
+Your names have to be explicit and concrete. Big names lead to latency issues and sometimes even exceptions.
9.2 Continuing Spans
Sometimes, you do not want to create a new span but you want to continue one. An example of such a
+situation might be as follows:
  • AOP: If there was already a span created before an aspect was reached, you might not want to create a new span.
  • Hystrix: Executing a Hystrix command is most likely a logical part of the current processing.
+It is in fact merely a technical implementation detail that you would not necessarily want to reflect in tracing as a separate being.
To continue a span, you can use brave.Tracer, as shown in the following example:
// let's assume that we're in a thread Y and we've received
 // the `initialSpan` from thread X
-Span continuedSpan = this.tracer.continueSpan(initialSpan);
+Span continuedSpan = this.tracer.toSpan(newSpan.context());
 try {
 	// ...
 	// You can tag a span
-	this.tracer.addTag("taxValue", taxValue);
+	continuedSpan.tag("taxValue", taxValue);
 	// ...
 	// You can log an event on a span
-	continuedSpan.logEvent("taxCalculated");
+	continuedSpan.annotate("taxCalculated");
 } finally {
-	// Once done remember to detach the span. That way you'll
-	// safely remove it from the current thread without closing it
-	this.tracer.detach(continuedSpan);
-}
[Important]Important
Always clean after you create a span! Don’t forget to detach a span if some work was done started in one
- thread (e.g. thread X) and it’s waiting for other threads (e.g. Y, Z) to finish.
- Then the spans in the threads Y, Z should be detached at the end of their work. When the results are collected
- the span in thread X should be closed.
6.3 Creating spans with an explicit parent
There is a possibility that you want to start a new span and provide an explicit parent of that span.
-Let’s assume that the parent of a span is in one thread and you want to start a new span in another thread. The
-startSpan method of the Tracer interface is the method you are looking for.
// let's assume that we're in a thread Y and we've received
+	// Once done remember to flush the span. That means that
+	// it will get reported but the span itself is not yet finished
+	continuedSpan.flush();
+}
9.3 Creating a Span with an explicit Parent
You might want to start a new span and provide an explicit parent of that span.
+Assume that the parent of a span is in one thread and you want to start a new span in another thread.
+In Brave, whenever you call nextSpan(), it creates a span in reference to the span that is currently in scope.
+You can put the span in scope and then call nextSpan(), as shown in the following example:
// let's assume that we're in a thread Y and we've received
 // the `initialSpan` from thread X. `initialSpan` will be the parent
 // of the `newSpan`
-Span newSpan = this.tracer.createSpan("calculateCommission", initialSpan);
-try {
+Span newSpan = null;
+try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(initialSpan)) {
+	newSpan = this.tracer.nextSpan().name("calculateCommission");
 	// ...
 	// You can tag a span
-	this.tracer.addTag("commissionValue", commissionValue);
+	newSpan.tag("commissionValue", commissionValue);
 	// ...
 	// You can log an event on a span
-	newSpan.logEvent("commissionCalculated");
+	newSpan.annotate("commissionCalculated");
 } finally {
-	// Once done remember to close the span. This will allow collecting
+	// Once done remember to finish the span. This will allow collecting
 	// the span to send it to Zipkin. The tags and events set on the
 	// newSpan will not be present on the parent
-	this.tracer.close(newSpan);
-}
[Important]Important
After having created such a span remember to close it. Otherwise you will see a lot of warnings in your logs
- related to the fact that you have a span present in the current thread other than the one you’re trying to close.
- What’s worse your spans won’t get closed properly thus will not get collected to Zipkin.
Prev   Next
5. Instrumentation Home 7. Naming spans

\ No newline at end of file
+	if (newSpan != null) {
+		newSpan.finish();
+	}
+}
[Important]Important

After creating such a span, you must finish it. Otherwise it is not reported (for example, to Zipkin).

Prev   Next
8. Instrumentation Home 10. Naming spans
\ No newline at end of file diff --git a/2.0.x/multi/multi__zipkin_stream_span_consumer.html b/2.0.x/multi/multi__zipkin_stream_span_consumer.html new file mode 100644 index 000000000..6570accf0 --- /dev/null +++ b/2.0.x/multi/multi__zipkin_stream_span_consumer.html @@ -0,0 +1,5 @@ + + + 14. Zipkin Stream Span Consumer
14. Zipkin Stream Span Consumer
Prev   Next

14. Zipkin Stream Span Consumer

[Important]Important

We recommend using Zipkin’s native support for message-based span sending. +Starting from the Edgware release, the Zipkin Stream server is deprecated. +In the Finchley release, it got removed.

If for some reason you need to create the deprecated Stream Zipkin server, see the Dalston Documentation.

Prev   Next
13. Sending Spans to Zipkin Home 15. Integrations
\ No newline at end of file diff --git a/2.0.x/multi/multi_pr01.html b/2.0.x/multi/multi_pr01.html index 36c974284..9d68e972d 100644 --- a/2.0.x/multi/multi_pr01.html +++ b/2.0.x/multi/multi_pr01.html @@ -1,3 +1,3 @@ -
Prev   Next

2.0.0.BUILD-SNAPSHOT

Prev   Next
Spring Cloud Sleuth Home 1. Introduction
\ No newline at end of file +
Prev   Next

2.0.1.BUILD-SNAPSHOT

Prev   Next
Spring Cloud Sleuth Home 1. Introduction
\ No newline at end of file diff --git a/2.0.x/multi/multi_spring-cloud-sleuth.html b/2.0.x/multi/multi_spring-cloud-sleuth.html index a735595ec..f52ccbb79 100644 --- a/2.0.x/multi/multi_spring-cloud-sleuth.html +++ b/2.0.x/multi/multi_spring-cloud-sleuth.html @@ -1,3 +1,3 @@ - Spring Cloud Sleuth
Spring Cloud Sleuth
   Next

Spring Cloud Sleuth

Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer

Table of Contents

1. Introduction
1.1. Terminology
1.2. Purpose
1.2.1. Distributed tracing with Zipkin
1.2.2. Visualizing errors
1.2.3. Live examples
1.2.4. Log correlation
JSON Logback with Logstash
1.2.5. Propagating Span Context
Baggage vs. Span Tags
1.3. Adding to the project
1.3.1. Only Sleuth (log correlation)
1.3.2. Sleuth with Zipkin via HTTP
1.3.3. Sleuth with Zipkin via RabbitMQ or Kafka
2. Additional resources
3. Features
4. Sampling
5. Instrumentation
6. Span lifecycle
6.1. Creating and closing spans
6.2. Continuing spans
6.3. Creating spans with an explicit parent
7. Naming spans
7.1. @SpanName annotation
7.2. toString() method
8. Managing spans with annotations
8.1. Rationale
8.2. Creating new spans
8.3. Continuing spans
8.4. More advanced tag setting
8.4.1. Custom extractor
8.4.2. Resolving expressions for value
8.4.3. Using toString method
9. Customizations
9.1. Spring Integration
9.2. HTTP
9.3. Example
9.4. TraceFilter
9.5. Custom SA tag in Zipkin
9.6. Custom service name
9.7. Customization of reported spans
9.8. Host locator
10. Sending spans to Zipkin
11. Span Data as Messages
11.1. Zipkin Consumer
11.2. Custom Consumer
12. Metrics
13. Integrations
13.1. Runnable and Callable
13.2. Hystrix
13.2.1. Custom Concurrency Strategy
13.2.2. Manual Command setting
13.3. RxJava
13.4. HTTP integration
13.4.1. HTTP Filter
13.4.2. HandlerInterceptor
13.4.3. Async Servlet support
13.4.4. WebFlux support
13.5. HTTP client integration
13.5.1. Synchronous Rest Template
13.5.2. Asynchronous Rest Template
Multiple Asynchronous Rest Templates
13.5.3. WebClient
13.5.4. Traverson
13.6. Feign
13.7. Asynchronous communication
13.7.1. @Async annotated methods
13.7.2. @Scheduled annotated methods
13.7.3. Executor, ExecutorService and ScheduledExecutorService
Customization of Executors
13.8. Messaging
13.9. Zuul
14. Running examples
   Next
   
\ No newline at end of file + Spring Cloud Sleuth
Spring Cloud Sleuth
   Next

Spring Cloud Sleuth

Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer, Jay Bryant

Table of Contents

1. Introduction
1.1. Terminology
1.2. Purpose
1.2.1. Distributed Tracing with Zipkin
1.2.2. Visualizing errors
1.2.3. Distributed Tracing with Brave
1.2.4. Live examples
1.2.5. Log correlation
JSON Logback with Logstash
1.2.6. Propagating Span Context
Baggage versus Span Tags
1.3. Adding Sleuth to the Project
1.3.1. Only Sleuth (log correlation)
1.3.2. Sleuth with Zipkin via HTTP
1.3.3. Sleuth with Zipkin over RabbitMQ or Kafka
2. Additional Resources
3. Features
3.1. Introduction to Brave
3.1.1. Tracing
3.1.2. Local Tracing
3.1.3. Customizing Spans
3.1.4. Implicitly Looking up the Current Span
3.1.5. RPC tracing
One-Way tracing
4. Sampling
4.1. Declarative sampling
4.2. Custom sampling
4.3. Sampling in Spring Cloud Sleuth
5. Propagation
5.1. Propagating extra fields
5.1.1. Prefixed fields
5.1.2. Extracting a Propagated Context
5.1.3. Sharing span IDs between Client and Server
5.1.4. Implementing Propagation
6. Current Tracing Component
7. Current Span
7.1. Setting a span in scope manually
8. Instrumentation
9. Span lifecycle
9.1. Creating and finishing spans
9.2. Continuing Spans
9.3. Creating a Span with an explicit Parent
10. Naming spans
10.1. @SpanName Annotation
10.2. toString() method
11. Managing Spans with Annotations
11.1. Rationale
11.2. Creating New Spans
11.3. Continuing Spans
11.4. Advanced Tag Setting
11.4.1. Custom extractor
11.4.2. Resolving Expressions for a Value
11.4.3. Using the toString() method
12. Customizations
12.1. HTTP
12.2. TracingFilter
12.3. Custom service name
12.4. Customization of Reported Spans
12.5. Host Locator
13. Sending Spans to Zipkin
14. Zipkin Stream Span Consumer
15. Integrations
15.1. OpenTracing
15.2. Runnable and Callable
15.3. Hystrix
15.3.1. Custom Concurrency Strategy
15.3.2. Manual Command setting
15.4. RxJava
15.5. HTTP integration
15.5.1. HTTP Filter
15.5.2. HandlerInterceptor
15.5.3. Async Servlet support
15.5.4. WebFlux support
15.5.5. Dubbo RPC support
15.6. HTTP Client Integration
15.6.1. Synchronous Rest Template
15.6.2. Asynchronous Rest Template
Multiple Asynchronous Rest Templates
15.6.3. WebClient
15.6.4. Traverson
15.6.5. Apache HttpClientBuilder and HttpAsyncClientBuilder
15.6.6. Netty HttpClient
15.6.7. UserInfoRestTemplateCustomizer
15.7. Feign
15.8. Asynchronous Communication
15.8.1. @Async Annotated methods
15.8.2. @Scheduled Annotated Methods
15.8.3. Executor, ExecutorService, and ScheduledExecutorService
Customization of Executors
15.9. Messaging
15.9.1. Spring Integration and Spring Cloud Stream
15.9.2. Spring RabbitMq
15.9.3. Spring Kafka
15.10. Zuul
16. Running examples
   Next
   
\ No newline at end of file diff --git a/2.0.x/single/images/callouts/1.png b/2.0.x/single/images/callouts/1.png new file mode 100644 index 000000000..7d473430b Binary files /dev/null and b/2.0.x/single/images/callouts/1.png differ diff --git a/2.0.x/single/images/callouts/2.png b/2.0.x/single/images/callouts/2.png new file mode 100644 index 000000000..5d09341b2 Binary files /dev/null and b/2.0.x/single/images/callouts/2.png differ diff --git a/2.0.x/single/images/callouts/3.png b/2.0.x/single/images/callouts/3.png new file mode 100644 index 000000000..ef7b70047 Binary files /dev/null and b/2.0.x/single/images/callouts/3.png differ diff --git a/2.0.x/single/spring-cloud-sleuth.html b/2.0.x/single/spring-cloud-sleuth.html index 14fdc7ed5..056cff6c0 100644 --- a/2.0.x/single/spring-cloud-sleuth.html +++ b/2.0.x/single/spring-cloud-sleuth.html @@ -1,52 +1,59 @@ - Spring Cloud Sleuth

Spring Cloud Sleuth

Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer

Table of Contents

1. Introduction
1.1. Terminology
1.2. Purpose
1.2.1. Distributed tracing with Zipkin
1.2.2. Visualizing errors
1.2.3. Live examples
1.2.4. Log correlation
JSON Logback with Logstash
1.2.5. Propagating Span Context
Baggage vs. Span Tags
1.3. Adding to the project
1.3.1. Only Sleuth (log correlation)
1.3.2. Sleuth with Zipkin via HTTP
1.3.3. Sleuth with Zipkin via RabbitMQ or Kafka
2. Additional resources
3. Features
4. Sampling
5. Instrumentation
6. Span lifecycle
6.1. Creating and closing spans
6.2. Continuing spans
6.3. Creating spans with an explicit parent
7. Naming spans
7.1. @SpanName annotation
7.2. toString() method
8. Managing spans with annotations
8.1. Rationale
8.2. Creating new spans
8.3. Continuing spans
8.4. More advanced tag setting
8.4.1. Custom extractor
8.4.2. Resolving expressions for value
8.4.3. Using toString method
9. Customizations
9.1. Spring Integration
9.2. HTTP
9.3. Example
9.4. TraceFilter
9.5. Custom SA tag in Zipkin
9.6. Custom service name
9.7. Customization of reported spans
9.8. Host locator
10. Sending spans to Zipkin
11. Span Data as Messages
11.1. Zipkin Consumer
11.2. Custom Consumer
12. Metrics
13. Integrations
13.1. Runnable and Callable
13.2. Hystrix
13.2.1. Custom Concurrency Strategy
13.2.2. Manual Command setting
13.3. RxJava
13.4. HTTP integration
13.4.1. HTTP Filter
13.4.2. HandlerInterceptor
13.4.3. Async Servlet support
13.4.4. WebFlux support
13.5. HTTP client integration
13.5.1. Synchronous Rest Template
13.5.2. Asynchronous Rest Template
Multiple Asynchronous Rest Templates
13.5.3. WebClient
13.5.4. Traverson
13.6. Feign
13.7. Asynchronous communication
13.7.1. @Async annotated methods
13.7.2. @Scheduled annotated methods
13.7.3. Executor, ExecutorService and ScheduledExecutorService
Customization of Executors
13.8. Messaging
13.9. Zuul
14. Running examples

2.0.0.BUILD-SNAPSHOT

1. Introduction

Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud.

1.1 Terminology

Spring Cloud Sleuth borrows Dapper’s terminology.

Span: The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an -RPC. Span’s are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span -is a part of. Spans also have other data, such as descriptions, timestamped events, key-value -annotations (tags), the ID of the span that caused them, and process ID’s (normally IP address).

Spans are started and stopped, and they keep track of their timing information. Once you create a -span, you must stop it at some point in the future.

[Tip]Tip

The initial span that starts a trace is called a root span. The value of span id -of that span is equal to trace id.

Trace: A set of spans forming a tree-like structure. For example, if you are running a distributed -big-data store, a trace might be formed by a put request.

Annotation: is used to record existence of an event in time. Some of the core annotations used to define -the start and stop of a request are:

  • cs - Client Sent - The client has made a request. This annotation depicts the start of the span.
  • sr - Server Received - The server side got the request and will start processing it. -If one subtracts the cs timestamp from this timestamp one will receive the network latency.
  • ss - Server Sent - Annotated upon completion of request processing (when the response -got sent back to the client). If one subtracts the sr timestamp from this timestamp one -will receive the time needed by the server side to process the request.
  • cr - Client Received - Signifies the end of the span. The client has successfully received the -response from the server side. If one subtracts the cs timestamp from this timestamp one -will receive the whole time needed by the client to receive the response from the server.

Visualization of what Span and Trace will look in a system together with the Zipkin annotations:

Trace Info propagation

Each color of a note signifies a span (7 spans - from A to G). If you have such information in the note:

Trace Id = X
+   Spring Cloud Sleuth
Spring Cloud Sleuth
Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer, Jay Bryant
Table of Contents
1. Introduction
1.1. Terminology
1.2. Purpose
1.2.1. Distributed Tracing with Zipkin
1.2.2. Visualizing errors
1.2.3. Distributed Tracing with Brave
1.2.4. Live examples
1.2.5. Log correlation
JSON Logback with Logstash
1.2.6. Propagating Span Context
Baggage versus Span Tags
1.3. Adding Sleuth to the Project
1.3.1. Only Sleuth (log correlation)
1.3.2. Sleuth with Zipkin via HTTP
1.3.3. Sleuth with Zipkin over RabbitMQ or Kafka
2. Additional Resources
3. Features
3.1. Introduction to Brave
3.1.1. Tracing
3.1.2. Local Tracing
3.1.3. Customizing Spans
3.1.4. Implicitly Looking up the Current Span
3.1.5. RPC tracing
One-Way tracing
4. Sampling
4.1. Declarative sampling
4.2. Custom sampling
4.3. Sampling in Spring Cloud Sleuth
5. Propagation
5.1. Propagating extra fields
5.1.1. Prefixed fields
5.1.2. Extracting a Propagated Context
5.1.3. Sharing span IDs between Client and Server
5.1.4. Implementing Propagation
6. Current Tracing Component
7. Current Span
7.1. Setting a span in scope manually
8. Instrumentation
9. Span lifecycle
9.1. Creating and finishing spans
9.2. Continuing Spans
9.3. Creating a Span with an explicit Parent
10. Naming spans
10.1. @SpanName Annotation
10.2. toString() method
11. Managing Spans with Annotations
11.1. Rationale
11.2. Creating New Spans
11.3. Continuing Spans
11.4. Advanced Tag Setting
11.4.1. Custom extractor
11.4.2. Resolving Expressions for a Value
11.4.3. Using the toString() method
12. Customizations
12.1. HTTP
12.2. TracingFilter
12.3. Custom service name
12.4. Customization of Reported Spans
12.5. Host Locator
13. Sending Spans to Zipkin
14. Zipkin Stream Span Consumer
15. Integrations
15.1. OpenTracing
15.2. Runnable and Callable
15.3. Hystrix
15.3.1. Custom Concurrency Strategy
15.3.2. Manual Command setting
15.4. RxJava
15.5. HTTP integration
15.5.1. HTTP Filter
15.5.2. HandlerInterceptor
15.5.3. Async Servlet support
15.5.4. WebFlux support
15.5.5. Dubbo RPC support
15.6. HTTP Client Integration
15.6.1. Synchronous Rest Template
15.6.2. Asynchronous Rest Template
Multiple Asynchronous Rest Templates
15.6.3. WebClient
15.6.4. Traverson
15.6.5. Apache HttpClientBuilder and HttpAsyncClientBuilder
15.6.6. Netty HttpClient
15.6.7. UserInfoRestTemplateCustomizer
15.7. Feign
15.8. Asynchronous Communication
15.8.1. @Async Annotated methods
15.8.2. @Scheduled Annotated Methods
15.8.3. Executor, ExecutorService, and ScheduledExecutorService
Customization of Executors
15.9. Messaging
15.9.1. Spring Integration and Spring Cloud Stream
15.9.2. Spring RabbitMq
15.9.3. Spring Kafka
15.10. Zuul
16. Running examples
2.0.1.BUILD-SNAPSHOT
1. Introduction
Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud.
1.1 Terminology
Spring Cloud Sleuth borrows Dapper’s terminology.
Span: The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an RPC.
+Spans are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span is a part of.
+Spans also have other data, such as descriptions, timestamped events, key-value annotations (tags), the ID of the span that caused them, and process IDs (normally IP addresses).
Spans can be started and stopped, and they keep track of their timing information.
+Once you create a span, you must stop it at some point in the future.
[Tip]Tip
The initial span that starts a trace is called a root span. The value of the ID
+of that span is equal to the trace ID.
Trace: A set of spans forming a tree-like structure.
+For example, if you run a distributed big-data store, a trace might be formed by a PUT request.
Annotation:  Used to record the existence of an event in time. With
+Brave instrumentation, we no longer need to set special events
+for Zipkin to understand who the client and server are, where
+the request started, and where it ended. For learning purposes,
+however, we mark these events to highlight what kind
+of an action took place.
  • cs: Client Sent. The client has made a request. This annotation indicates the start of the span.
  • sr: Server Received: The server side got the request and started processing it.
+Subtracting the cs timestamp from this timestamp reveals the network latency.
  • ss: Server Sent. Annotated upon completion of request processing (when the response got sent back to the client).
+Subtracting the sr timestamp from this timestamp reveals the time needed by the server side to process the request.
  • cr: Client Received. Signifies the end of the span.
+The client has successfully received the response from the server side.
+Subtracting the cs timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server.
The following image shows how Span and Trace look in a system, together with the Zipkin annotations:
Trace Info propagation
Each color of a note signifies a span (there are seven spans - from A to G).
+Consider the following note:
Trace Id = X
 Span Id = D
-Client Sent
That means that the current span has Trace-Id set to X, Span-Id set to D. It also has emitted
- Client Sent event.
This is how the visualization of the parent / child relationship of spans would look like:
Parent child relationship
1.2 Purpose
In the following sections the example from the image above will be taken into consideration.
1.2.1 Distributed tracing with Zipkin
Altogether there are 7 spans . If you go to traces in Zipkin you will see this number in the second trace:
Traces
However if you pick a particular trace then you will see 4 spans:
Traces Info propagation
[Note]Note
When picking a particular trace you will see merged spans. That means that if there were 2 spans sent to
-Zipkin with Server Received and Server Sent / Client Received and Client Sent
-annotations then they will presented as a single span.
Why is there a difference between the 7 and 4 spans in this case?
  • 2 spans come from http:/start span. It has the Server Received (SR) and Server Sent (SS) annotations.
  • 2 spans come from the RPC call from service1 to service2 to the http:/foo endpoint. It has the Client Sent (CS)
-and Client Received (CR) annotations on service1 side. It also has Server Received (SR) and Server Sent (SS) annotations
-on the service2 side. Physically there are 2 spans but they form 1 logical span related to an RPC call.
  • 2 spans come from the RPC call from service2 to service3 to the http:/bar endpoint. It has the Client Sent (CS)
-and Client Received (CR) annotations on service2 side. It also has Server Received (SR) and Server Sent (SS) annotations
-on the service3 side. Physically there are 2 spans but they form 1 logical span related to an RPC call.
  • 2 spans come from the RPC call from service2 to service4 to the http:/baz endpoint. It has the Client Sent (CS)
-and Client Received (CR) annotations on service2 side. It also has Server Received (SR) and Server Sent (SS) annotations
-on the service4 side. Physically there are 2 spans but they form 1 logical span related to an RPC call.
So if we count the physical spans we have 1 from http:/start, 2 from service1 calling service2, 2 form service2
-calling service3 and 2 from service2 calling service4. Altogether 7 spans.
Logically we see the information of Total Spans: 4 because we have 1 span related to the incoming request
-to service1 and 3 spans related to RPC calls.
1.2.2 Visualizing errors
Zipkin allows you to visualize errors in your trace. When an exception was thrown and wasn’t caught then we’re
-setting proper tags on the span which Zipkin can properly colorize. You could see in the list of traces one
-  trace that was in red color. That’s because there was an exception thrown.
If you click that trace then you’ll see a similar picture
Error Traces
Then if you click on one of the spans you’ll see the following
Error Traces Info propagation
As you can see you can easily see the reason for an error and the whole stacktrace related to it.
1.2.3 Live examples
Figure 1.1. Click Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

The dependency graph in Zipkin would look like this:
Dependencies
Figure 1.2. Click Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

1.2.4 Log correlation
When grepping the logs of those four applications by trace id equal to e.g. 2485ec27856c56f4 one would get the following:
service1.log:2016-02-26 11:15:47.561  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Hello from service1. Calling service2
+Client Sent
This note indicates that the current span has Trace Id set to X and Span Id set to D.
+Also, the Client Sent event took place.
The following image shows how parent-child relationships of spans look:
Parent child relationship
1.2 Purpose
The following sections refer to the example shown in the preceding image.
1.2.1 Distributed Tracing with Zipkin
This example has seven spans.
+If you go to traces in Zipkin, you can see this number in the second trace, as shown in the following image:
Traces
However, if you pick a particular trace, you can see four spans, as shown in the following image:
Traces Info propagation
[Note]Note
When you pick a particular trace, you see merged spans.
+That means that, if there were two spans sent to Zipkin with Server Received and Server Sent or Client Received and Client Sent annotations, they are presented as a single span.
Why is there a difference between the seven and four spans in this case?
  • Two spans come from the http:/start span. It has the Server Received (sr) and Server Sent (ss) annotations.
  • Two spans come from the RPC call from service1 to service2 to the http:/foo endpoint.
+The Client Sent (cs) and Client Received (cr) events took place on the service1 side.
+Server Received (sr) and Server Sent (ss) events took place on the service2 side.
+These two spans form one logical span related to an RPC call.
  • Two spans come from the RPC call from service2 to service3 to the http:/bar endpoint.
+The Client Sent (cs) and Client Received (cr) events took place on the service2 side.
+The Server Received (sr) and Server Sent (ss) events took place on the service3 side.
+These two spans form one logical span related to an RPC call.
  • Two spans come from the RPC call from service2 to service4 to the http:/baz endpoint.
+The Client Sent (cs) and Client Received (cr) events took place on the service2 side.
+Server Received (sr) and Server Sent (ss) events took place on the service4 side.
+These two spans form one logical span related to an RPC call.
So, if we count the physical spans, we have one from http:/start, two from service1 calling service2, two from service2
+calling service3, and two from service2 calling service4. In sum, we have a total of seven spans.
Logically, we see the information of four total Spans because we have one span related to the incoming request
+to service1 and three spans related to RPC calls.
1.2.2 Visualizing errors
Zipkin lets you visualize errors in your trace.
+When an exception was thrown and was not caught, we set proper tags on the span, which Zipkin can then properly colorize.
+You could see in the list of traces one trace that is red. That appears because an exception was thrown.
If you click that trace, you see a similar picture, as follows:
Error Traces
If you then click on one of the spans, you see the following
Error Traces Info propagation
The span shows the reason for the error and the whole stack trace related to it.
1.2.3 Distributed Tracing with Brave
Starting with version 2.0.0, Spring Cloud Sleuth uses Brave as the tracing library.
+Consequently, Sleuth no longer takes care of storing the context but delegates that work to Brave.
Due to the fact that Sleuth had different naming and tagging conventions than Brave, we decided to follow Brave’s conventions from now on.
+However, if you want to use the legacy Sleuth approaches, you can set the spring.sleuth.http.legacy.enabled property to true.
1.2.4 Live examples
Figure 1.1. Click the Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

Click here to see it live!
The dependency graph in Zipkin should resemble the following image:
Dependencies
Figure 1.2. Click the Pivotal Web Services icon to see it live!
Zipkin deployed on Pivotal Web Services

Click here to see it live!
1.2.5 Log correlation
When using grep to read the logs of those four applications by scanning for a trace ID equal to (for example) 2485ec27856c56f4, you get output resembling the following:
service1.log:2016-02-26 11:15:47.561  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Hello from service1. Calling service2
 service2.log:2016-02-26 11:15:47.710  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Hello from service2. Calling service3 and then service4
 service3.log:2016-02-26 11:15:47.895  INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application   : Hello from service3
 service2.log:2016-02-26 11:15:47.924  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service3 [Hello from service3]
 service4.log:2016-02-26 11:15:48.134  INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application   : Hello from service4
 service2.log:2016-02-26 11:15:48.156  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service4 [Hello from service4]
-service1.log:2016-02-26 11:15:48.182  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]
If you’re using a log aggregating tool like Kibana,
-Splunk etc. you can order the events that took place. An example of
-Kibana would look like this:
Log correlation with Kibana
If you want to use Logstash here is the Grok pattern for Logstash:
filter {
+service1.log:2016-02-26 11:15:48.182  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]
If you use a log aggregating tool (such as Kibana, Splunk, and others), you can order the events that took place.
+An example from Kibana would resemble the following image:
Log correlation with Kibana
If you want to use Logstash, the following listing shows the Grok pattern for Logstash:
filter {
        # pattern matching logback pattern
        grok {
               match => { "message" => "%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
        }
-}
[Note]Note
If you want to use Grok together with the logs from Cloud Foundry you have to use this pattern:
filter {
+}
[Note]Note
If you want to use Grok together with the logs from Cloud Foundry, you have to use the following pattern:
filter {
        # pattern matching logback pattern
        grok {
               match => { "message" => "(?m)OUT\s+%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
        }
-}
JSON Logback with Logstash
Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability
-we’re passing the dependencies in the groupId:artifactId:version notation.
Dependencies setup
  • Ensure that Logback is on the classpath (ch.qos.logback:logback-core)
  • Add Logstash Logback encode - example for version 4.6 : net.logstash.logback:logstash-logback-encoder:4.6
Logback setup
Below you can find an example of a Logback configuration (file named logback-spring.xml) that:
  • logs information from the application in a JSON format to a build/${spring.application.name}.json file
  • has commented out two additional appenders - console and standard log file
  • has the same logging pattern as the one presented in the previous section
<?xml version="1.0" encoding="UTF-8"?>
+}
JSON Logback with Logstash
Often, you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick.
+To do so, you have to do the following (for readability, we pass the dependencies in the groupId:artifactId:version notation).
Dependencies Setup
  1. Ensure that Logback is on the classpath (ch.qos.logback:logback-core).
  2. Add Logstash Logback encode. For example, to use version 4.6, add net.logstash.logback:logstash-logback-encoder:4.6.
Logback Setup
Consider the following example of a Logback configuration file (named logback-spring.xml).
<?xml version="1.0" encoding="UTF-8"?>
 <configuration>
 	<include resource="org/springframework/boot/logging/logback/defaults.xml"/>
 	​
@@ -121,44 +128,51 @@ we’re passing the dependencies in the groupId:artifa
 		<!--<appender-ref ref="logstash"/>-->
 		<!--<appender-ref ref="flatfile"/>-->
 	</root>
-</configuration>
[Note]Note
If you’re using a custom logback-spring.xml then you have to pass the spring.application.name in
-bootstrap instead of application property file. Otherwise your custom logback file won’t read the property properly.
1.2.5 Propagating Span Context
The span context is the state that must get propagated to any child Spans across process boundaries.
+</configuration>

That Logback configuration file:

  • Logs information from the application in a JSON format to a build/${spring.application.name}.json file.
  • Has commented out two additional appenders: console and standard log file.
  • Has the same logging pattern as the one presented in the previous section.
[Note]Note

If you use a custom logback-spring.xml, you must pass the spring.application.name in the bootstrap rather than the application property file. +Otherwise, your custom logback file does not properly read the property.

1.2.6 Propagating Span Context

The span context is the state that must get propagated to any child spans across process boundaries. Part of the Span Context is the Baggage. The trace and span IDs are a required part of the span context. -Baggage is an optional part.

Baggage is a set of key:value pairs stored in the span context. Baggage travels together with the trace -and is attached to every span. Spring Cloud Sleuth will understand that a header is baggage related if the HTTP - header is prefixed with baggage- and for messaging it starts with baggage_.

[Important]Important

There’s currently no limitation of the count or size of baggage items. However, keep in mind that -too many can decrease system throughput or increase RPC latency. In extreme cases, it could crash the app due -to exceeding transport-level message or header capacity.

Example of setting baggage on a span:

Span initialSpan = this.tracer.createSpan("span");
-initialSpan.setBaggageItem("foo", "bar");
-initialSpan.setBaggageItem("UPPER_CASE", "someValue");

Baggage vs. Span Tags

Baggage travels with the trace (i.e. every child span contains the baggage of its parent). Zipkin has no knowledge of -baggage and will not even receive that information.

Tags are attached to a specific span - they are presented for that particular span only. However you -can search by tag to find the trace, where there exists a span having the searched tag value.

If you want to be able to lookup a span based on baggage, you should add corresponding entry as a tag in the root span.

@Autowired Tracer tracer;
-
-Span span = tracer.getCurrentSpan();
-String baggageKey = "key";
-String baggageValue = "foo";
-span.setBaggageItem(baggageKey, baggageValue);
-tracer.addTag(baggageKey, baggageValue);

1.3 Adding to the project

[Important]Important

To ensure that your application name is properly displayed in Zipkin - set the spring.application.name property in bootstrap.yml.

1.3.1 Only Sleuth (log correlation)

If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add -the spring-cloud-starter-sleuth module to your project.

Maven.  +Baggage is an optional part.

Baggage is a set of key:value pairs stored in the span context. +Baggage travels together with the trace and is attached to every span. +Spring Cloud Sleuth understands that a header is baggage-related if the HTTP header is prefixed with baggage- and, for messaging, it starts with baggage_.

[Important]Important

There is currently no limitation of the count or size of baggage items. +However, keep in mind that too many can decrease system throughput or increase RPC latency. +In extreme cases, too much baggage can crash the application, due to exceeding transport-level message or header capacity.

The following example shows setting baggage on a span:

Span initialSpan = this.tracer.nextSpan().name("span").start();
+try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(initialSpan)) {
+	ExtraFieldPropagation.set("foo", "bar");
+	ExtraFieldPropagation.set("UPPER_CASE", "someValue");
+}

Baggage versus Span Tags

Baggage travels with the trace (every child span contains the baggage of its parent). +Zipkin has no knowledge of baggage and does not receive that information.

[Important]Important

Starting from Sleuth 2.0.0 you have to pass the baggage key names explicitly +in your project configuration. Read more about that setup here

Tags are attached to a specific span. In other words, they are presented only for that particular span. +However, you can search by tag to find the trace, assuming a span having the searched tag value exists.

If you want to be able to lookup a span based on baggage, you should add a corresponding entry as a tag in the root span.

[Important]Important

The span must be in scope.

The following listing shows integration tests that use baggage:

The setup.  +

spring.sleuth:
+  baggage-keys:
+    - baz
+    - bizarrecase
+  propagation-keys:
+    - foo
+    - upper_case

+

The code.  +

initialSpan.tag("foo",
+		ExtraFieldPropagation.get(initialSpan.context(), "foo"));
+initialSpan.tag("UPPER_CASE",
+		ExtraFieldPropagation.get(initialSpan.context(), "UPPER_CASE"));

+

1.3 Adding Sleuth to the Project

This section addresses how to add Sleuth to your project with either Maven or Gradle.

[Important]Important

To ensure that your application name is properly displayed in Zipkin, set the spring.application.name property in bootstrap.yml.

1.3.1 Only Sleuth (log correlation)

If you want to use only Spring Cloud Sleuth without the Zipkin integration, add the spring-cloud-starter-sleuth module to your project.

The following example shows how to add Sleuth with Maven:

Maven.  

<dependencyManagement> 1
-         <dependencies>
-             <dependency>
-                 <groupId>org.springframework.cloud</groupId>
-                 <artifactId>spring-cloud-dependencies</artifactId>
-                 <version>${release.train.version}</version>
-                 <type>pom</type>
-                 <scope>import</scope>
-             </dependency>
-         </dependencies>
-   </dependencyManagement>
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>${release.train.version}</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
 
-   <dependency> 2
-       <groupId>org.springframework.cloud</groupId>
-       <artifactId>spring-cloud-starter-sleuth</artifactId>
-   </dependency>

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-sleuth

Gradle.  +<dependency> 2 + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-sleuth</artifactId> +</dependency>

+

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-sleuth.

The following example shows how to add Sleuth with Gradle:

Gradle.  

dependencyManagement { 1
     imports {
         mavenBom "org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"
@@ -168,26 +182,24 @@ the Spring BOM
2
     compile "org.springframework.cloud:spring-cloud-starter-sleuth"
 }

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-sleuth

1.3.2 Sleuth with Zipkin via HTTP

If you want both Sleuth and Zipkin just add the spring-cloud-starter-zipkin dependency.

Maven.  +

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-sleuth.

1.3.2 Sleuth with Zipkin via HTTP

If you want both Sleuth and Zipkin, add the spring-cloud-starter-zipkin dependency.

The following example shows how to do so for Maven:

Maven.  

<dependencyManagement> 1
-         <dependencies>
-             <dependency>
-                 <groupId>org.springframework.cloud</groupId>
-                 <artifactId>spring-cloud-dependencies</artifactId>
-                 <version>${release.train.version}</version>
-                 <type>pom</type>
-                 <scope>import</scope>
-             </dependency>
-         </dependencies>
-   </dependencyManagement>
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>${release.train.version}</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
 
-   <dependency> 2
-       <groupId>org.springframework.cloud</groupId>
-       <artifactId>spring-cloud-starter-zipkin</artifactId>
-   </dependency>

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin

Gradle.  +<dependency> 2 + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-zipkin</artifactId> +</dependency>

+

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-zipkin.

The following example shows how to do so for Gradle:

Gradle.  

dependencyManagement { 1
     imports {
         mavenBom "org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"
@@ -197,32 +209,30 @@ the Spring BOM
2
     compile "org.springframework.cloud:spring-cloud-starter-zipkin"
 }

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin

1.3.3 Sleuth with Zipkin via RabbitMQ or Kafka

If you want to use RabbitMQ or Kafka instead of http, add the spring-rabbit or spring-kafka -dependencies. The default destination name is zipkin.

Note: spring-cloud-sleuth-stream is deprecated and incompatible with these destinations

If you want Sleuth over RabbitMQ add the spring-cloud-starter-zipkin and spring-rabbit -dependencies.

Maven.  +

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-zipkin.

1.3.3 Sleuth with Zipkin over RabbitMQ or Kafka

If you want to use RabbitMQ or Kafka instead of HTTP, add the spring-rabbit or spring-kafka dependency. +The default destination name is zipkin.

If using Kafka, you must set the property spring.zipkin.sender.type property accordingly:

spring.zipkin.sender.type: kafka
[Caution]Caution

spring-cloud-sleuth-stream is deprecated and incompatible with these destinations.

If you want Sleuth over RabbitMQ, add the spring-cloud-starter-zipkin and spring-rabbit +dependencies.

The following example shows how to do so for Gradle:

Maven.  

<dependencyManagement> 1
-         <dependencies>
-             <dependency>
-                 <groupId>org.springframework.cloud</groupId>
-                 <artifactId>spring-cloud-dependencies</artifactId>
-                 <version>${release.train.version}</version>
-                 <type>pom</type>
-                 <scope>import</scope>
-             </dependency>
-         </dependencies>
-   </dependencyManagement>
+      <dependencies>
+          <dependency>
+              <groupId>org.springframework.cloud</groupId>
+              <artifactId>spring-cloud-dependencies</artifactId>
+              <version>${release.train.version}</version>
+              <type>pom</type>
+              <scope>import</scope>
+          </dependency>
+      </dependencies>
+</dependencyManagement>
 
-   <dependency> 2
-       <groupId>org.springframework.cloud</groupId>
-       <artifactId>spring-cloud-starter-zipkin</artifactId>
-   </dependency>
-   <dependency> 3
-       <groupId>org.springframework.amqp</groupId>
-       <artifactId>spring-rabbit</artifactId>
-   </dependency>

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin - that way all dependent dependencies will be downloaded

3

To automatically configure rabbit, simply add the spring-rabbit dependency

Gradle.  +<dependency> 2 + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-zipkin</artifactId> +</dependency> +<dependency> 3 + <groupId>org.springframework.amqp</groupId> + <artifactId>spring-rabbit</artifactId> +</dependency>

+

1

We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.

2

Add the dependency to spring-cloud-starter-zipkin. That way, all nested dependencies get downloaded.

3

To automatically configure RabbitMQ, add the spring-rabbit dependency.

Gradle.  

dependencyManagement { 1
     imports {
         mavenBom "org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"
@@ -233,136 +243,350 @@ dependencies {
     compile "org.springframework.cloud:spring-cloud-starter-zipkin" 2
     compile "org.springframework.amqp:spring-rabbit" 3
 }

-

1

In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM

2

Add the dependency to spring-cloud-starter-zipkin - that way all dependent dependencies will be downloaded

3

To automatically configure rabbit, simply add the spring-rabbit dependency

2. Additional resources

Marcin Grzejszczak talking about Spring Cloud Sleuth and Zipkin

click here to see the video

3. Features

  • Adds trace and span ids to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator. Example logs:

    2016-02-02 15:30:57.902  INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
+
    1 
    We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself.
    2 
    Add the dependency to spring-cloud-starter-zipkin. That way, all nested dependencies get downloaded.
    3 
    To automatically configure RabbitMQ, add the spring-rabbit dependency.

2. Additional Resources

You can watch a video of Reshmi Krishna and Marcin Grzejszczak talking about Spring Cloud +Sleuth and Zipkin by clicking here.

You can check different setups of Sleuth and Brave in the openzipkin/sleuth-webmvc-example repository.

3. Features

  • Adds trace and span IDs to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator, as shown in the following example logs:

    2016-02-02 15:30:57.902  INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
 2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
-2016-02-02 15:31:01.936  INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ...

    notice the [appname,traceId,spanId,exportable] entries from the MDC:

    • spanId - the id of a specific operation that took place
    • appname - the name of the application that logged the span
    • traceId - the id of the latency graph that contains the span
    • exportable - whether the log should be exported to Zipkin or not. When would you like the span not to be -exportable? In the case in which you want to wrap some operation in a Span and have it written to the logs -only.
  • Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations, -key-value annotations. Loosely based on HTrace, but Zipkin (Dapper) compatible.

  • Sleuth records timing information to aid in latency analysis. Using sleuth, you can pinpoint causes of -latency in your applications. Sleuth is written to not log too much, and to not cause your production application to crash.

    • propagates structural data about your call-graph in-band, and the rest out-of-band.
    • includes opinionated instrumentation of layers such as HTTP
    • includes sampling policy to manage volume
    • can report to a Zipkin system for query and visualization
  • Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints, -rest template, scheduled actions, message channels, zuul filters, feign client).
  • Sleuth includes default logic to join a trace across http or messaging boundaries. For example, http propagation -works via Zipkin-compatible request headers. This propagation logic is defined and customized via -SpanInjector and SpanExtractor implementations.
  • Sleuth gives you the possibility to propagate context (also known as baggage) between processes. That means that if you set on a Span -a baggage element then it will be sent downstream either via HTTP or messaging to other processes.
  • Provides a way to create / continue spans and add tags and logs via annotations.
  • Provides simple metrics of accepted / dropped spans.

  • If spring-cloud-sleuth-zipkin then the app will generate and collect Zipkin-compatible traces. -By default it sends them via HTTP to a Zipkin server on localhost (port 9411). -Configure the location of the service using spring.zipkin.baseUrl.

    • If you depend on spring-rabbit or spring-kafka your app will send traces to a broker instead of http.
    • Note: spring-cloud-sleuth-stream is deprecated and should no longer be used.
[Important]Important

If using Zipkin, configure the percentage of spans exported using spring.sleuth.sampler.percentage -(default 0.1, i.e. 10%). Otherwise you might think that Sleuth is not working cause it’s omitting some spans.

[Note]Note

the SLF4J MDC is always set and logback users will immediately see the trace and span ids in logs per the example - above. Other logging systems have to configure their own formatter to get the same result. The default is - logging.pattern.level set to %5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}] - (this is a Spring Boot feature for logback users). - This means that if you’re not using SLF4J this pattern WILL NOT be automatically applied.

4. Sampling

In distributed tracing the data volumes can be very high so sampling -can be important (you usually don’t need to export all spans to get a -good picture of what is happening). Spring Cloud Sleuth has a -Sampler strategy that you can implement to take control of the -sampling algorithm. Samplers do not stop span (correlation) ids from -being generated, but they do prevent the tags and events being -attached and exported. By default you get a strategy that continues to -trace if a span is already active, but new ones are always marked as -non-exportable. If all your apps run with this sampler you will see -traces in logs, but not in any remote store. For testing the default -is often enough, and it probably is all you need if you are only using -the logs (e.g. with an ELK aggregator). If you are exporting span data -to Zipkin or Spring Cloud Stream, there is also an AlwaysSampler -that exports everything and a PercentageBasedSampler that samples a -fixed fraction of spans.

[Note]Note

the PercentageBasedSampler is the default if you are using -spring-cloud-sleuth-zipkin or spring-cloud-sleuth-stream. You can -configure the exports using spring.sleuth.sampler.percentage. The passed -value needs to be a double from 0.0 to 1.0 so it’s not a percentage. -For backwards compatibility reasons we’re not changing the property name.

A sampler can be installed just by creating a bean definition, e.g:

@Bean
+2016-02-02 15:31:01.936  INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ...

Notice the [appname,traceId,spanId,exportable] entries from the MDC:

  • spanId: The ID of a specific operation that took place.
  • appname: The name of the application that logged the span.
  • traceId: The ID of the latency graph that contains the span.
  • exportable: Whether the log should be exported to Zipkin. +When would you like the span not to be exportable? +When you want to wrap some operation in a Span and have it written to the logs only.
  • Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations, and key-value annotations. +Spring Cloud Sleuth is loosely based on HTrace but is compatible with Zipkin (Dapper).
  • Sleuth records timing information to aid in latency analysis. +By using sleuth, you can pinpoint causes of latency in your applications.

  • Sleuth is written to not log too much and to not cause your production application to crash. +To that end, Sleuth:

    • Propagates structural data about your call graph in-band and the rest out-of-band.
    • Includes opinionated instrumentation of layers such as HTTP.
    • Includes a sampling policy to manage volume.
    • Can report to a Zipkin system for query and visualization.
  • Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints, rest template, scheduled actions, message channels, Zuul filters, and Feign client).
  • Sleuth includes default logic to join a trace across HTTP or messaging boundaries. +For example, HTTP propagation works over Zipkin-compatible request headers.
  • Sleuth can propagate context (also known as baggage) between processes. +Consequently, if you set a baggage element on a Span, it is sent downstream to other processes over either HTTP or messaging.
  • Provides a way to create or continue spans and add tags and logs through annotations.

  • If spring-cloud-sleuth-zipkin is on the classpath, the app generates and collects Zipkin-compatible traces. +By default, it sends them over HTTP to a Zipkin server on localhost (port 9411). +You can configure the location of the service by setting spring.zipkin.baseUrl.

    • If you depend on spring-rabbit, your app sends traces to a RabbitMQ broker instead of HTTP.
    • If you depend on spring-kafka, and set spring.zipkin.sender.type: kafka, your app sends traces to a Kafka broker instead of HTTP.
    • [Caution]Caution

    spring-cloud-sleuth-stream is deprecated and should no longer be used.

    [Important]Important

    If you use Zipkin, configure the probability of spans exported by setting spring.sleuth.sampler.probability +(default: 0.1, which is 10 percent). Otherwise, you might think that Sleuth is not working be cause it omits some spans.

    [Note]Note

    The SLF4J MDC is always set and logback users immediately see the trace and span IDs in logs per the example +shown earlier. +Other logging systems have to configure their own formatter to get the same result. +The default is as follows: +logging.pattern.level set to %5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}] +(this is a Spring Boot feature for logback users). +If you do not use SLF4J, this pattern is NOT automatically applied.

    3.1 Introduction to Brave

    [Important]Important

    Starting with version 2.0.0, Spring Cloud Sleuth uses +Brave as the tracing library. +For your convenience, we embed part of the Brave’s docs here.

    [Important]Important

    In the vast majority of cases you need to just use the Tracer +or SpanCustomizer beans from Brave that Sleuth provides. The documentation below contains +a high overview of what Brave is and how it works.

    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.

    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).

    3.1.1 Tracing

    Most importantly, you need a brave.Tracer, configured to report to Zipkin.

    The following example setup sends trace data (spans) to Zipkin over HTTP (as opposed to Kafka):

    class MyClass {
+
+    private final Tracer tracer;
+
+    // Tracer will be autowired
+    MyClass(Tracer tracer) {
+        this.tracer = tracer;
+    }
+
+    void doSth() {
+        Span span = tracer.newTrace().name("encode").start();
+        // ...
+    }
+}
    [Important]Important

    If your span contains a name longer than 50 chars, then that name is truncated to 50 chars. +Your names have to be explicit and concrete. +Big names lead to latency issues and sometimes even thrown exceptions.

    The tracer creates and joins spans that model the latency of potentially distributed work. +It can employ sampling to reduce overhead during the process, to reduce the amount of data sent to Zipkin, or both.

    Spans returned by a tracer report data to Zipkin when finished or do nothing if unsampled. +After starting a span, you can annotate events of interest or add tags containing details or lookup keys.

    Spans have a context that includes trace identifiers that place the span at the correct spot in the tree representing the distributed operation.

    3.1.2 Local Tracing

    When tracing local code, you can run it inside a span, as shown in the following example:

    @Autowired Tracer tracer;
+
+Span span = tracer.newTrace().name("encode").start();
+try {
+  doSomethingExpensive();
+} finally {
+  span.finish();
+}

    In the preceding example, the span is the root of the trace. +In many cases, the span is part of an existing trace. +When this is the case, call newChild instead of newTrace, as shown in the following example:

    @Autowired Tracer tracer;
+
+Span span = tracer.newChild(root.context()).name("encode").start();
+try {
+  doSomethingExpensive();
+} finally {
+  span.finish();
+}

    3.1.3 Customizing Spans

    Once you have a span, you can add tags to it. +The tags can be used as lookup keys or details. +For example, you might add a tag with your runtime version, as shown in the following example:

    span.tag("clnt/finagle.version", "6.36.0");

    When exposing the ability to customize spans to third parties, prefer brave.SpanCustomizer as opposed to brave.Span. +The former is simpler to understand and test and does not tempt users with span lifecycle hooks.

    interface MyTraceCallback {
+  void request(Request request, SpanCustomizer customizer);
+}

    Since brave.Span implements brave.SpanCustomizer, you can pass it to users, as shown in the following example:

    for (MyTraceCallback callback : userCallbacks) {
+  callback.request(request, span);
+}

    3.1.4 Implicitly Looking up the Current Span

    Sometimes, you do not know if a trace is in progress or not, and you do not want users to do null checks. +brave.CurrentSpanCustomizer handles this problem by adding data to any span that’s in progress or drops, as shown in the following example:

    Ex.

    // The user code can then inject this without a chance of it being null.
+@Autowired SpanCustomizer span;
+
+void userCode() {
+  span.annotate("tx.started");
+  ...
+}

    3.1.5 RPC tracing

    [Tip]Tip

    Check for instrumentation written here and Zipkin’s list before rolling your own RPC instrumentation.

    RPC tracing is often done automatically by interceptors. Behind the scenes, they add tags and events that relate to their role in an RPC operation.

    The following example shows how to add a client span:

    @Autowired Tracer tracer;
+
+// before you send a request, add metadata that describes the operation
+span = tracer.newTrace().name("get").type(CLIENT);
+span.tag("clnt/finagle.version", "6.36.0");
+span.tag(TraceKeys.HTTP_PATH, "/api");
+span.remoteEndpoint(Endpoint.builder()
+    .serviceName("backend")
+    .ipv4(127 << 24 | 1)
+    .port(8080).build());
+
+// when the request is scheduled, start the span
+span.start();
+
+// if you have callbacks for when data is on the wire, note those events
+span.annotate(Constants.WIRE_SEND);
+span.annotate(Constants.WIRE_RECV);
+
+// when the response is complete, finish the span
+span.finish();

    One-Way tracing

    Sometimes, you need to model an asynchronous operation where there is a +request but no response. In normal RPC tracing, you use span.finish() +to indicate that the response was received. In one-way tracing, you use +span.flush() instead, as you do not expect a response.

    The following example shows how a client might model a one-way operation:

    @Autowired Tracer tracer;
+
+// start a new span representing a client request
+oneWaySend = tracer.newSpan(parent).kind(Span.Kind.CLIENT);
+
+// Add the trace context to the request, so it can be propagated in-band
+tracing.propagation().injector(Request::addHeader)
+                     .inject(oneWaySend.context(), request);
+
+// fire off the request asynchronously, totally dropping any response
+request.execute();
+
+// start the client side and flush instead of finish
+oneWaySend.start().flush();

    The following example shows how a server might handle a one-way operation:

    @Autowired Tracing tracing;
+@Autowired Tracer tracer;
+
+// pull the context out of the incoming request
+extractor = tracing.propagation().extractor(Request::getHeader);
+
+// convert that context to a span which you can name and add tags to
+oneWayReceive = nextSpan(tracer, extractor.extract(request))
+    .name("process-request")
+    .kind(SERVER)
+    ... add tags etc.
+
+// start the server side and flush instead of finish
+oneWayReceive.start().flush();
+
+// you should not modify this span anymore as it is complete. However,
+// you can create children to represent follow-up work.
+next = tracer.newSpan(oneWayReceive.context()).name("step2").start();

    4. Sampling

    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).

    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.

    By default, a global sampler applies a single rate to all traced operations. +Tracer.Builder.sampler controls this setting, and it defaults to tracing every request.

    4.1 Declarative sampling

    Some applications need to sample based on the type or annotations of a java method.

    Most users use a framework interceptor to automate this sort of policy. +The following example shows how that might work internally:

    @Autowired Tracing tracing;
+
+// derives a sample rate from an annotation on a java method
+DeclarativeSampler<Traced> sampler = DeclarativeSampler.create(Traced::sampleRate);
+
+@Around("@annotation(traced)")
+public Object traceThing(ProceedingJoinPoint pjp, Traced traced) throws Throwable {
+  Span span = tracing.tracer().newTrace(sampler.sample(traced))...
+  try {
+    return pjp.proceed();
+  } finally {
+    span.finish();
+  }
+}

    4.2 Custom sampling

    Depending on what the operation is, you may want to apply different policies. +For example, you might not want to trace requests to static resources such as images, or you might want to trace all requests to a new api.

    Most users use a framework interceptor to automate this sort of policy. +The following example shows how that might work internally:

    @Autowired Tracer tracer;
+
+Span newTrace(Request input) {
+  SamplingFlags flags = SamplingFlags.NONE;
+  if (input.url().startsWith("/experimental")) {
+    flags = SamplingFlags.SAMPLED;
+  } else if (input.url().startsWith("/static")) {
+    flags = SamplingFlags.NOT_SAMPLED;
+  }
+  return tracer.newTrace(flags);
+}

    4.3 Sampling in Spring Cloud Sleuth

    By default Spring Cloud Sleuth sets all spans to non-exportable. +That means that traces appear in logs but not in any remote store. +For testing the default is often enough, and it probably is all you need if you use only the logs (for example, with an ELK aggregator). +If you export span data to Zipkin, there is also an Sampler.ALWAYS_SAMPLE setting that exports everything and a ProbabilityBasedSampler setting that samples a fixed fraction of spans.

    [Note]Note

    The ProbabilityBasedSampler is the default if you use spring-cloud-sleuth-zipkin. +You can configure the exports by setting spring.sleuth.sampler.probability. +The passed value needs to be a double from 0.0 to 1.0.

    A sampler can be installed by creating a bean definition, as shown in the following example:

    @Bean
 public Sampler defaultSampler() {
-	return new AlwaysSampler();
-}
    [Tip]Tip

    You can set the HTTP header X-B3-Flags to 1 or when doing messaging you can -set spanFlags header to 1. Then the current span will be forced to be exportable -regardless of the sampling decision.

    5. Instrumentation

    Spring Cloud Sleuth instruments all your Spring application -automatically, so you shouldn’t have to do anything to activate -it. The instrumentation is added using a variety of technologies -according to the stack that is available, e.g. for a servlet web -application we use a Filter, and for Spring Integration we use -ChannelInterceptors.

    You can customize the keys used in span tags. To limit the volume of -span data, by default an HTTP request will be tagged only with a -handful of metadata like the status code, host and URL. You can add -request headers by configuring spring.sleuth.keys.http.headers (a -list of header names).

    [Note]Note

    Remember that tags are only collected and exported if there is a -Sampler that allows it (by default there is not, so there is no -danger of accidentally collecting too much data without configuring -something).

    [Note]Note

    Currently the instrumentation in Spring Cloud Sleuth is eager - it means that -we’re actively trying to pass the tracing context between threads. Also timing events -are captured even when sleuth isn’t exporting data to a tracing system. -This approach may change in the future towards being lazy on this matter.

    6. Span lifecycle

    You can do the following operations on the Span by means of org.springframework.cloud.sleuth.Tracer interface:

    • start - when you start a span its name is assigned and start timestamp is recorded.
    • close - the span gets finished (the end time of the span is recorded) and if -the span is exportable then it will be eligible for collection to Zipkin. -The span is also removed from the current thread.
    • continue - a new instance of span will be created whereas it will be a copy of the -one that it continues.
    • detach - the span doesn’t get stopped or closed. It only gets removed from the current thread.
    • create with explicit parent - you can create a new span and set an explicit parent to it
    [Tip]Tip

    Spring creates the instance of Tracer for you. In order to use it all you need is to just autowire it.

    6.1 Creating and closing spans

    You can manually create spans by using the Tracer interface.

    // Start a span. If there was a span present in this thread it will become
+	return Sampler.ALWAYS_SAMPLE;
+}
    [Tip]Tip

    You can set the HTTP header X-B3-Flags to 1, or, when doing messaging, you can set the spanFlags header to 1. +Doing so forces the current span to be exportable regardless of the sampling decision.

    5. Propagation

    Propagation is needed to ensure activities originating from the same root are collected together in the same trace. +The most common propagation approach is to copy a trace context from a client by sending an RPC request to a server receiving it.

    For example, when a downstream HTTP call is made, its trace context is encoded as request headers and sent along with it, as shown in the following image:

       Client Span                                                Server Span
+┌──────────────────┐                                       ┌──────────────────┐
+│                  │                                       │                  │
+│   TraceContext   │           Http Request Headers        │   TraceContext   │
+│ ┌──────────────┐ │          ┌───────────────────┐        │ ┌──────────────┐ │
+│ │ TraceId      │ │          │ X─B3─TraceId      │        │ │ TraceId      │ │
+│ │              │ │          │                   │        │ │              │ │
+│ │ ParentSpanId │ │ Extract  │ X─B3─ParentSpanId │ Inject │ │ ParentSpanId │ │
+│ │              ├─┼─────────>│                   ├────────┼>│              │ │
+│ │ SpanId       │ │          │ X─B3─SpanId       │        │ │ SpanId       │ │
+│ │              │ │          │                   │        │ │              │ │
+│ │ Sampled      │ │          │ X─B3─Sampled      │        │ │ Sampled      │ │
+│ └──────────────┘ │          └───────────────────┘        │ └──────────────┘ │
+│                  │                                       │                  │
+└──────────────────┘                                       └──────────────────┘

    The names above are from B3 Propagation, which is built-in to Brave and has implementations in many languages and frameworks.

    Most users use a framework interceptor to automate propagation. +The next two examples show how that might work for a client and a server.

    The following example shows how client-side propagation might work:

    @Autowired Tracing tracing;
+
+// configure a function that injects a trace context into a request
+injector = tracing.propagation().injector(Request.Builder::addHeader);
+
+// before a request is sent, add the current span's context to it
+injector.inject(span.context(), request);

    The following example shows how server-side propagation might work:

    @Autowired Tracing tracing;
+@Autowired Tracer tracer;
+
+// configure a function that extracts the trace context from a request
+extractor = tracing.propagation().extractor(Request::getHeader);
+
+// when a server receives a request, it joins or starts a new trace
+span = tracer.nextSpan(extractor.extract(request));

    5.1 Propagating extra fields

    Sometimes you need to propagate extra fields, such as a request ID or an alternate trace context. +For example, if you are in a Cloud Foundry environment, you might want to pass the request ID, as shown in the following example:

    // when you initialize the builder, define the extra field you want to propagate
+Tracing.newBuilder().propagationFactory(
+  ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-vcap-request-id")
+);
+
+// later, you can tag that request ID or use it in log correlation
+requestId = ExtraFieldPropagation.get("x-vcap-request-id");

    You may also need to propagate a trace context that you are not using. +For example, you may be in an Amazon Web Services environment but not be reporting data to X-Ray. +To ensure X-Ray can co-exist correctly, pass-through its tracing header, as shown in the following example:

    tracingBuilder.propagationFactory(
+  ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-amzn-trace-id")
+);
    [Tip]Tip

    In Spring Cloud Sleuth all elements of the tracing builder Tracing.newBuilder() +are defined as beans. So if you want to pass a custom PropagationFactory, it’s enough +for you to create a bean of that type and we will set it in the Tracing bean.

    5.1.1 Prefixed fields

    If they follow a common pattern, you can also prefix fields. +The following example shows how to propagate x-vcap-request-id the field as-is but send the country-code and user-id fields on the wire as x-baggage-country-code and x-baggage-user-id, respectively:

    Tracing.newBuilder().propagationFactory(
+  ExtraFieldPropagation.newFactoryBuilder(B3Propagation.FACTORY)
+                       .addField("x-vcap-request-id")
+                       .addPrefixedFields("baggage-", Arrays.asList("country-code", "user-id"))
+                       .build()
+);

    Later, you can call the following code to affect the country code of the current trace context:

    ExtraFieldPropagation.set("country-code", "FO");
+String countryCode = ExtraFieldPropagation.get("country-code");

    Alternatively, if you have a reference to a trace context, you can use it explicitly, as shown in the following example:

    ExtraFieldPropagation.set(span.context(), "country-code", "FO");
+String countryCode = ExtraFieldPropagation.get(span.context(), "country-code");
    [Important]Important

    A difference from previous versions of Sleuth is that, with Brave, you must pass the list of baggage keys. +There are two properties to achieve this. +With the spring.sleuth.baggage-keys, you set keys that get prefixed with baggage- for HTTP calls and baggage_ for messaging. +You can also use the spring.sleuth.propagation-keys property to pass a list of prefixed keys that are whitelisted without any prefix.

    5.1.2 Extracting a Propagated Context

    The TraceContext.Extractor<C> reads trace identifiers and sampling status from an incoming request or message. +The carrier is usually a request object or headers.

    This utility is used in standard instrumentation (such as HttpServerHandler`) but can also be used for custom RPC or messaging code.

    TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are +sharing span IDs between a client and a server.

    5.1.3 Sharing span IDs between Client and Server

    A normal instrumentation pattern is to create a span representing the server side of an RPC. +Extractor.extract might return a complete trace context when applied to an incoming client request. +Tracer.joinSpan attempts to continue this trace, using the same span ID if supported or creating a child span +if not. When the span ID is shared, the reported data includes a flag saying so.

    The following image shows an example of B3 propagation:

                                  ┌───────────────────┐      ┌───────────────────┐
+ Incoming Headers             │   TraceContext    │      │   TraceContext    │
+┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │
+│ X─B3-TraceId      │─────────┼─┼> TraceId      │ │──────┼─┼> TraceId      │ │
+│                   │         │ │               │ │      │ │               │ │
+│ X─B3-ParentSpanId │─────────┼─┼> ParentSpanId │ │──────┼─┼> ParentSpanId │ │
+│                   │         │ │               │ │      │ │               │ │
+│ X─B3-SpanId       │─────────┼─┼> SpanId       │ │──────┼─┼> SpanId       │ │
+└───────────────────┘         │ │               │ │      │ │               │ │
+                              │ │               │ │      │ │  Shared: true │ │
+                              │ └───────────────┘ │      │ └───────────────┘ │
+                              └───────────────────┘      └───────────────────┘

    Some propagation systems forward only the parent span ID, detected when Propagation.Factory.supportsJoin() == false. +In this case, a new span ID is always provisioned, and the incoming context determines the parent ID.

    The following image shows an example of AWS propagation:

                                  ┌───────────────────┐      ┌───────────────────┐
+ x-amzn-trace-id              │   TraceContext    │      │   TraceContext    │
+┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │
+│ Root              │─────────┼─┼> TraceId      │ │──────┼─┼> TraceId      │ │
+│                   │         │ │               │ │      │ │               │ │
+│ Parent            │─────────┼─┼> SpanId       │ │──────┼─┼> ParentSpanId │ │
+└───────────────────┘         │ └───────────────┘ │      │ │               │ │
+                              └───────────────────┘      │ │  SpanId: New  │ │
+                                                         │ └───────────────┘ │
+                                                         └───────────────────┘

    Note: Some span reporters do not support sharing span IDs. +For example, if you set Tracing.Builder.spanReporter(amazonXrayOrGoogleStackdrive), you should disable join by setting Tracing.Builder.supportsJoin(false). +Doing so forces a new child span on Tracer.joinSpan().

    5.1.4 Implementing Propagation

    TraceContext.Extractor<C> is implemented by a Propagation.Factory plugin. +Internally, this code creates the union type, TraceContextOrSamplingFlags, with one of the following: +* TraceContext if trace and span IDs were present. +* TraceIdContext if a trace ID was present but span IDs were not present. +* SamplingFlags if no identifiers were present.

    Some Propagation implementations carry extra data from the point of extraction (for example, reading incoming headers) to injection (for example, writing outgoing headers). +For example, it might carry a request ID. +When implementations have extra data, they handle it as follows: +* If a TraceContext were extracted, add the extra data as TraceContext.extra(). +* Otherwise, add it as TraceContextOrSamplingFlags.extra(), which Tracer.nextSpan handles.

    6. Current Tracing Component

    Brave supports a "current tracing component" concept, which should only be used when you have no other way to get a reference. +This was made for JDBC connections, as they often initialize prior to the tracing component.

    The most recent tracing component instantiated is available through Tracing.current(). +You can also use Tracing.currentTracer() to get only the tracer. +If you use either of these methods, do not cache the result. +Instead, look them up each time you need them.

    7. Current Span

    Brave supports a "current span" concept which represents the in-flight operation. +You can use Tracer.currentSpan() to add custom tags to a span and Tracer.nextSpan() to create a child of whatever is in-flight.

    [Important]Important

    In Sleuth, you can autowire the Tracer bean to retrieve the current span via +tracer.currentSpan() method. To retrieve the current context just call +tracer.currentSpan().context(). To get the current trace id as String +you can use the traceIdString() method like this: tracer.currentSpan().context().traceIdString().

    7.1 Setting a span in scope manually

    When writing new instrumentation, it is important to place a span you created in scope as the current span. +Not only does doing so let users access it with Tracer.currentSpan(), but it also allows customizations such as SLF4J MDC to see the current trace IDs.

    Tracer.withSpanInScope(Span) facilitates this and is most conveniently employed by using the try-with-resources idiom. +Whenever external code might be invoked (such as proceeding an interceptor or otherwise), place the span in scope, as shown in the following example:

    @Autowired Tracer tracer;
+
+try (SpanInScope ws = tracer.withSpanInScope(span)) {
+  return inboundRequest.invoke();
+} finally { // note the scope is independent of the span
+  span.finish();
+}

    In edge cases, you may need to clear the current span temporarily (for example, launching a task that should not be associated with the current request). To do tso, pass null to withSpanInScope, as shown in the following example:

    @Autowired Tracer tracer;
+
+try (SpanInScope cleared = tracer.withSpanInScope(null)) {
+  startBackgroundThread();
+}

    8. Instrumentation

    Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it. +The instrumentation is added by using a variety of technologies according to the stack that is available. For example, for a servlet web application, we use a Filter, and, for Spring Integration, we use ChannelInterceptors.

    You can customize the keys used in span tags. +To limit the volume of span data, an HTTP request is, by default, tagged only with a handful of metadata, such as the status code, the host, and the URL. +You can add request headers by configuring spring.sleuth.keys.http.headers (a list of header names).

    [Note]Note

    Tags are collected and exported only if there is a Sampler that allows it. By default, there is no such Sampler, to ensure that there is no danger of accidentally collecting too much data without configuring something).

    9. Span lifecycle

    You can do the following operations on the Span by means of brave.Tracer:

    • start: When you start a span, its name is assigned and the start timestamp is recorded.
    • close: The span gets finished (the end time of the span is recorded) and, if the span is sampled, it is eligible for collection (for example, to Zipkin).
    • continue: A new instance of span is created. +It is a copy of the one that it continues.
    • detach: The span does not get stopped or closed. +It only gets removed from the current thread.
    • create with explicit parent: You can create a new span and set an explicit parent for it.
    [Tip]Tip

    Spring Cloud Sleuth creates an instance of Tracer for you. In order to use it, you can autowire it.

    9.1 Creating and finishing spans

    You can manually create spans by using the Tracer, as shown in the following example:

    // Start a span. If there was a span present in this thread it will become
 // the `newSpan`'s parent.
-Span newSpan = this.tracer.createSpan("calculateTax");
-try {
+Span newSpan = this.tracer.nextSpan().name("calculateTax");
+try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(newSpan.start())) {
 	// ...
 	// You can tag a span
-	this.tracer.addTag("taxValue", taxValue);
+	newSpan.tag("taxValue", taxValue);
 	// ...
 	// You can log an event on a span
-	newSpan.logEvent("taxCalculated");
+	newSpan.annotate("taxCalculated");
 } finally {
-	// Once done remember to close the span. This will allow collecting
+	// Once done remember to finish the span. This will allow collecting
 	// the span to send it to Zipkin
-	this.tracer.close(newSpan);
-}

    In this example we could see how to create a new instance of span. Assuming that there already -was a span present in this thread then it would become the parent of that span.

    [Important]Important

    Always clean after you create a span! Don’t forget to close a span if you want to send it to Zipkin.

    [Important]Important

    If your span contains a name greater than 50 chars, then that name will -be truncated to 50 chars. Your names have to be explicit and concrete. Big names lead to -latency issues and sometimes even thrown exceptions.

    6.2 Continuing spans

    Sometimes you don’t want to create a new span but you want to continue one. Example of such a -situation might be (of course it all depends on the use-case):

    • AOP - If there was already a span created before an aspect was reached then you might not want to create a new span.
    • Hystrix - executing a Hystrix command is most likely a logical part of the current processing. It’s in fact -only a technical implementation detail that you wouldn’t necessarily want to reflect in tracing as a separate being.

    The continued instance of span is equal to the one that it continues:

    Span continuedSpan = this.tracer.continueSpan(spanToContinue);
-assertThat(continuedSpan).isEqualTo(spanToContinue);

    To continue a span you can use the Tracer interface.

    // let's assume that we're in a thread Y and we've received
+	newSpan.finish();
+}

    In the preceding example, we could see how to create a new instance of the span. +If there is already a span in this thread, it becomes the parent of the new span.

    [Important]Important

    Always clean after you create a span. Also, always finish any span that you want to send to Zipkin.

    [Important]Important

    If your span contains a name greater than 50 chars, that name is truncated to 50 chars. +Your names have to be explicit and concrete. Big names lead to latency issues and sometimes even exceptions.

    9.2 Continuing Spans

    Sometimes, you do not want to create a new span but you want to continue one. An example of such a +situation might be as follows:

    • AOP: If there was already a span created before an aspect was reached, you might not want to create a new span.
    • Hystrix: Executing a Hystrix command is most likely a logical part of the current processing. +It is in fact merely a technical implementation detail that you would not necessarily want to reflect in tracing as a separate being.

    To continue a span, you can use brave.Tracer, as shown in the following example:

    // let's assume that we're in a thread Y and we've received
 // the `initialSpan` from thread X
-Span continuedSpan = this.tracer.continueSpan(initialSpan);
+Span continuedSpan = this.tracer.toSpan(newSpan.context());
 try {
 	// ...
 	// You can tag a span
-	this.tracer.addTag("taxValue", taxValue);
+	continuedSpan.tag("taxValue", taxValue);
 	// ...
 	// You can log an event on a span
-	continuedSpan.logEvent("taxCalculated");
+	continuedSpan.annotate("taxCalculated");
 } finally {
-	// Once done remember to detach the span. That way you'll
-	// safely remove it from the current thread without closing it
-	this.tracer.detach(continuedSpan);
-}
    [Important]Important

    Always clean after you create a span! Don’t forget to detach a span if some work was done started in one - thread (e.g. thread X) and it’s waiting for other threads (e.g. Y, Z) to finish. - Then the spans in the threads Y, Z should be detached at the end of their work. When the results are collected - the span in thread X should be closed.

    6.3 Creating spans with an explicit parent

    There is a possibility that you want to start a new span and provide an explicit parent of that span. -Let’s assume that the parent of a span is in one thread and you want to start a new span in another thread. The -startSpan method of the Tracer interface is the method you are looking for.

    // let's assume that we're in a thread Y and we've received
+	// Once done remember to flush the span. That means that
+	// it will get reported but the span itself is not yet finished
+	continuedSpan.flush();
+}

    9.3 Creating a Span with an explicit Parent

    You might want to start a new span and provide an explicit parent of that span. +Assume that the parent of a span is in one thread and you want to start a new span in another thread. +In Brave, whenever you call nextSpan(), it creates a span in reference to the span that is currently in scope. +You can put the span in scope and then call nextSpan(), as shown in the following example:

    // let's assume that we're in a thread Y and we've received
 // the `initialSpan` from thread X. `initialSpan` will be the parent
 // of the `newSpan`
-Span newSpan = this.tracer.createSpan("calculateCommission", initialSpan);
-try {
+Span newSpan = null;
+try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(initialSpan)) {
+	newSpan = this.tracer.nextSpan().name("calculateCommission");
 	// ...
 	// You can tag a span
-	this.tracer.addTag("commissionValue", commissionValue);
+	newSpan.tag("commissionValue", commissionValue);
 	// ...
 	// You can log an event on a span
-	newSpan.logEvent("commissionCalculated");
+	newSpan.annotate("commissionCalculated");
 } finally {
-	// Once done remember to close the span. This will allow collecting
+	// Once done remember to finish the span. This will allow collecting
 	// the span to send it to Zipkin. The tags and events set on the
 	// newSpan will not be present on the parent
-	this.tracer.close(newSpan);
-}
    [Important]Important

    After having created such a span remember to close it. Otherwise you will see a lot of warnings in your logs - related to the fact that you have a span present in the current thread other than the one you’re trying to close. - What’s worse your spans won’t get closed properly thus will not get collected to Zipkin.

    7. Naming spans

    Picking a span name is not a trivial task. Span name should depict an operation name. The name should -be low cardinality (e.g. not include identifiers).

    Since there is a lot of instrumentation going on some of the span names will be -artificial like:

    • controller-method-name when received by a Controller with a method name conrollerMethodName
    • async for asynchronous operations done via wrapped Callable and Runnable.
    • @Scheduled annotated methods will return the simple name of the class.

    Fortunately, for the asynchronous processing you can provide explicit naming.

    7.1 @SpanName annotation

    You can name the span explicitly via the @SpanName annotation.

    @SpanName("calculateTax")
+	if (newSpan != null) {
+		newSpan.finish();
+	}
+}
    [Important]Important

    After creating such a span, you must finish it. Otherwise it is not reported (for example, to Zipkin).

    10. Naming spans

    Picking a span name is not a trivial task. A span name should depict an operation name. +The name should be low cardinality, so it should not include identifiers.

    Since there is a lot of instrumentation going on, some span names are artificial:

    • controller-method-name when received by a Controller with a method name of controllerMethodName
    • async for asynchronous operations done with wrapped Callable and Runnable interfaces.
    • Methods annotated with @Scheduled return the simple name of the class.

    Fortunately, for asynchronous processing, you can provide explicit naming.

    10.1 @SpanName Annotation

    You can name the span explicitly by using the @SpanName annotation, as shown in the following example:

    @SpanName("calculateTax")
 class TaxCountingRunnable implements Runnable {
 
 	@Override public void run() {
 		// perform logic
 	}
-}

    In this case, when processed in the following manner:

    Runnable runnable = new TraceRunnable(tracer, spanNamer, new TaxCountingRunnable());
+}

    In this case, when processed in the following manner, the span is named calculateTax:

    Runnable runnable = new TraceRunnable(tracing, spanNamer,
+		new TaxCountingRunnable());
 Future<?> future = executorService.submit(runnable);
 // ... some additional logic ...
-future.get();

    The span will be named calculateTax.

    7.2 toString() method

    It’s pretty rare to create separate classes for Runnable or Callable. Typically one creates an anonymous -instance of those classes. You can’t annotate such classes thus to override that, if there is no @SpanName annotation present, -we’re checking if the class has a custom implementation of the toString() method.

    So executing such code:

    Runnable runnable = new TraceRunnable(tracer, spanNamer, new Runnable() {
+future.get();

    10.2 toString() method

    It is pretty rare to create separate classes for Runnable or Callable. +Typically, one creates an anonymous instance of those classes. +You cannot annotate such classes. +To overcome that limitation, if there is no @SpanName annotation present, we check whether the class has a custom implementation of the toString() method.

    Running such code leads to creating a span named calculateTax, as shown in the following example:

    Runnable runnable = new TraceRunnable(tracing, spanNamer, new Runnable() {
 	@Override public void run() {
 		// perform logic
 	}
@@ -373,228 +597,144 @@ we’re checking if the class has a custom implementation of the // ... some additional logic ...
-future.get();

    will lead in creating a span named calculateTax.

    8. Managing spans with annotations

    8.1 Rationale

    The main arguments for this features are

    • api-agnostic means to collaborate with a span

      • use of annotations allows users to add to a span with no library dependency on a span api. -This allows Sleuth to change its core api less impact to user code.

    • reduced surface area for basic span operations.

      • without this feature one has to use the span api, which has lifecycle commands that -could be used incorrectly. By only exposing scope, tag and log functionality, users can -collaborate without accidentally breaking span lifecycle.

    • collaboration with runtime generated code

      • with libraries such as Spring Data / Feign the implementations of interfaces are generated -at runtime thus span wrapping of objects was tedious. Now you can provide annotations - over interfaces and arguments of those interfaces

    8.2 Creating new spans

    If you really don’t want to take care of creating local spans manually you can profit from the -@NewSpan annotation. Also we give you the @SpanTag annotation to add tags in an automated -fashion.

    Let’s look at some examples of usage.

    @NewSpan
-void testMethod();

    Annotating the method without any parameter will lead to a creation of a new span whose name -will be equal to annotated method name.

    @NewSpan("customNameOnTestMethod4")
-void testMethod4();

    If you provide the value in the annotation (either directly or via the name parameter) then -the created span will have the name as the provided value.

    // method declaration
+future.get();

    11. Managing Spans with Annotations

    You can manage spans with a variety of annotations.

    11.1 Rationale

    There are a number of good reasons to manage spans with annotations, including:

    • API-agnostic means to collaborate with a span. Use of annotations lets users add to a span with no library dependency on a span api. +Doing so lets Sleuth change its core API to create less impact to user code.
    • Reduced surface area for basic span operations. Without this feature, you must use the span api, which has lifecycle commands that could be used incorrectly. +By only exposing scope, tag, and log functionality, you can collaborate without accidentally breaking span lifecycle.
    • Collaboration with runtime generated code. With libraries such as Spring Data and Feign, the implementations of interfaces are generated at runtime. +Consequently, span wrapping of objects was tedious. +Now you can provide annotations over interfaces and the arguments of those interfaces.

    11.2 Creating New Spans

    If you do not want to create local spans manually, you can use the @NewSpan annotation. +Also, we provide the @SpanTag annotation to add tags in an automated fashion.

    Now we can consider some examples of usage.

    @NewSpan
+void testMethod();

    Annotating the method without any parameter leads to creating a new span whose name equals the annotated method name.

    @NewSpan("customNameOnTestMethod4")
+void testMethod4();

    If you provide the value in the annotation (either directly or by setting the name parameter), the created span has the provided value as the name.

    // method declaration
 @NewSpan(name = "customNameOnTestMethod5")
 void testMethod5(@SpanTag("testTag") String param);
 
 // and method execution
-this.testBean.testMethod5("test");

    You can combine both the name and a tag. Let’s focus on the latter. In this case whatever the value of -the annotated method’s parameter runtime value will be - that will be the value of the tag. In our sample -the tag key will be testTag and the tag value will be test.

    @NewSpan(name = "customNameOnTestMethod3")
+this.testBean.testMethod5("test");

    You can combine both the name and a tag. Let’s focus on the latter. +In this case, the value of the annotated method’s parameter runtime value becomes the value of the tag. +In our sample, the tag key is testTag, and the tag value is test.

    @NewSpan(name = "customNameOnTestMethod3")
 @Override
 public void testMethod3() {
-}

    You can place the @NewSpan annotation on both the class and an interface. If you override the -interface’s method and provide a different value of the @NewSpan annotation then the most -concrete one wins (in this case customNameOnTestMethod3 will be set).

    8.3 Continuing spans

    If you want to just add tags and annotations to an existing span it’s enough -to use the @ContinueSpan annotation as presented below. Note that in contrast -with the @NewSpan annotation you can also add logs via the log parameter:

    // method declaration
+}

    You can place the @NewSpan annotation on both the class and an interface. +If you override the interface’s method and provide a different value for the @NewSpan annotation, the most +concrete one wins (in this case customNameOnTestMethod3 is set).

    11.3 Continuing Spans

    If you want to add tags and annotations to an existing span, you can use the @ContinueSpan annotation, as shown in the following example:

    // method declaration
 @ContinueSpan(log = "testMethod11")
 void testMethod11(@SpanTag("testTag11") String param);
 
 // method execution
-this.testBean.testMethod11("test");

    That way the span will get continued and:

    • logs with name testMethod11.before and testMethod11.after will be created
    • if an exception will be thrown a log testMethod11.afterFailure will also be created
    • tag with key testTag11 and value test will be created

    8.4 More advanced tag setting

    There are 3 different ways to add tags to a span. All of them are controlled by the SpanTag annotation. -Precedence is:

    • try with the bean of TagValueResolver type and provided name
    • if one hasn’t provided the bean name, try to evaluate an expression. We’re searching for a TagValueExpressionResolver bean. -The default implementation uses SPEL expression resolution.
    • if one hasn’t provided any expression to evaluate just return a toString() value of the parameter

    8.4.1 Custom extractor

    The value of the tag for following method will be computed by an implementation of TagValueResolver interface. -Its class name has to be passed as the value of the resolver attribute.

    Having such an annotated method:

    @NewSpan
+this.testBean.testMethod11("test");
+this.testBean.testMethod13();

    (Note that, in contrast with the @NewSpan annotation ,you can also add logs with the log parameter.)

    That way, the span gets continued and:

    • Log entries named testMethod11.before and testMethod11.after are created.
    • If an exception is thrown, a log entry named testMethod11.afterFailure is also created.
    • A tag with a key of testTag11 and a value of test is created.

    11.4 Advanced Tag Setting

    There are 3 different ways to add tags to a span. All of them are controlled by the SpanTag annotation. +The precedence is as follows:

    1. Try with a bean of TagValueResolver type and a provided name.
    2. If the bean name has not been provided, try to evaluate an expression. +We search for a TagValueExpressionResolver bean. +The default implementation uses SPEL expression resolution. +IMPORTANT You can only reference properties from the SPEL expression. Method execution is not allowed due to security constraints.
    3. If we do not find any expression to evaluate, return the toString() value of the parameter.

    11.4.1 Custom extractor

    The value of the tag for the following method is computed by an implementation of TagValueResolver interface. +Its class name has to be passed as the value of the resolver attribute.

    Consider the following annotated method:

    @NewSpan
 public void getAnnotationForTagValueResolver(@SpanTag(key = "test", resolver = TagValueResolver.class) String test) {
-}

    and such a TagValueResolver bean implementation

    @Bean(name = "myCustomTagValueResolver")
+}

    Now further consider the following TagValueResolver bean implementation:

    @Bean(name = "myCustomTagValueResolver")
 public TagValueResolver tagValueResolver() {
 	return parameter -> "Value from myCustomTagValueResolver";
-}

    Will lead to setting of a tag value equal to Value from myCustomTagValueResolver.

    8.4.2 Resolving expressions for value

    Having such an annotated method:

    @NewSpan
-public void getAnnotationForTagValueExpression(@SpanTag(key = "test", expression = "length() + ' characters'") String test) {
-}

    and no custom implementation of a TagValueExpressionResolver will lead to evaluation of the SPEL expression and a tag with value 4 characters will be set on the span. -If you want to use some other expression resolution mechanism you can create your own implementation -of the bean.

    8.4.3 Using toString method

    Having such an annotated method:

    @NewSpan
+}

    The two preceding examples lead to setting a tag value equal to Value from myCustomTagValueResolver.

    11.4.2 Resolving Expressions for a Value

    Consider the following annotated method:

    @NewSpan
+public void getAnnotationForTagValueExpression(@SpanTag(key = "test", expression = "'hello' + ' characters'") String test) {
+}

    No custom implementation of a TagValueExpressionResolver leads to evaluation of the SPEL expression, and a tag with a value of 4 characters is set on the span. +If you want to use some other expression resolution mechanism, you can create your own implementation of the bean.

    11.4.3 Using the toString() method

    Consider the following annotated method:

    @NewSpan
 public void getAnnotationForArgumentToString(@SpanTag("test") Long param) {
-}

    if executed with a value of 15 will lead to setting of a tag with a String value of "15".

    9. Customizations

    Thanks to the SpanInjector and SpanExtractor you can customize the way spans -are created and propagated.

    There are currently two built-in ways to pass tracing information between processes:

    • via Spring Integration
    • via HTTP

    Span ids are extracted from Zipkin-compatible (B3) headers (either Message -or HTTP headers), to start or join an existing trace. Trace information is -injected into any outbound requests so the next hop can extract them.

    The key change in comparison to the previous versions of Sleuth is that Sleuth is implementing -the Open Tracing’s TextMap notion. In Sleuth it’s called SpanTextMap. Basically the idea -is that any means of communication (e.g. message, http request, etc.) can be abstracted via -a SpanTextMap. This abstraction defines how one can insert data into the carrier and -how to retrieve it from there. Thanks to this if you want to instrument a new HTTP library -that uses a FooRequest as a mean of sending HTTP requests then you have to create an -implementation of a SpanTextMap that delegates calls to FooRequest in terms of retrieval -and insertion of HTTP headers.

    9.1 Spring Integration

    For Spring Integration there are 2 interfaces responsible for creation of a Span from a Message. -These are:

    • MessagingSpanTextMapExtractor
    • MessagingSpanTextMapInjector

    You can override them by providing your own implementation.

    9.2 HTTP

    For HTTP there are 2 interfaces responsible for creation of a Span from a Message. -These are:

    • HttpSpanExtractor
    • HttpSpanInjector

    You can override them by providing your own implementation.

    9.3 Example

    Let’s assume that instead of the standard Zipkin compatible tracing HTTP header names -you have

    • for trace id - correlationId
    • for span id - mySpanId

    This is a an example of a SpanExtractor

    static class CustomHttpSpanExtractor implements HttpSpanExtractor {
+}

    Running the preceding method with a value of 15 leads to setting a tag with a String value of "15".

    12. Customizations

    12.1 HTTP

    If a customization of client / server parsing of the HTTP related spans is required, +just register a bean of type brave.http.HttpClientParser or +brave.http.HttpServerParser. If client /server sampling is required, just +register a bean of type brave.http.HttpSampler and name the bean + sleuthClientSampler for client sampler and sleuthServerSampler for server sampler. + For your convenience the @ClientSampler and @ServerSampler + annotations can be used to inject the proper beans or to + reference the bean names via their static String NAME fields.

    Check out Brave’s code to see an example of how to make a path-based sampler +https://github.com/openzipkin/brave/tree/master/instrumentation/http#sampling-policy

    If you want to completely rewrite the HttpTracing bean you can use the SkipPatternProvider +interface to retrieve the URL Pattern for spans that should be not sampled. Below you can see +an example of usage of SkipPatternProvider inside a server side, HttpSampler.

    @Configuration
+class Config {
+  @Bean(name = ServerSampler.NAME)
+  HttpSampler myHttpSampler(SkipPatternProvider provider) {
+  	Pattern pattern = provider.skipPattern();
+  	return new HttpSampler() {
 
-	@Override public Span joinTrace(SpanTextMap carrier) {
-		Map<String, String> 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.traceIdString());
-		carrier.put("mySpanId", Span.idToHex(span.getSpanId()));
-	}
-}

    And you could register it like this:

    @Bean
-HttpSpanInjector customHttpSpanInjector() {
-	return new CustomHttpSpanInjector();
-}
-
-@Bean
-HttpSpanExtractor customHttpSpanExtractor() {
-	return new CustomHttpSpanExtractor();
-}

    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 SpanInjector -that injects the headers into the Http Response and a Servlet filter which makes use of this can be added the following way:

    static class CustomHttpServletResponseSpanInjector extends ZipkinHttpSpanInjector {
-
-	@Override
-	public void inject(Span span, SpanTextMap carrier) {
-		super.inject(span, carrier);
-		carrier.put(Span.TRACE_ID_NAME, span.traceIdString());
-		carrier.put(Span.SPAN_ID_NAME, Span.idToHex(span.getSpanId()));
-	}
-}
-
-static class HttpResponseInjectingTraceFilter extends GenericFilterBean {
+  		@Override public <Req> Boolean trySample(HttpAdapter<Req, ?> adapter, Req request) {
+  			String url = adapter.path(request);
+  			boolean shouldSkip = pattern.matcher(url).matches();
+  			if (shouldSkip) {
+  				return false;
+  			}
+  			return null;
+  		}
+  	};
+  }
+}

    12.2 TracingFilter

    You can also modify the behavior of the TracingFilter, which is the component that is responsible for processing the input HTTP request and adding tags basing on the HTTP response. +You can customize the tags or modify the response headers by registering your own instance of the TracingFilter bean.

    In the following example, we register the TracingFilter bean, add the ZIPKIN-TRACE-ID response header containing the current Span’s trace id, and add a tag with key custom and a value tag to the span.

    @Component
+@Order(TraceWebServletAutoConfiguration.TRACING_FILTER_ORDER + 1)
+class MyFilter extends GenericFilterBean {
 
 	private final Tracer tracer;
-	private final HttpSpanInjector spanInjector;
 
-	public HttpResponseInjectingTraceFilter(Tracer tracer, HttpSpanInjector spanInjector) {
+	MyFilter(Tracer tracer) {
 		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);
+	@Override public void doFilter(ServletRequest request, ServletResponse response,
+			FilterChain chain) throws IOException, ServletException {
+		Span currentSpan = this.tracer.currentSpan();
+		if (currentSpan == null) {
+			chain.doFilter(request, response);
+			return;
+		}
+		// for readability we're returning trace id in a hex form
+		((HttpServletResponse) response)
+				.addHeader("ZIPKIN-TRACE-ID",
+						currentSpan.context().traceIdString());
+		// we can also add some custom tags
+		currentSpan.tag("custom", "tag");
+		chain.doFilter(request, response);
 	}
-
-	 class HttpServletResponseTextMap implements SpanTextMap {
-
-		 private final HttpServletResponse delegate;
-
-		 HttpServletResponseTextMap(HttpServletResponse delegate) {
-			 this.delegate = delegate;
-		 }
-
-		 @Override
-		 public Iterator<Map.Entry<String, String>> iterator() {
-			 Map<String, String> map = new HashMap<>();
-			 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);
-		 }
-	 }
-}

    And you could register them like this:

    @Bean HttpSpanInjector customHttpServletResponseSpanInjector() {
-	return new CustomHttpServletResponseSpanInjector();
+}

    12.3 Custom service name

    By default, Sleuth assumes that, when you send a span to Zipkin, you want the span’s service name to be equal to the value of the spring.application.name property. +That is not always the case, though. +There are situations in which you want to explicitly provide a different service name for all spans coming from your application. +To achieve that, you can pass the following property to your application to override that value (the example is for a service named myService):

    spring.zipkin.service.name: myService

    12.4 Customization of Reported Spans

    Before reporting spans (for example, to Zipkin) you may want to modify that span in some way. +You can do so by using the SpanAdjuster interface.

    In Sleuth, we generate spans with a fixed name. +Some users want to modify the name depending on values of tags. +You can implement the SpanAdjuster interface to alter that name.

    The following example shows how to register two beans that implement SpanAdjuster:

    @Bean SpanAdjuster adjusterOne() {
+	return span -> span.toBuilder().name("foo").build();
 }
 
-@Bean
-HttpResponseInjectingTraceFilter responseInjectingTraceFilter(Tracer tracer) {
-	return new HttpResponseInjectingTraceFilter(tracer, customHttpServletResponseSpanInjector());
-}

    9.4 TraceFilter

    You can also modify the behaviour of the TraceFilter - the component that is responsible -for processing the input HTTP request and adding tags basing on the HTTP response. You can customize -the tags, or modify the response headers by registering your own instance of the TraceFilter bean.

    In the following example we will register the TraceFilter bean and we will add the -ZIPKIN-TRACE-ID response header containing the current Span’s trace id. Also we will -add to the Span a tag with key custom and a value tag.

    @Bean
-TraceFilter myTraceFilter(BeanFactory beanFactory, final Tracer tracer) {
-	return new TraceFilter(beanFactory) {
-		@Override protected void addResponseTags(HttpServletResponse response,
-				Throwable e) {
-			// execute the default behaviour
-			super.addResponseTags(response, e);
-			// for readability we're returning trace id in a hex form
-			response.addHeader("ZIPKIN-TRACE-ID",
-					Span.idToHex(tracer.getCurrentSpan().getTraceId()));
-			// we can also add some custom tags
-			tracer.addTag("custom", "tag");
-		}
-	};
-}

    9.5 Custom SA tag in Zipkin

    Sometimes you want to create a manual Span that will wrap a call to an external service which is not instrumented. -What you can do is to create a span with the peer.service tag that will contain a value of the service that you want to call. -Below you can see an example of a call to Redis that is wrapped in such a span.

    Unresolved directive in spring-cloud-sleuth.adoc - include::../../../..//spring-cloud-sleuth-zipkin-legacy/src/test/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporterTest.java[tags=service_name,indent=0]
    [Important]Important

    Remember not to add both peer.service tag and the SA tag! You have to add only peer.service.

    9.6 Custom service name

    By default Sleuth assumes that when you send a span to Zipkin, you want the span’s service name - to be equal to spring.application.name value. That’s not always the case though. There - are situations in which you want to explicitly provide a different service name for all spans coming - from your application. To achieve that it’s enough to just pass the following property - to your application to override that value (example for foo service name):

    spring.zipkin.service.name: foo

    9.7 Customization of reported spans

    Before reporting spans to e.g. Zipkin you can be interested in modifying that span in some way. - You can achieve that by using the SpanAdjuster interface.

    Example of usage:

    In Sleuth we’re generating spans with a fixed name. Some users want to modify the name depending on values -of tags. Implementation of the SpanAdjuster interface can be used to alter that name. Example:

    @Bean
-SpanAdjuster customSpanAdjuster() {
-    return span -> span.toBuilder().name(scrub(span.getName())).build();
-}

    This will lead in changing the name of the reported span just before it gets sent to Zipkin.

    [Important]Important

    Your SpanReporter should inject the SpanAdjuster and - allow span manipulation before the actual reporting is done.

    9.8 Host locator

    In order to define the host that is corresponding to a particular span we need to resolve the host name -and port. The default approach is to take it from server properties. If those for some reason are not set -then we’re trying to retrieve the host name from the network interfaces.

    If you have the discovery client enabled and prefer to retrieve the host address from the registered -instance in a service registry then you have to set the property (it’s applicable for both HTTP and -Stream based span reporting).

    spring.zipkin.locator.discovery.enabled: true

    10. Sending spans to Zipkin

    By default if you add spring-cloud-starter-zipkin as a dependency to your project, -when the span is closed, it will be sent to Zipkin over HTTP. The communication -is asynchronous. You can configure the URL by setting the spring.zipkin.baseUrl -property as follows:

    spring.zipkin.baseUrl: http://192.168.99.100:9411/

    If you want to find Zipkin via service discovery it’s enough to pass the -Zipkin’s service id inside the URL (example for zipkinserver service id)

    spring.zipkin.baseUrl: http://zipkinserver/

    11. Span Data as Messages

    [Important]Important

    The suggested approach is to use the Zipkin’s -native support for message based span sending. Starting from -Edgware Zipkin Stream server is deprecated and in Finchley -it got removed.

    You can accumulate and send span data over -Spring Cloud Stream by -including the spring-cloud-sleuth-stream jar as a dependency, and -adding a Channel Binder implementation -(e.g. spring-cloud-starter-stream-rabbit for RabbitMQ or -spring-cloud-starter-stream-kafka for Kafka). This will -automatically turn your app into a producer of messages with payload -type Spans.

    11.1 Zipkin Consumer

    Please refer to the Dalston Documentaion -on how to create a Stream Zipkin server. That approach has been -deprecated in Edgware and removed in Finchley release.

    11.2 Custom Consumer

    A custom consumer can also easily be implemented using -spring-cloud-sleuth-stream and binding to the SleuthSink. Example:

    @EnableBinding(SleuthSink.class)
-@SpringBootApplication(exclude = SleuthStreamAutoConfiguration.class)
-@MessageEndpoint
-public class Consumer {
-
-    @ServiceActivator(inputChannel = SleuthSink.INPUT)
-    public void sink(Spans input) throws Exception {
-        // ... process spans
-    }
-}
    [Note]Note

    the sample consumer application above explicitly excludes -SleuthStreamAutoConfiguration so it doesn’t send messages to itself, -but this is optional (you might actually want to trace requests into -the consumer app).

    In order to customize the polling mechanism you can create a bean of PollerMetadata type -with name equal to StreamSpanReporter.POLLER. Here you can find an example of such a configuration.

    @Configuration
-public static class CustomPollerConfiguration {
-
-	@Bean(name = StreamSpanReporter.POLLER)
-	PollerMetadata customPoller() {
-		PollerMetadata poller = new PollerMetadata();
-		poller.setMaxMessagesPerPoll(500);
-		poller.setTrigger(new PeriodicTrigger(5000L));
-		return poller;
+@Bean SpanAdjuster adjusterTwo() {
+	return span -> span.toBuilder().name(span.name() + " bar").build();
+}

    The preceding example results in changing the name of the reported span to foo bar, just before it gets reported (for example, to Zipkin).

    12.5 Host Locator

    [Important]Important

    This section is about defining host from service discovery. +It is NOT about finding Zipkin through service discovery.

    To define the host that corresponds to a particular span, we need to resolve the host name and port. +The default approach is to take these values from server properties. +If those are not set, we try to retrieve the host name from the network interfaces.

    If you have the discovery client enabled and prefer to retrieve the host address from the registered instance in a service registry, you have to set the spring.zipkin.locator.discovery.enabled property (it is applicable for both HTTP-based and Stream-based span reporting), as follows:

    spring.zipkin.locator.discovery.enabled: true

    13. Sending Spans to Zipkin

    By default, if you add spring-cloud-starter-zipkin as a dependency to your project, when the span is closed, it is sent to Zipkin over HTTP. +The communication is asynchronous. +You can configure the URL by setting the spring.zipkin.baseUrl property, as follows:

    spring.zipkin.baseUrl: http://192.168.99.100:9411/

    If you want to find Zipkin through service discovery, you can pass the Zipkin’s service ID inside the URL, as shown in the following example for zipkinserver service ID:

    spring.zipkin.baseUrl: http://zipkinserver/

    To disable this feature just set spring.zipkin.discoveryClientEnabled to `false.

    When the Discovery Client feature is enabled, Sleuth uses +LoadBalancerClient to find the URL of the Zipkin Server. It means +that you can set up the load balancing configuration e.g. via Ribbon.

    zipkinserver:
+  ribbon:
+    ListOfServers: host1,host2

    If you have web, rabbit, or kafka together on the classpath, you might need to pick the means by which you would like to send spans to zipkin. +To do so, set web, rabbit, or kafka to the spring.zipkin.sender.type property. +The following example shows setting the sender type for web:

    spring.zipkin.sender.type: web

    To customize the RestTemplate that sends spans to Zipkin via HTTP, you can register +the ZipkinRestTemplateCustomizer bean.

    @Configuration
+class MyConfig {
+	@Bean ZipkinRestTemplateCustomizer myCustomizer() {
+		return new ZipkinRestTemplateCustomizer() {
+			@Override
+			void customize(RestTemplate restTemplate) {
+				// customize the RestTemplate
+			}
+		};
 	}
-}

    12. Metrics

    Currently Spring Cloud Sleuth registers very simple metrics related to spans. -It’s using the Spring Boot’s metrics support -to calculate the number of accepted and dropped spans. Each time a span gets -sent to Zipkin the number of accepted spans will increase. If there’s an error then -the number of dropped spans will get increased.

    13. Integrations

    13.1 Runnable and Callable

    If you’re wrapping your logic in Runnable or Callable it’s enough to wrap those classes in their Sleuth representative.

    Example for Runnable:

    Runnable runnable = new Runnable() {
+}

    If, however, you would like to control the full process of creating the RestTemplate +object, you will have to create a bean of zipkin2.reporter.Sender type.

    	@Bean Sender myRestTemplateSender(ZipkinProperties zipkin,
+			ZipkinRestTemplateCustomizer zipkinRestTemplateCustomizer) {
+		RestTemplate restTemplate = mySuperCustomRestTemplate();
+		zipkinRestTemplateCustomizer.customize(restTemplate);
+		return myCustomSender(zipkin, restTemplate);
+	}

    14. Zipkin Stream Span Consumer

    [Important]Important

    We recommend using Zipkin’s native support for message-based span sending. +Starting from the Edgware release, the Zipkin Stream server is deprecated. +In the Finchley release, it got removed.

    If for some reason you need to create the deprecated Stream Zipkin server, see the Dalston Documentation.

    15. Integrations

    15.1 OpenTracing

    Spring Cloud Sleuth is compatible with OpenTracing. +If you have OpenTracing on the classpath, we automatically register the OpenTracing Tracer bean. +If you wish to disable this, set spring.sleuth.opentracing.enabled to false

    15.2 Runnable and Callable

    If you wrap your logic in Runnable or Callable, you can wrap those classes in their Sleuth representative, as shown in the following example for Runnable:

    Runnable runnable = new Runnable() {
 	@Override
 	public void run() {
 		// do some work
@@ -606,10 +746,11 @@ the number of dropped spans will get increased.
    // Manual `TraceRunnable` creation with explicit "calculateTax" Span name -Runnable traceRunnable = new TraceRunnable(tracer, spanNamer, runnable, "calculateTax"); -// Wrapping `Runnable` with `Tracer`. The Span name will be taken either from the -// `@SpanName` annotation or from `toString` method -Runnable traceRunnableFromTracer = tracer.wrap(runnable);

    Example for Callable:

    Callable<String> callable = new Callable<String>() {
+Runnable traceRunnable = new TraceRunnable(tracing, spanNamer, runnable,
+		"calculateTax");
+// Wrapping `Runnable` with `Tracing`. That way the current span will be available
+// in the thread of `Runnable`
+Runnable traceRunnableFromTracer = tracing.currentTraceContext().wrap(runnable);

    The following example shows how to do so for Callable:

    Callable<String> callable = new Callable<String>() {
 	@Override
 	public String call() throws Exception {
 		return someLogic();
@@ -621,82 +762,64 @@ Runnable traceRunnableFromTracer = tracer.wrap(runnable);

    Example for // Manual `TraceCallable` creation with explicit "calculateTax" Span name -Callable<String> traceCallable = new TraceCallable<>(tracer, spanNamer, callable, "calculateTax"); -// Wrapping `Callable` with `Tracer`. The Span name will be taken either from the -// `@SpanName` annotation or from `toString` method -Callable<String> traceCallableFromTracer = tracer.wrap(callable);

    That way you will ensure that a new Span is created and closed for each execution.

    13.2 Hystrix

    13.2.1 Custom Concurrency Strategy

    We’re registering a custom HystrixConcurrencyStrategy -that wraps all Callable instances into their Sleuth representative - -the TraceCallable. The strategy either starts or continues a span depending on the fact whether tracing was already going -on before the Hystrix command was called. To disable the custom Hystrix Concurrency Strategy set the spring.sleuth.hystrix.strategy.enabled to false.

    13.2.2 Manual Command setting

    Assuming that you have the following HystrixCommand:

    HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) {
+Callable<String> traceCallable = new TraceCallable<>(tracing, spanNamer, callable,
+		"calculateTax");
+// Wrapping `Callable` with `Tracing`. That way the current span will be available
+// in the thread of `Callable`
+Callable<String> traceCallableFromTracer = tracing.currentTraceContext().wrap(callable);

    That way, you ensure that a new span is created and closed for each execution.

    15.3 Hystrix

    15.3.1 Custom Concurrency Strategy

    We register a custom HystrixConcurrencyStrategy called TraceCallable that wraps all Callable instances in their Sleuth representative. +The strategy either starts or continues a span, depending on whether tracing was already going on before the Hystrix command was called. +To disable the custom Hystrix Concurrency Strategy, set the spring.sleuth.hystrix.strategy.enabled to false.

    15.3.2 Manual Command setting

    Assume that you have the following HystrixCommand:

    HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) {
 	@Override
 	protected String run() throws Exception {
 		return someLogic();
 	}
-};

    In order to pass the tracing information you have to wrap the same logic in the Sleuth version of the HystrixCommand which is the -TraceCommand:

    TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, traceKeys, setter) {
+};

    To pass the tracing information, you have to wrap the same logic in the Sleuth version of the HystrixCommand, which is called +TraceCommand, as shown in the following example:

    TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, setter) {
 	@Override
 	public String doRun() throws Exception {
 		return someLogic();
 	}
-};

    13.3 RxJava

    We’re registering a custom RxJavaSchedulersHook -that wraps all Action0 instances into their Sleuth representative - -the TraceAction. The hook either starts or continues a span depending on the fact whether tracing was already going -on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the spring.sleuth.rxjava.schedulers.hook.enabled to false.

    You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list -of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property.

    13.4 HTTP integration

    Features from this section can be disabled by providing the spring.sleuth.web.enabled property with value equal to false.

    13.4.1 HTTP Filter

    Via the TraceFilter all sampled incoming requests result in creation of a Span. That Span’s name is http: + the path to which - the request was sent. E.g. if the request was sent to /foo/bar then the name will be http:/foo/bar. You can configure which URIs you would - like to skip via the spring.sleuth.web.skipPattern property. If you have ManagementServerProperties on classpath then - its value of contextPath gets appended to the provided skip pattern.

    13.4.2 HandlerInterceptor

    Since we want the span names to be precise we’re using a TraceHandlerInterceptor that either wraps an - existing HandlerInterceptor or is added directly to the list of existing HandlerInterceptors. The - TraceHandlerInterceptor adds a special request attribute to the given HttpServletRequest. If the - the TraceFilter doesn’t see this attribute set it will create a "fallback" span which is an additional - span created on the server side so that the trace is presented properly in the UI. Seeing that most likely - signifies that there is a missing instrumentation. In that case please file an issue in Spring Cloud Sleuth.

    13.4.3 Async Servlet support

    If your controller returns a Callable or a WebAsyncTask Spring Cloud Sleuth will continue the existing span instead of creating a new one.

    13.4.4 WebFlux support

    Via the TraceWebFilter all sampled incoming requests result in creation of a Span. That Span’s name is http: + the path to which - the request was sent. E.g. if the request was sent to /foo/bar then the name will be http:/foo/bar. You can configure which URIs you would - like to skip via the spring.sleuth.web.skipPattern property. If you have ManagementServerProperties on classpath then - its value of contextPath gets appended to the provided skip pattern.

    13.5 HTTP client integration

    13.5.1 Synchronous Rest Template

    We’re injecting a RestTemplate interceptor that ensures that all the tracing information is passed to the requests. Each time a -call is made a new Span is created. It gets closed upon receiving the response. In order to block the synchronous RestTemplate features -just set spring.sleuth.web.client.enabled to false.

    [Important]Important

    You have to register RestTemplate as a bean so that the interceptors will get injected. -If you create a RestTemplate instance with a new keyword then the instrumentation WILL NOT work.

    13.5.2 Asynchronous Rest Template

    [Important]Important

    A traced version of an AsyncRestTemplate bean is registered for you out of the box. If you -have your own bean you have to wrap it in a TraceAsyncRestTemplate representation. The best solution -is to only customize the ClientHttpRequestFactory and / or AsyncClientHttpRequestFactory. -If you have your own AsyncRestTemplate and you don’t wrap it your calls WILL NOT GET TRACED.

    Custom instrumentation is set to create and close Spans upon sending and receiving requests. You can customize the ClientHttpRequestFactory -and the AsyncClientHttpRequestFactory by registering your beans. Remember to use tracing compatible implementations (e.g. don’t forget to -wrap ThreadPoolTaskScheduler in a TraceAsyncListenableTaskExecutor). Example of custom request factories:

    @EnableAutoConfiguration
-@Configuration
-public static class TestConfiguration {
-
-	@Bean
-	ClientHttpRequestFactory mySyncClientFactory() {
-		return new MySyncClientHttpRequestFactory();
-	}
-
-	@Bean
-	AsyncClientHttpRequestFactory myAsyncClientFactory() {
-		return new MyAsyncClientHttpRequestFactory();
-	}
-}

    To block the AsyncRestTemplate features set spring.sleuth.web.async.client.enabled to false. -To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapper set spring.sleuth.web.async.client.factory.enabled -to false. If you don’t want to create AsyncRestClient at all set spring.sleuth.web.async.client.template.enabled to false.

    Multiple Asynchronous Rest Templates

    Sometimes you need to use multiple implementations of Asynchronous Rest Template. In the following snippet you -can see an example of how to set up such a custom AsyncRestTemplate.

    @Configuration
+};

    15.4 RxJava

    We registering a custom RxJavaSchedulersHook that wraps all Action0 instances in their Sleuth representative, which is called TraceAction. +The hook either starts or continues a span, depending on whether tracing was already going on before the Action was scheduled. +To disable the custom RxJavaSchedulersHook, set the spring.sleuth.rxjava.schedulers.hook.enabled to false.

    You can define a list of regular expressions for thread names for which you do not want spans to be created. +To do so, provide a comma-separated list of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property.

    [Important]Important

    The suggest approach to reactive programming and Sleuth is to use +the Reactor support.

    15.5 HTTP integration

    Features from this section can be disabled by setting the spring.sleuth.web.enabled property with value equal to false.

    15.5.1 HTTP Filter

    Through the TracingFilter, all sampled incoming requests result in creation of a Span. +That Span’s name is http: + the path to which the request was sent. +For example, if the request was sent to /this/that then the name will be http:/this/that. +You can configure which URIs you would like to skip by setting the spring.sleuth.web.skipPattern property. +If you have ManagementServerProperties on classpath, its value of contextPath gets appended to the provided skip pattern. +If you want to reuse the Sleuth’s default skip patterns and just append your own, pass those patterns by using the spring.sleuth.web.additionalSkipPattern.

    15.5.2 HandlerInterceptor

    Since we want the span names to be precise, we use a TraceHandlerInterceptor that either wraps an existing HandlerInterceptor or is added directly to the list of existing HandlerInterceptors. +The TraceHandlerInterceptor adds a special request attribute to the given HttpServletRequest. +If the the TracingFilter does not see this attribute, it creates a "fallback" span, which is an additional span created on the server side so that the trace is presented properly in the UI. +If that happens, there is probably missing instrumentation. +In that case, please file an issue in Spring Cloud Sleuth.

    15.5.3 Async Servlet support

    If your controller returns a Callable or a WebAsyncTask, Spring Cloud Sleuth continues the existing span instead of creating a new one.

    15.5.4 WebFlux support

    Through TraceWebFilter, all sampled incoming requests result in creation of a Span. +That Span’s name is http: + the path to which the request was sent. +For example, if the request was sent to /this/that, the name is http:/this/that. +You can configure which URIs you would like to skip by using the spring.sleuth.web.skipPattern property. +If you have ManagementServerProperties on the classpath, its value of contextPath gets appended to the provided skip pattern. +If you want to reuse Sleuth’s default skip patterns and append your own, pass those patterns by using the spring.sleuth.web.additionalSkipPattern.

    15.5.5 Dubbo RPC support

    Via the integration with Brave, Spring Cloud Sleuth supports Dubbo. +It’s enough to add the brave-instrumentation-dubbo-rpc dependency:

    <dependency>
+    <groupId>io.zipkin.brave</groupId>
+    <artifactId>brave-instrumentation-dubbo-rpc</artifactId>
+</dependency>

    You need to also set a dubbo.properties file with the following contents:

    dubbo.provider.filter=tracing
+dubbo.consumer.filter=tracing

    You can read more about Brave - Dubbo integration here. +An example of Spring Cloud Sleuth and Dubbo can be found here.

    15.6 HTTP Client Integration

    15.6.1 Synchronous Rest Template

    We inject a RestTemplate interceptor to ensure that all the tracing information is passed to the requests. +Each time a call is made, a new Span is created. +It gets closed upon receiving the response. +To block the synchronous RestTemplate features, set spring.sleuth.web.client.enabled to false.

    [Important]Important

    You have to register RestTemplate as a bean so that the interceptors get injected. +If you create a RestTemplate instance with a new keyword, the instrumentation does NOT work.

    15.6.2 Asynchronous Rest Template

    [Important]Important

    Starting with Sleuth 2.0.0, we no longer register a bean of AsyncRestTemplate type. +It is up to you to create such a bean. +Then we instrument it.

    To block the AsyncRestTemplate features, set spring.sleuth.web.async.client.enabled to false. +To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapper, set spring.sleuth.web.async.client.factory.enabled +to false. +If you do not want to create AsyncRestClient at all, set spring.sleuth.web.async.client.template.enabled to false.

    Multiple Asynchronous Rest Templates

    Sometimes you need to use multiple implementations of the Asynchronous Rest Template. +In the following snippet, you can see an example of how to set up such a custom AsyncRestTemplate:

    @Configuration
 @EnableAutoConfiguration
 static class Config {
-	@Autowired Tracer tracer;
-	@Autowired HttpTraceKeysInjector httpTraceKeysInjector;
-	@Autowired HttpSpanInjector spanInjector;
 
 	@Bean(name = "customAsyncRestTemplate")
-	public AsyncRestTemplate traceAsyncRestTemplate(@Qualifier("customHttpRequestFactoryWrapper")
-			TraceAsyncClientHttpRequestFactoryWrapper wrapper, ErrorParser errorParser) {
-		return new TraceAsyncRestTemplate(wrapper, this.tracer, errorParser);
-	}
-
-	@Bean(name = "customHttpRequestFactoryWrapper")
-	public TraceAsyncClientHttpRequestFactoryWrapper traceAsyncClientHttpRequestFactory() {
-		return new TraceAsyncClientHttpRequestFactoryWrapper(this.tracer,
-				this.spanInjector,
-				asyncClientFactory(),
-				clientHttpRequestFactory(),
-				this.httpTraceKeysInjector);
+	public AsyncRestTemplate traceAsyncRestTemplate() {
+		return new AsyncRestTemplate(asyncClientFactory(), clientHttpRequestFactory());
 	}
 
 	private ClientHttpRequestFactory clientHttpRequestFactory() {
@@ -710,32 +833,32 @@ can see an example of how to set up such a custom AsyncRes
 		//CUSTOMIZE HERE
 		return factory;
 	}
-}

    13.5.3 WebClient

    We inject a ExchangeFilterFunction implementation that creates a span and via on success and on -error callbacks takes care of closing client side spans.

    [Important]Important

    You have to register WebClient as a bean so that the tracing instrumention gets applied. -If you create a WebClient instance with a new keyword then the instrumentation WILL NOT work.

    13.5.4 Traverson

    If you’re using the Traverson library -it’s enough for you to inject a RestTemplate as a bean into your Traverson object. Since RestTemplate -is already intercepted, you will get full support of tracing in your client. Below you can find a pseudo code -of how to do that:

    @Autowired RestTemplate restTemplate;
+}

    15.6.3 WebClient

    We inject a ExchangeFilterFunction implementation that creates a span and, through on-success and on-error callbacks, takes care of closing client-side spans.

    To block this feature, set spring.sleuth.web.client.enabled to false.

    [Important]Important

    You have to register WebClient as a bean so that the tracing instrumentation gets applied. +If you create a WebClient instance with a new keyword, the instrumentation does NOT work.

    15.6.4 Traverson

    If you use the Traverson library, you can inject a RestTemplate as a bean into your Traverson object. +Since RestTemplate is already intercepted, you get full support for tracing in your client. The following pseudo code +shows how to do that:

    @Autowired RestTemplate restTemplate;
 
 Traverson traverson = new Traverson(URI.create("http://some/address"),
     MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate);
-// use Traverson

    13.6 Feign

    By default Spring Cloud Sleuth provides integration with feign via the TraceFeignClientAutoConfiguration. You can disable it entirely -by setting spring.sleuth.feign.enabled to false. If you do so then no Feign related instrumentation will take place.

    Part of Feign instrumentation is done via a FeignBeanPostProcessor. You can disable it by providing the spring.sleuth.feign.processor.enabled equal to false. -If you set it like this then Spring Cloud Sleuth will not instrument any of your custom Feign components. All the default instrumentation -however will be still there.

    13.7 Asynchronous communication

    13.7.1 @Async annotated methods

    In Spring Cloud Sleuth we’re instrumenting async related components so that the tracing information is passed between threads. -You can disable this behaviour by setting the value of spring.sleuth.async.enabled to false.

    If you annotate your method with @Async then we’ll automatically create a new Span with the following characteristics:

    • if the method is annotated with @SpanName then the value of the annotation will be the Span’s name
    • if the method is not annotated with @SpanName the Span name will be the annotated method name
    • the Span will be tagged with that method’s class name and the method name too

    13.7.2 @Scheduled annotated methods

    In Spring Cloud Sleuth we’re instrumenting scheduled method execution so that the tracing information is passed between threads. You can disable this behaviour -by setting the value of spring.sleuth.scheduled.enabled to false.

    If you annotate your method with @Scheduled then we’ll automatically create a new Span with the following characteristics:

    • the Span name will be the annotated method name
    • the Span will be tagged with that method’s class name and the method name too

    If you want to skip Span creation for some @Scheduled annotated classes you can set the -spring.sleuth.scheduled.skipPattern with a regular expression that will match the fully qualified name of the -@Scheduled annotated class.

    [Tip]Tip

    If you are using spring-cloud-sleuth-stream and spring-cloud-netflix-hystrix-stream together, Span will be created for each Hystrix metrics and sent to Zipkin. This may be annoying. You can prevent this by setting spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask

    13.7.3 Executor, ExecutorService and ScheduledExecutorService

    We’re providing LazyTraceExecutor, TraceableExecutorService and TraceableScheduledExecutorService. Those implementations -are creating Spans each time a new task is submitted, invoked or scheduled.

    Here you can see an example of how to pass tracing information with TraceableExecutorService when working with CompletableFuture:

    CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
+// use Traverson

    15.6.5 Apache HttpClientBuilder and HttpAsyncClientBuilder

    We instrument the HttpClientBuilder and HttpAsyncClientBuilder so that +tracing context gets injected to the sent requests.

    To block these features, set spring.sleuth.web.client.enabled to false.

    15.6.6 Netty HttpClient

    We instrument the Netty’s HttpClient.

    To block this feature, set spring.sleuth.web.client.enabled to false.

    [Important]Important

    You have to register HttpClient as a bean so that the instrumentation happens. +If you create a HttpClient instance with a new keyword, the instrumentation does NOT work.

    15.6.7 UserInfoRestTemplateCustomizer

    We instrument the Spring Security’s UserInfoRestTemplateCustomizer.

    To block this feature, set spring.sleuth.web.client.enabled to false.

    15.7 Feign

    By default, Spring Cloud Sleuth provides integration with Feign through TraceFeignClientAutoConfiguration. +You can disable it entirely by setting spring.sleuth.feign.enabled to false. +If you do so, no Feign-related instrumentation take place.

    Part of Feign instrumentation is done through a FeignBeanPostProcessor. +You can disable it by setting spring.sleuth.feign.processor.enabled to false. +If you set it to false, Spring Cloud Sleuth does not instrument any of your custom Feign components. +However, all the default instrumentation is still there.

    15.8 Asynchronous Communication

    15.8.1 @Async Annotated methods

    In Spring Cloud Sleuth, we instrument async-related components so that the tracing information is passed between threads. +You can disable this behavior by setting the value of spring.sleuth.async.enabled to false.

    If you annotate your method with @Async, we automatically create a new Span with the following characteristics:

    • If the method is annotated with @SpanName, the value of the annotation is the Span’s name.
    • If the method is not annotated with @SpanName, the Span name is the annotated method name.
    • The span is tagged with the method’s class name and method name.

    15.8.2 @Scheduled Annotated Methods

    In Spring Cloud Sleuth, we instrument scheduled method execution so that the tracing information is passed between threads. +You can disable this behavior by setting the value of spring.sleuth.scheduled.enabled to false.

    If you annotate your method with @Scheduled, we automatically create a new span with the following characteristics:

    • The span name is the annotated method name.
    • The span is tagged with the method’s class name and method name.

    If you want to skip span creation for some @Scheduled annotated classes, you can set the spring.sleuth.scheduled.skipPattern with a regular expression that matches the fully qualified name of the @Scheduled annotated class. +If you use spring-cloud-sleuth-stream and spring-cloud-netflix-hystrix-stream together, a span is created for each Hystrix metrics and sent to Zipkin. +This behavior may be annoying. That’s why, by default, spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask.

    15.8.3 Executor, ExecutorService, and ScheduledExecutorService

    We provide LazyTraceExecutor, TraceableExecutorService, and TraceableScheduledExecutorService. Those implementations create spans each time a new task is submitted, invoked, or scheduled.

    The following example shows how to pass tracing information with TraceableExecutorService when working with CompletableFuture:

    CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
 	// perform some logic
 	return 1_000_000L;
-}, new TraceableExecutorService(executorService,
+}, new TraceableExecutorService(beanFactory, executorService,
 		// 'calculateTax' explicitly names the span - this param is optional
-		tracer, traceKeys, spanNamer, "calculateTax"));
    [Important]Important

    Sleuth doesn’t work with parallelStream() out of the box. If you want -to have the tracing information propagated through the stream you have to use the -approach with supplyAsync(...) as presented above.

    Customization of Executors

    Sometimes you need to set up a custom instance of the AsyncExecutor. In the following snippet you -can see an example of how to set up such a custom Executor.

    @Configuration
+		"calculateTax"));
    [Important]Important

    Sleuth does not work with parallelStream() out of the box. +If you want to have the tracing information propagated through the stream, you have to use the approach with supplyAsync(...), as shown earlier.

    Customization of Executors

    Sometimes, you need to set up a custom instance of the AsyncExecutor. +The following example shows how to set up such a custom Executor:

    @Configuration
 @EnableAutoConfiguration
 @EnableAsync
 static class CustomExecutorConfig extends AsyncConfigurerSupport {
@@ -753,9 +876,17 @@ can see an example of how to set up such a custom Executor
 		executor.initialize();
 		return new LazyTraceExecutor(this.beanFactory, executor);
 	}
-}

    13.8 Messaging

    Spring Cloud Sleuth integrates with Spring Integration. It creates spans for publish and -subscribe events. To disable Spring Integration instrumentation, set spring.sleuth.integration.enabled to false.

    You can provide the spring.sleuth.integration.patterns pattern to explicitly -provide the names of channels that you want to include for tracing. By default all channels -are included.

    [Important]Important

    When using the Executor to build a Spring Integration IntegrationFlow remember to use the untraced version of the Executor. -Decorating Spring Integration Executor Channel with TraceableExecutorService will cause the spans to be improperly closed.

    13.9 Zuul

    We’re registering Zuul filters to propagate the tracing information (the request header is enriched with tracing data). -To disable Zuul support set the spring.sleuth.zuul.enabled property to false.

    14. Running examples

    You can find the running examples deployed in the Pivotal Web Services. Check them out in the following links:

    \ No newline at end of file +}

    15.9 Messaging

    Features from this section can be disabled by setting the spring.sleuth.messaging.enabled property with value equal to false.

    15.9.1 Spring Integration and Spring Cloud Stream

    Spring Cloud Sleuth integrates with Spring Integration. +It creates spans for publish and subscribe events. +To disable Spring Integration instrumentation, set spring.sleuth.integration.enabled to false.

    You can provide the spring.sleuth.integration.patterns pattern to explicitly provide the names of channels that you want to include for tracing. +By default, all channels but hystrixStreamOutput channel are included.

    [Important]Important

    When using the Executor to build a Spring Integration IntegrationFlow, you must use the untraced version of the Executor. +Decorating the Spring Integration Executor Channel with TraceableExecutorService causes the spans to be improperly closed.

    15.9.2 Spring RabbitMq

    We instrument the RabbitTemplate so that tracing headers get injected +into the message.

    To block this feature, set spring.sleuth.messaging.rabbit.enabled to false.

    15.9.3 Spring Kafka

    We instrument the Spring Kafka’s ProducerFactory and ConsumerFactory +so that tracing headers get injected into the created Spring Kafka’s +Producer and Consumer.

    To block this feature, set spring.sleuth.messaging.kafka.enabled to false.

    [Note]Note

    We do not support context propagation via @KafkaListener annotation. +Check this issue for more information.

    15.10 Zuul

    We instrument the Zuul Ribbon integration by enriching the Ribbon requests with tracing information. +To disable Zuul support, set the spring.sleuth.zuul.enabled property to false.

    16. Running examples

    You can see the running examples deployed in the Pivotal Web Services. +Check them out at the following links:

    \ No newline at end of file diff --git a/2.0.x/spring-cloud-sleuth.xml b/2.0.x/spring-cloud-sleuth.xml index f90d7ddc3..5e2bd9b1f 100644 --- a/2.0.x/spring-cloud-sleuth.xml +++ b/2.0.x/spring-cloud-sleuth.xml @@ -4,17 +4,17 @@ Spring Cloud Sleuth -2017-11-28 +2018-07-25 -Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer +Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer, Jay Bryant A -2.0.0.BUILD-SNAPSHOT +2.0.1.BUILD-SNAPSHOT Introduction @@ -22,40 +22,42 @@
    Terminology Spring Cloud Sleuth borrows Dapper’s terminology. -Span: The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an -RPC. Span’s are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span -is a part of. Spans also have other data, such as descriptions, timestamped events, key-value -annotations (tags), the ID of the span that caused them, and process ID’s (normally IP address). -Spans are started and stopped, and they keep track of their timing information. Once you create a -span, you must stop it at some point in the future. +Span: The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an RPC. +Spans are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span is a part of. +Spans also have other data, such as descriptions, timestamped events, key-value annotations (tags), the ID of the span that caused them, and process IDs (normally IP addresses). +Spans can be started and stopped, and they keep track of their timing information. +Once you create a span, you must stop it at some point in the future. -The initial span that starts a trace is called a root span. The value of span id -of that span is equal to trace id. +The initial span that starts a trace is called a root span. The value of the ID +of that span is equal to the trace ID. -Trace: A set of spans forming a tree-like structure. For example, if you are running a distributed -big-data store, a trace might be formed by a put request. -Annotation: is used to record existence of an event in time. Some of the core annotations used to define -the start and stop of a request are: +Trace: A set of spans forming a tree-like structure. +For example, if you run a distributed big-data store, a trace might be formed by a PUT request. +Annotation: Used to record the existence of an event in time. With +Brave instrumentation, we no longer need to set special events +for Zipkin to understand who the client and server are, where +the request started, and where it ended. For learning purposes, +however, we mark these events to highlight what kind +of an action took place. -cs - Client Sent - The client has made a request. This annotation depicts the start of the span. +cs: Client Sent. The client has made a request. This annotation indicates the start of the span. -sr - Server Received - The server side got the request and will start processing it. -If one subtracts the cs timestamp from this timestamp one will receive the network latency. +sr: Server Received: The server side got the request and started processing it. +Subtracting the cs timestamp from this timestamp reveals the network latency. -ss - Server Sent - Annotated upon completion of request processing (when the response -got sent back to the client). If one subtracts the sr timestamp from this timestamp one -will receive the time needed by the server side to process the request. +ss: Server Sent. Annotated upon completion of request processing (when the response got sent back to the client). +Subtracting the sr timestamp from this timestamp reveals the time needed by the server side to process the request. -cr - Client Received - Signifies the end of the span. The client has successfully received the -response from the server side. If one subtracts the cs timestamp from this timestamp one -will receive the whole time needed by the client to receive the response from the server. +cr: Client Received. Signifies the end of the span. +The client has successfully received the response from the server side. +Subtracting the cs timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server. -Visualization of what Span and Trace will look in a system together with the Zipkin annotations: +The following image shows how Span and Trace look in a system, together with the Zipkin annotations: @@ -64,13 +66,14 @@ will receive the whole time needed by the client to receive the response from th Trace Info propagation -Each color of a note signifies a span (7 spans - from A to G). If you have such information in the note: +Each color of a note signifies a span (there are seven spans - from A to G). +Consider the following note: Trace Id = X Span Id = D Client Sent -That means that the current span has Trace-Id set to X, Span-Id set to D. It also has emitted - Client Sent event. -This is how the visualization of the parent / child relationship of spans would look like: +This note indicates that the current span has Trace Id set to X and Span Id set to D. +Also, the Client Sent event took place. +The following image shows how parent-child relationships of spans look: @@ -82,10 +85,11 @@ Client Sent
    Purpose -In the following sections the example from the image above will be taken into consideration. +The following sections refer to the example shown in the preceding image.
    -Distributed tracing with Zipkin -Altogether there are 7 spans . If you go to traces in Zipkin you will see this number in the second trace: +Distributed Tracing with Zipkin +This example has seven spans. +If you go to traces in Zipkin, you can see this number in the second trace, as shown in the following image: @@ -94,7 +98,7 @@ Client Sent Traces -However if you pick a particular trace then you will see 4 spans: +However, if you pick a particular trace, you can see four spans, as shown in the following image: @@ -104,42 +108,44 @@ Client Sent -When picking a particular trace you will see merged spans. That means that if there were 2 spans sent to -Zipkin with Server Received and Server Sent / Client Received and Client Sent -annotations then they will presented as a single span. +When you pick a particular trace, you see merged spans. +That means that, if there were two spans sent to Zipkin with Server Received and Server Sent or Client Received and Client Sent annotations, they are presented as a single span. -Why is there a difference between the 7 and 4 spans in this case? +Why is there a difference between the seven and four spans in this case? -2 spans come from http:/start span. It has the Server Received (SR) and Server Sent (SS) annotations. +Two spans come from the http:/start span. It has the Server Received (sr) and Server Sent (ss) annotations. -2 spans come from the RPC call from service1 to service2 to the http:/foo endpoint. It has the Client Sent (CS) -and Client Received (CR) annotations on service1 side. It also has Server Received (SR) and Server Sent (SS) annotations -on the service2 side. Physically there are 2 spans but they form 1 logical span related to an RPC call. +Two spans come from the RPC call from service1 to service2 to the http:/foo endpoint. +The Client Sent (cs) and Client Received (cr) events took place on the service1 side. +Server Received (sr) and Server Sent (ss) events took place on the service2 side. +These two spans form one logical span related to an RPC call. -2 spans come from the RPC call from service2 to service3 to the http:/bar endpoint. It has the Client Sent (CS) -and Client Received (CR) annotations on service2 side. It also has Server Received (SR) and Server Sent (SS) annotations -on the service3 side. Physically there are 2 spans but they form 1 logical span related to an RPC call. +Two spans come from the RPC call from service2 to service3 to the http:/bar endpoint. +The Client Sent (cs) and Client Received (cr) events took place on the service2 side. +The Server Received (sr) and Server Sent (ss) events took place on the service3 side. +These two spans form one logical span related to an RPC call. -2 spans come from the RPC call from service2 to service4 to the http:/baz endpoint. It has the Client Sent (CS) -and Client Received (CR) annotations on service2 side. It also has Server Received (SR) and Server Sent (SS) annotations -on the service4 side. Physically there are 2 spans but they form 1 logical span related to an RPC call. +Two spans come from the RPC call from service2 to service4 to the http:/baz endpoint. +The Client Sent (cs) and Client Received (cr) events took place on the service2 side. +Server Received (sr) and Server Sent (ss) events took place on the service4 side. +These two spans form one logical span related to an RPC call. -So if we count the physical spans we have 1 from http:/start, 2 from service1 calling service2, 2 form service2 -calling service3 and 2 from service2 calling service4. Altogether 7 spans. -Logically we see the information of Total Spans: 4 because we have 1 span related to the incoming request -to service1 and 3 spans related to RPC calls. +So, if we count the physical spans, we have one from http:/start, two from service1 calling service2, two from service2 +calling service3, and two from service2 calling service4. In sum, we have a total of seven spans. +Logically, we see the information of four total Spans because we have one span related to the incoming request +to service1 and three spans related to RPC calls.
    Visualizing errors -Zipkin allows you to visualize errors in your trace. When an exception was thrown and wasn’t caught then we’re -setting proper tags on the span which Zipkin can properly colorize. You could see in the list of traces one - trace that was in red color. That’s because there was an exception thrown. -If you click that trace then you’ll see a similar picture +Zipkin lets you visualize errors in your trace. +When an exception was thrown and was not caught, we set proper tags on the span, which Zipkin can then properly colorize. +You could see in the list of traces one trace that is red. That appears because an exception was thrown. +If you click that trace, you see a similar picture, as follows: @@ -148,7 +154,7 @@ setting proper tags on the span which Zipkin can properly colorize. You could se Error Traces -Then if you click on one of the spans you’ll see the following +If you then click on one of the spans, you see the following @@ -157,12 +163,19 @@ setting proper tags on the span which Zipkin can properly colorize. You could se Error Traces Info propagation -As you can see you can easily see the reason for an error and the whole stacktrace related to it. +The span shows the reason for the error and the whole stack trace related to it. +
    +
    +Distributed Tracing with Brave +Starting with version 2.0.0, Spring Cloud Sleuth uses Brave as the tracing library. +Consequently, Sleuth no longer takes care of storing the context but delegates that work to Brave. +Due to the fact that Sleuth had different naming and tagging conventions than Brave, we decided to follow Brave’s conventions from now on. +However, if you want to use the legacy Sleuth approaches, you can set the spring.sleuth.http.legacy.enabled property to true.
    Live examples
    -Click Pivotal Web Services icon to see it live! +Click the Pivotal Web Services icon to see it live! @@ -170,7 +183,8 @@ setting proper tags on the span which Zipkin can properly colorize. You could se Zipkin deployed on Pivotal Web Services
    -The dependency graph in Zipkin would look like this: +Click here to see it live! +The dependency graph in Zipkin should resemble the following image: @@ -180,7 +194,7 @@ setting proper tags on the span which Zipkin can properly colorize. You could se
    -Click Pivotal Web Services icon to see it live! +Click the Pivotal Web Services icon to see it live! @@ -188,10 +202,11 @@ setting proper tags on the span which Zipkin can properly colorize. You could se Zipkin deployed on Pivotal Web Services
    +Click here to see it live!
    Log correlation -When grepping the logs of those four applications by trace id equal to e.g. 2485ec27856c56f4 one would get the following: +When using grep to read the logs of those four applications by scanning for a trace ID equal to (for example) 2485ec27856c56f4, you get output resembling the following: service1.log:2016-02-26 11:15:47.561 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Hello from service1. Calling service2 service2.log:2016-02-26 11:15:47.710 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Hello from service2. Calling service3 and then service4 service3.log:2016-02-26 11:15:47.895 INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application : Hello from service3 @@ -199,9 +214,8 @@ service2.log:2016-02-26 11:15:47.924 INFO [service2,2485ec27856c56f4,9aa10ee6fb service4.log:2016-02-26 11:15:48.134 INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application : Hello from service4 service2.log:2016-02-26 11:15:48.156 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Got response from service4 [Hello from service4] service1.log:2016-02-26 11:15:48.182 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]] -If you’re using a log aggregating tool like Kibana, -Splunk etc. you can order the events that took place. An example of -Kibana would look like this: +If you use a log aggregating tool (such as Kibana, Splunk, and others), you can order the events that took place. +An example from Kibana would resemble the following image: @@ -210,7 +224,7 @@ Kibana would look like this: Log correlation with Kibana -If you want to use Logstash here is the Grok pattern for Logstash: +If you want to use Logstash, the following listing shows the Grok pattern for Logstash: filter { # pattern matching logback pattern grok { @@ -218,7 +232,7 @@ Kibana would look like this: } } -If you want to use Grok together with the logs from Cloud Foundry you have to use this pattern: +If you want to use Grok together with the logs from Cloud Foundry, you have to use the following pattern: filter { # pattern matching logback pattern @@ -228,30 +242,19 @@ Kibana would look like this: }
    JSON Logback with Logstash -Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability -we’re passing the dependencies in the groupId:artifactId:version notation. -Dependencies setup - +Often, you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. +To do so, you have to do the following (for readability, we pass the dependencies in the groupId:artifactId:version notation). +Dependencies Setup + -Ensure that Logback is on the classpath (ch.qos.logback:logback-core) +Ensure that Logback is on the classpath (ch.qos.logback:logback-core). -Add Logstash Logback encode - example for version 4.6 : net.logstash.logback:logstash-logback-encoder:4.6 +Add Logstash Logback encode. For example, to use version 4.6, add net.logstash.logback:logstash-logback-encoder:4.6. - -Logback setup -Below you can find an example of a Logback configuration (file named logback-spring.xml) that: - - -logs information from the application in a JSON format to a build/${spring.application.name}.json file - - -has commented out two additional appenders - console and standard log file - - -has the same logging pattern as the one presented in the previous section - - + +Logback Setup +Consider the following example of a Logback configuration file (named logback-spring.xml). <?xml version="1.0" encoding="UTF-8"?> <configuration> <include resource="org/springframework/boot/logging/logback/defaults.xml"/> @@ -328,86 +331,122 @@ we’re passing the dependencies in the groupId:artifactId:version< <!--<appender-ref ref="flatfile"/>--> </root> </configuration> +That Logback configuration file: + + +Logs information from the application in a JSON format to a build/${spring.application.name}.json file. + + +Has commented out two additional appenders: console and standard log file. + + +Has the same logging pattern as the one presented in the previous section. + + -If you’re using a custom logback-spring.xml then you have to pass the spring.application.name in -bootstrap instead of application property file. Otherwise your custom logback file won’t read the property properly. +If you use a custom logback-spring.xml, you must pass the spring.application.name in the bootstrap rather than the application property file. +Otherwise, your custom logback file does not properly read the property.
    Propagating Span Context -The span context is the state that must get propagated to any child Spans across process boundaries. +The span context is the state that must get propagated to any child spans across process boundaries. Part of the Span Context is the Baggage. The trace and span IDs are a required part of the span context. Baggage is an optional part. -Baggage is a set of key:value pairs stored in the span context. Baggage travels together with the trace -and is attached to every span. Spring Cloud Sleuth will understand that a header is baggage related if the HTTP - header is prefixed with baggage- and for messaging it starts with baggage_. +Baggage is a set of key:value pairs stored in the span context. +Baggage travels together with the trace and is attached to every span. +Spring Cloud Sleuth understands that a header is baggage-related if the HTTP header is prefixed with baggage- and, for messaging, it starts with baggage_. -There’s currently no limitation of the count or size of baggage items. However, keep in mind that -too many can decrease system throughput or increase RPC latency. In extreme cases, it could crash the app due -to exceeding transport-level message or header capacity. +There is currently no limitation of the count or size of baggage items. +However, keep in mind that too many can decrease system throughput or increase RPC latency. +In extreme cases, too much baggage can crash the application, due to exceeding transport-level message or header capacity. -Example of setting baggage on a span: -Span initialSpan = this.tracer.createSpan("span"); -initialSpan.setBaggageItem("foo", "bar"); -initialSpan.setBaggageItem("UPPER_CASE", "someValue"); -
    -Baggage vs. Span Tags -Baggage travels with the trace (i.e. every child span contains the baggage of its parent). Zipkin has no knowledge of -baggage and will not even receive that information. -Tags are attached to a specific span - they are presented for that particular span only. However you -can search by tag to find the trace, where there exists a span having the searched tag value. -If you want to be able to lookup a span based on baggage, you should add corresponding entry as a tag in the root span. -@Autowired Tracer tracer; - -Span span = tracer.getCurrentSpan(); -String baggageKey = "key"; -String baggageValue = "foo"; -span.setBaggageItem(baggageKey, baggageValue); -tracer.addTag(baggageKey, baggageValue); -
    -
    -
    -
    -Adding to the project +The following example shows setting baggage on a span: +Span initialSpan = this.tracer.nextSpan().name("span").start(); +try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(initialSpan)) { + ExtraFieldPropagation.set("foo", "bar"); + ExtraFieldPropagation.set("UPPER_CASE", "someValue"); +} +
    +Baggage versus Span Tags +Baggage travels with the trace (every child span contains the baggage of its parent). +Zipkin has no knowledge of baggage and does not receive that information. -To ensure that your application name is properly displayed in Zipkin - set the spring.application.name property in bootstrap.yml. +Starting from Sleuth 2.0.0 you have to pass the baggage key names explicitly +in your project configuration. Read more about that setup here + +Tags are attached to a specific span. In other words, they are presented only for that particular span. +However, you can search by tag to find the trace, assuming a span having the searched tag value exists. +If you want to be able to lookup a span based on baggage, you should add a corresponding entry as a tag in the root span. + +The span must be in scope. + +The following listing shows integration tests that use baggage: + +The setup + +spring.sleuth: + baggage-keys: + - baz + - bizarrecase + propagation-keys: + - foo + - upper_case + + + +The code + +initialSpan.tag("foo", + ExtraFieldPropagation.get(initialSpan.context(), "foo")); +initialSpan.tag("UPPER_CASE", + ExtraFieldPropagation.get(initialSpan.context(), "UPPER_CASE")); + + +
    +
    + +
    +Adding Sleuth to the Project +This section addresses how to add Sleuth to your project with either Maven or Gradle. + +To ensure that your application name is properly displayed in Zipkin, set the spring.application.name property in bootstrap.yml.
    Only Sleuth (log correlation) -If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add -the spring-cloud-starter-sleuth module to your project. +If you want to use only Spring Cloud Sleuth without the Zipkin integration, add the spring-cloud-starter-sleuth module to your project. +The following example shows how to add Sleuth with Maven: Maven <dependencyManagement> - <dependencies> - <dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-dependencies</artifactId> - <version>${release.train.version}</version> - <type>pom</type> - <scope>import</scope> - </dependency> - </dependencies> - </dependencyManagement> + <dependencies> + <dependency> + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-dependencies</artifactId> + <version>${release.train.version}</version> + <type>pom</type> + <scope>import</scope> + </dependency> + </dependencies> +</dependencyManagement> - <dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-starter-sleuth</artifactId> - </dependency> +<dependency> + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-sleuth</artifactId> +</dependency> -In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM +We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself. -Add the dependency to spring-cloud-starter-sleuth +Add the dependency to spring-cloud-starter-sleuth. +The following example shows how to add Sleuth with Gradle: Gradle @@ -424,47 +463,47 @@ dependencies { -In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM +We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself. -Add the dependency to spring-cloud-starter-sleuth +Add the dependency to spring-cloud-starter-sleuth.
    Sleuth with Zipkin via HTTP -If you want both Sleuth and Zipkin just add the spring-cloud-starter-zipkin dependency. +If you want both Sleuth and Zipkin, add the spring-cloud-starter-zipkin dependency. +The following example shows how to do so for Maven: Maven <dependencyManagement> - <dependencies> - <dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-dependencies</artifactId> - <version>${release.train.version}</version> - <type>pom</type> - <scope>import</scope> - </dependency> - </dependencies> - </dependencyManagement> + <dependencies> + <dependency> + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-dependencies</artifactId> + <version>${release.train.version}</version> + <type>pom</type> + <scope>import</scope> + </dependency> + </dependencies> +</dependencyManagement> - <dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-starter-zipkin</artifactId> - </dependency> +<dependency> + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-zipkin</artifactId> +</dependency> -In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM +We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself. -Add the dependency to spring-cloud-starter-zipkin +Add the dependency to spring-cloud-starter-zipkin. +The following example shows how to do so for Gradle: Gradle @@ -481,56 +520,59 @@ dependencies { -In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM +We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself. -Add the dependency to spring-cloud-starter-zipkin +Add the dependency to spring-cloud-starter-zipkin.
    -
    -Sleuth with Zipkin via RabbitMQ or Kafka -If you want to use RabbitMQ or Kafka instead of http, add the spring-rabbit or spring-kafka -dependencies. The default destination name is zipkin. -Note: spring-cloud-sleuth-stream is deprecated and incompatible with these destinations -If you want Sleuth over RabbitMQ add the spring-cloud-starter-zipkin and spring-rabbit +
    +Sleuth with Zipkin over RabbitMQ or Kafka +If you want to use RabbitMQ or Kafka instead of HTTP, add the spring-rabbit or spring-kafka dependency. +The default destination name is zipkin. +If using Kafka, you must set the property spring.zipkin.sender.type property accordingly: +spring.zipkin.sender.type: kafka + +spring-cloud-sleuth-stream is deprecated and incompatible with these destinations. + +If you want Sleuth over RabbitMQ, add the spring-cloud-starter-zipkin and spring-rabbit dependencies. +The following example shows how to do so for Gradle: Maven <dependencyManagement> - <dependencies> - <dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-dependencies</artifactId> - <version>${release.train.version}</version> - <type>pom</type> - <scope>import</scope> - </dependency> - </dependencies> - </dependencyManagement> + <dependencies> + <dependency> + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-dependencies</artifactId> + <version>${release.train.version}</version> + <type>pom</type> + <scope>import</scope> + </dependency> + </dependencies> +</dependencyManagement> - <dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-starter-zipkin</artifactId> - </dependency> - <dependency> - <groupId>org.springframework.amqp</groupId> - <artifactId>spring-rabbit</artifactId> - </dependency> +<dependency> + <groupId>org.springframework.cloud</groupId> + <artifactId>spring-cloud-starter-zipkin</artifactId> +</dependency> +<dependency> + <groupId>org.springframework.amqp</groupId> + <artifactId>spring-rabbit</artifactId> +</dependency> -In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM +We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself. -Add the dependency to spring-cloud-starter-zipkin - that way all dependent dependencies will be downloaded +Add the dependency to spring-cloud-starter-zipkin. That way, all nested dependencies get downloaded. -To automatically configure rabbit, simply add the spring-rabbit dependency +To automatically configure RabbitMQ, add the spring-rabbit dependency. @@ -550,323 +592,689 @@ dependencies { -In order not to pick versions by yourself it’s much better if you add the dependency management via -the Spring BOM +We recommend that you add the dependency management through the Spring BOM so that you need not manage versions yourself. -Add the dependency to spring-cloud-starter-zipkin - that way all dependent dependencies will be downloaded +Add the dependency to spring-cloud-starter-zipkin. That way, all nested dependencies get downloaded. -To automatically configure rabbit, simply add the spring-rabbit dependency +To automatically configure RabbitMQ, add the spring-rabbit dependency.
    -Additional resources -Marcin Grzejszczak talking about Spring Cloud Sleuth and Zipkin - -click here to see the video +Additional Resources +You can watch a video of Reshmi Krishna and Marcin Grzejszczak talking about Spring Cloud +Sleuth and Zipkin by clicking here. +You can check different setups of Sleuth and Brave in the openzipkin/sleuth-webmvc-example repository. Features -Adds trace and span ids to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator. Example logs: +Adds trace and span IDs to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator, as shown in the following example logs: 2016-02-02 15:30:57.902 INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ... 2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ... 2016-02-02 15:31:01.936 INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ... -notice the [appname,traceId,spanId,exportable] entries from the MDC: +Notice the [appname,traceId,spanId,exportable] entries from the MDC: -spanId - the id of a specific operation that took place +spanId: The ID of a specific operation that took place. -appname - the name of the application that logged the span +appname: The name of the application that logged the span. -traceId - the id of the latency graph that contains the span +traceId: The ID of the latency graph that contains the span. -exportable - whether the log should be exported to Zipkin or not. When would you like the span not to be -exportable? In the case in which you want to wrap some operation in a Span and have it written to the logs -only. +exportable: Whether the log should be exported to Zipkin. +When would you like the span not to be exportable? +When you want to wrap some operation in a Span and have it written to the logs only. -Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations, -key-value annotations. Loosely based on HTrace, but Zipkin (Dapper) compatible. +Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations, and key-value annotations. +Spring Cloud Sleuth is loosely based on HTrace but is compatible with Zipkin (Dapper). -Sleuth records timing information to aid in latency analysis. Using sleuth, you can pinpoint causes of -latency in your applications. Sleuth is written to not log too much, and to not cause your production application to crash. +Sleuth records timing information to aid in latency analysis. +By using sleuth, you can pinpoint causes of latency in your applications. + + +Sleuth is written to not log too much and to not cause your production application to crash. +To that end, Sleuth: -propagates structural data about your call-graph in-band, and the rest out-of-band. +Propagates structural data about your call graph in-band and the rest out-of-band. -includes opinionated instrumentation of layers such as HTTP +Includes opinionated instrumentation of layers such as HTTP. -includes sampling policy to manage volume +Includes a sampling policy to manage volume. -can report to a Zipkin system for query and visualization +Can report to a Zipkin system for query and visualization. -Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints, -rest template, scheduled actions, message channels, zuul filters, feign client). +Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints, rest template, scheduled actions, message channels, Zuul filters, and Feign client). -Sleuth includes default logic to join a trace across http or messaging boundaries. For example, http propagation -works via Zipkin-compatible request headers. This propagation logic is defined and customized via -SpanInjector and SpanExtractor implementations. +Sleuth includes default logic to join a trace across HTTP or messaging boundaries. +For example, HTTP propagation works over Zipkin-compatible request headers. -Sleuth gives you the possibility to propagate context (also known as baggage) between processes. That means that if you set on a Span -a baggage element then it will be sent downstream either via HTTP or messaging to other processes. +Sleuth can propagate context (also known as baggage) between processes. +Consequently, if you set a baggage element on a Span, it is sent downstream to other processes over either HTTP or messaging. -Provides a way to create / continue spans and add tags and logs via annotations. +Provides a way to create or continue spans and add tags and logs through annotations. -Provides simple metrics of accepted / dropped spans. - - -If spring-cloud-sleuth-zipkin then the app will generate and collect Zipkin-compatible traces. -By default it sends them via HTTP to a Zipkin server on localhost (port 9411). -Configure the location of the service using spring.zipkin.baseUrl. +If spring-cloud-sleuth-zipkin is on the classpath, the app generates and collects Zipkin-compatible traces. +By default, it sends them over HTTP to a Zipkin server on localhost (port 9411). +You can configure the location of the service by setting spring.zipkin.baseUrl. -If you depend on spring-rabbit or spring-kafka your app will send traces to a broker instead of http. +If you depend on spring-rabbit, your app sends traces to a RabbitMQ broker instead of HTTP. -Note: spring-cloud-sleuth-stream is deprecated and should no longer be used. +If you depend on spring-kafka, and set spring.zipkin.sender.type: kafka, your app sends traces to a Kafka broker instead of HTTP. + +spring-cloud-sleuth-stream is deprecated and should no longer be used. + + + +Spring Cloud Sleuth is OpenTracing compatible. + + -If using Zipkin, configure the percentage of spans exported using spring.sleuth.sampler.percentage -(default 0.1, i.e. 10%). Otherwise you might think that Sleuth is not working cause it’s omitting some spans. +If you use Zipkin, configure the probability of spans exported by setting spring.sleuth.sampler.probability +(default: 0.1, which is 10 percent). Otherwise, you might think that Sleuth is not working be cause it omits some spans. -the SLF4J MDC is always set and logback users will immediately see the trace and span ids in logs per the example - above. Other logging systems have to configure their own formatter to get the same result. The default is - logging.pattern.level set to %5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}] - (this is a Spring Boot feature for logback users). - This means that if you’re not using SLF4J this pattern WILL NOT be automatically applied. +The SLF4J MDC is always set and logback users immediately see the trace and span IDs in logs per the example +shown earlier. +Other logging systems have to configure their own formatter to get the same result. +The default is as follows: +logging.pattern.level set to %5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}] +(this is a Spring Boot feature for logback users). +If you do not use SLF4J, this pattern is NOT automatically applied. +
    +Introduction to Brave + +Starting with version 2.0.0, Spring Cloud Sleuth uses +Brave as the tracing library. +For your convenience, we embed part of the Brave’s docs here. + + +In the vast majority of cases you need to just use the Tracer +or SpanCustomizer beans from Brave that Sleuth provides. The documentation below contains +a high overview of what Brave is and how it works. + +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. +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). +
    +Tracing +Most importantly, you need a brave.Tracer, configured to report to Zipkin. +The following example setup sends trace data (spans) to Zipkin over HTTP (as opposed to Kafka): +class MyClass { + + private final Tracer tracer; + + // Tracer will be autowired + MyClass(Tracer tracer) { + this.tracer = tracer; + } + + void doSth() { + Span span = tracer.newTrace().name("encode").start(); + // ... + } +} + +If your span contains a name longer than 50 chars, then that name is truncated to 50 chars. +Your names have to be explicit and concrete. +Big names lead to latency issues and sometimes even thrown exceptions. + +The tracer creates and joins spans that model the latency of potentially distributed work. +It can employ sampling to reduce overhead during the process, to reduce the amount of data sent to Zipkin, or both. +Spans returned by a tracer report data to Zipkin when finished or do nothing if unsampled. +After starting a span, you can annotate events of interest or add tags containing details or lookup keys. +Spans have a context that includes trace identifiers that place the span at the correct spot in the tree representing the distributed operation. +
    +
    +Local Tracing +When tracing local code, you can run it inside a span, as shown in the following example: +@Autowired Tracer tracer; + +Span span = tracer.newTrace().name("encode").start(); +try { + doSomethingExpensive(); +} finally { + span.finish(); +} +In the preceding example, the span is the root of the trace. +In many cases, the span is part of an existing trace. +When this is the case, call newChild instead of newTrace, as shown in the following example: +@Autowired Tracer tracer; + +Span span = tracer.newChild(root.context()).name("encode").start(); +try { + doSomethingExpensive(); +} finally { + span.finish(); +} +
    +
    +Customizing Spans +Once you have a span, you can add tags to it. +The tags can be used as lookup keys or details. +For example, you might add a tag with your runtime version, as shown in the following example: +span.tag("clnt/finagle.version", "6.36.0"); +When exposing the ability to customize spans to third parties, prefer brave.SpanCustomizer as opposed to brave.Span. +The former is simpler to understand and test and does not tempt users with span lifecycle hooks. +interface MyTraceCallback { + void request(Request request, SpanCustomizer customizer); +} +Since brave.Span implements brave.SpanCustomizer, you can pass it to users, as shown in the following example: +for (MyTraceCallback callback : userCallbacks) { + callback.request(request, span); +} +
    +
    +Implicitly Looking up the Current Span +Sometimes, you do not know if a trace is in progress or not, and you do not want users to do null checks. +brave.CurrentSpanCustomizer handles this problem by adding data to any span that’s in progress or drops, as shown in the following example: +Ex. +// The user code can then inject this without a chance of it being null. +@Autowired SpanCustomizer span; + +void userCode() { + span.annotate("tx.started"); + ... +} +
    +
    +RPC tracing + +Check for instrumentation written here and Zipkin’s list before rolling your own RPC instrumentation. + +RPC tracing is often done automatically by interceptors. Behind the scenes, they add tags and events that relate to their role in an RPC operation. +The following example shows how to add a client span: +@Autowired Tracer tracer; + +// before you send a request, add metadata that describes the operation +span = tracer.newTrace().name("get").type(CLIENT); +span.tag("clnt/finagle.version", "6.36.0"); +span.tag(TraceKeys.HTTP_PATH, "/api"); +span.remoteEndpoint(Endpoint.builder() + .serviceName("backend") + .ipv4(127 << 24 | 1) + .port(8080).build()); + +// when the request is scheduled, start the span +span.start(); + +// if you have callbacks for when data is on the wire, note those events +span.annotate(Constants.WIRE_SEND); +span.annotate(Constants.WIRE_RECV); + +// when the response is complete, finish the span +span.finish(); +
    +One-Way tracing +Sometimes, you need to model an asynchronous operation where there is a +request but no response. In normal RPC tracing, you use span.finish() +to indicate that the response was received. In one-way tracing, you use +span.flush() instead, as you do not expect a response. +The following example shows how a client might model a one-way operation: +@Autowired Tracer tracer; + +// start a new span representing a client request +oneWaySend = tracer.newSpan(parent).kind(Span.Kind.CLIENT); + +// Add the trace context to the request, so it can be propagated in-band +tracing.propagation().injector(Request::addHeader) + .inject(oneWaySend.context(), request); + +// fire off the request asynchronously, totally dropping any response +request.execute(); + +// start the client side and flush instead of finish +oneWaySend.start().flush(); +The following example shows how a server might handle a one-way operation: +@Autowired Tracing tracing; +@Autowired Tracer tracer; + +// pull the context out of the incoming request +extractor = tracing.propagation().extractor(Request::getHeader); + +// convert that context to a span which you can name and add tags to +oneWayReceive = nextSpan(tracer, extractor.extract(request)) + .name("process-request") + .kind(SERVER) + ... add tags etc. + +// start the server side and flush instead of finish +oneWayReceive.start().flush(); + +// you should not modify this span anymore as it is complete. However, +// you can create children to represent follow-up work. +next = tracer.newSpan(oneWayReceive.context()).name("step2").start(); +
    +
    +
     Sampling -In distributed tracing the data volumes can be very high so sampling -can be important (you usually don’t need to export all spans to get a -good picture of what is happening). Spring Cloud Sleuth has a -Sampler strategy that you can implement to take control of the -sampling algorithm. Samplers do not stop span (correlation) ids from -being generated, but they do prevent the tags and events being -attached and exported. By default you get a strategy that continues to -trace if a span is already active, but new ones are always marked as -non-exportable. If all your apps run with this sampler you will see -traces in logs, but not in any remote store. For testing the default -is often enough, and it probably is all you need if you are only using -the logs (e.g. with an ELK aggregator). If you are exporting span data -to Zipkin or Spring Cloud Stream, there is also an AlwaysSampler -that exports everything and a PercentageBasedSampler that samples a -fixed fraction of spans. +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). +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. +By default, a global sampler applies a single rate to all traced operations. +Tracer.Builder.sampler controls this setting, and it defaults to tracing every request. +
    +Declarative sampling +Some applications need to sample based on the type or annotations of a java method. +Most users use a framework interceptor to automate this sort of policy. +The following example shows how that might work internally: +@Autowired Tracing tracing; + +// derives a sample rate from an annotation on a java method +DeclarativeSampler<Traced> sampler = DeclarativeSampler.create(Traced::sampleRate); + +@Around("@annotation(traced)") +public Object traceThing(ProceedingJoinPoint pjp, Traced traced) throws Throwable { + Span span = tracing.tracer().newTrace(sampler.sample(traced))... + try { + return pjp.proceed(); + } finally { + span.finish(); + } +} +
    +
    +Custom sampling +Depending on what the operation is, you may want to apply different policies. +For example, you might not want to trace requests to static resources such as images, or you might want to trace all requests to a new api. +Most users use a framework interceptor to automate this sort of policy. +The following example shows how that might work internally: +@Autowired Tracer tracer; + +Span newTrace(Request input) { + SamplingFlags flags = SamplingFlags.NONE; + if (input.url().startsWith("/experimental")) { + flags = SamplingFlags.SAMPLED; + } else if (input.url().startsWith("/static")) { + flags = SamplingFlags.NOT_SAMPLED; + } + return tracer.newTrace(flags); +} +
    +
    +Sampling in Spring Cloud Sleuth +By default Spring Cloud Sleuth sets all spans to non-exportable. +That means that traces appear in logs but not in any remote store. +For testing the default is often enough, and it probably is all you need if you use only the logs (for example, with an ELK aggregator). +If you export span data to Zipkin, there is also an Sampler.ALWAYS_SAMPLE setting that exports everything and a ProbabilityBasedSampler setting that samples a fixed fraction of spans. -the PercentageBasedSampler is the default if you are using -spring-cloud-sleuth-zipkin or spring-cloud-sleuth-stream. You can -configure the exports using spring.sleuth.sampler.percentage. The passed -value needs to be a double from 0.0 to 1.0 so it’s not a percentage. -For backwards compatibility reasons we’re not changing the property name. +The ProbabilityBasedSampler is the default if you use spring-cloud-sleuth-zipkin. +You can configure the exports by setting spring.sleuth.sampler.probability. +The passed value needs to be a double from 0.0 to 1.0. -A sampler can be installed just by creating a bean definition, e.g: +A sampler can be installed by creating a bean definition, as shown in the following example: @Bean public Sampler defaultSampler() { - return new AlwaysSampler(); + return Sampler.ALWAYS_SAMPLE; } -You can set the HTTP header X-B3-Flags to 1 or when doing messaging you can -set spanFlags header to 1. Then the current span will be forced to be exportable -regardless of the sampling decision. +You can set the HTTP header X-B3-Flags to 1, or, when doing messaging, you can set the spanFlags header to 1. +Doing so forces the current span to be exportable regardless of the sampling decision. +
    +     + +Propagation +Propagation is needed to ensure activities originating from the same root are collected together in the same trace. +The most common propagation approach is to copy a trace context from a client by sending an RPC request to a server receiving it. +For example, when a downstream HTTP call is made, its trace context is encoded as request headers and sent along with it, as shown in the following image: + Client Span Server Span +┌──────────────────┐ ┌──────────────────┐ +│ │ │ │ +│ TraceContext │ Http Request Headers │ TraceContext │ +│ ┌──────────────┐ │ ┌───────────────────┐ │ ┌──────────────┐ │ +│ │ TraceId │ │ │ X─B3─TraceId │ │ │ TraceId │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ ParentSpanId │ │ Extract │ X─B3─ParentSpanId │ Inject │ │ ParentSpanId │ │ +│ │ ├─┼─────────>│ ├────────┼>│ │ │ +│ │ SpanId │ │ │ X─B3─SpanId │ │ │ SpanId │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ Sampled │ │ │ X─B3─Sampled │ │ │ Sampled │ │ +│ └──────────────┘ │ └───────────────────┘ │ └──────────────┘ │ +│ │ │ │ +└──────────────────┘ └──────────────────┘ +The names above are from B3 Propagation, which is built-in to Brave and has implementations in many languages and frameworks. +Most users use a framework interceptor to automate propagation. +The next two examples show how that might work for a client and a server. +The following example shows how client-side propagation might work: +@Autowired Tracing tracing; + +// configure a function that injects a trace context into a request +injector = tracing.propagation().injector(Request.Builder::addHeader); + +// before a request is sent, add the current span's context to it +injector.inject(span.context(), request); +The following example shows how server-side propagation might work: +@Autowired Tracing tracing; +@Autowired Tracer tracer; + +// configure a function that extracts the trace context from a request +extractor = tracing.propagation().extractor(Request::getHeader); + +// when a server receives a request, it joins or starts a new trace +span = tracer.nextSpan(extractor.extract(request)); +
    +Propagating extra fields +Sometimes you need to propagate extra fields, such as a request ID or an alternate trace context. +For example, if you are in a Cloud Foundry environment, you might want to pass the request ID, as shown in the following example: +// when you initialize the builder, define the extra field you want to propagate +Tracing.newBuilder().propagationFactory( + ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-vcap-request-id") +); + +// later, you can tag that request ID or use it in log correlation +requestId = ExtraFieldPropagation.get("x-vcap-request-id"); +You may also need to propagate a trace context that you are not using. +For example, you may be in an Amazon Web Services environment but not be reporting data to X-Ray. +To ensure X-Ray can co-exist correctly, pass-through its tracing header, as shown in the following example: +tracingBuilder.propagationFactory( + ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "x-amzn-trace-id") +); + +In Spring Cloud Sleuth all elements of the tracing builder Tracing.newBuilder() +are defined as beans. So if you want to pass a custom PropagationFactory, it’s enough +for you to create a bean of that type and we will set it in the Tracing bean. + +
    +Prefixed fields +If they follow a common pattern, you can also prefix fields. +The following example shows how to propagate x-vcap-request-id the field as-is but send the country-code and user-id fields on the wire as x-baggage-country-code and x-baggage-user-id, respectively: +Tracing.newBuilder().propagationFactory( + ExtraFieldPropagation.newFactoryBuilder(B3Propagation.FACTORY) + .addField("x-vcap-request-id") + .addPrefixedFields("baggage-", Arrays.asList("country-code", "user-id")) + .build() +); +Later, you can call the following code to affect the country code of the current trace context: +ExtraFieldPropagation.set("country-code", "FO"); +String countryCode = ExtraFieldPropagation.get("country-code"); +Alternatively, if you have a reference to a trace context, you can use it explicitly, as shown in the following example: +ExtraFieldPropagation.set(span.context(), "country-code", "FO"); +String countryCode = ExtraFieldPropagation.get(span.context(), "country-code"); + +A difference from previous versions of Sleuth is that, with Brave, you must pass the list of baggage keys. +There are two properties to achieve this. +With the spring.sleuth.baggage-keys, you set keys that get prefixed with baggage- for HTTP calls and baggage_ for messaging. +You can also use the spring.sleuth.propagation-keys property to pass a list of prefixed keys that are whitelisted without any prefix. + +
    +
    +Extracting a Propagated Context +The TraceContext.Extractor<C> reads trace identifiers and sampling status from an incoming request or message. +The carrier is usually a request object or headers. +This utility is used in standard instrumentation (such as HttpServerHandler`) but can also be used for custom RPC or messaging code. +TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are +sharing span IDs between a client and a server. +
    +
    +Sharing span IDs between Client and Server +A normal instrumentation pattern is to create a span representing the server side of an RPC. +Extractor.extract might return a complete trace context when applied to an incoming client request. +Tracer.joinSpan attempts to continue this trace, using the same span ID if supported or creating a child span +if not. When the span ID is shared, the reported data includes a flag saying so. +The following image shows an example of B3 propagation: + ┌───────────────────┐ ┌───────────────────┐ + Incoming Headers │ TraceContext │ │ TraceContext │ +┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │ +│ X─B3-TraceId │─────────┼─┼> TraceId │ │──────┼─┼> TraceId │ │ +│ │ │ │ │ │ │ │ │ │ +│ X─B3-ParentSpanId │─────────┼─┼> ParentSpanId │ │──────┼─┼> ParentSpanId │ │ +│ │ │ │ │ │ │ │ │ │ +│ X─B3-SpanId │─────────┼─┼> SpanId │ │──────┼─┼> SpanId │ │ +└───────────────────┘ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ Shared: true │ │ + │ └───────────────┘ │ │ └───────────────┘ │ + └───────────────────┘ └───────────────────┘ +Some propagation systems forward only the parent span ID, detected when Propagation.Factory.supportsJoin() == false. +In this case, a new span ID is always provisioned, and the incoming context determines the parent ID. +The following image shows an example of AWS propagation: + ┌───────────────────┐ ┌───────────────────┐ + x-amzn-trace-id │ TraceContext │ │ TraceContext │ +┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │ +│ Root │─────────┼─┼> TraceId │ │──────┼─┼> TraceId │ │ +│ │ │ │ │ │ │ │ │ │ +│ Parent │─────────┼─┼> SpanId │ │──────┼─┼> ParentSpanId │ │ +└───────────────────┘ │ └───────────────┘ │ │ │ │ │ + └───────────────────┘ │ │ SpanId: New │ │ + │ └───────────────┘ │ + └───────────────────┘ +Note: Some span reporters do not support sharing span IDs. +For example, if you set Tracing.Builder.spanReporter(amazonXrayOrGoogleStackdrive), you should disable join by setting Tracing.Builder.supportsJoin(false). +Doing so forces a new child span on Tracer.joinSpan(). +
    +
    +Implementing Propagation +TraceContext.Extractor<C> is implemented by a Propagation.Factory plugin. +Internally, this code creates the union type, TraceContextOrSamplingFlags, with one of the following: +* TraceContext if trace and span IDs were present. +* TraceIdContext if a trace ID was present but span IDs were not present. +* SamplingFlags if no identifiers were present. +Some Propagation implementations carry extra data from the point of extraction (for example, reading incoming headers) to injection (for example, writing outgoing headers). +For example, it might carry a request ID. +When implementations have extra data, they handle it as follows: +* If a TraceContext were extracted, add the extra data as TraceContext.extra(). +* Otherwise, add it as TraceContextOrSamplingFlags.extra(), which Tracer.nextSpan handles. +
    +
    +     + +Current Tracing Component +Brave supports a "current tracing component" concept, which should only be used when you have no other way to get a reference. +This was made for JDBC connections, as they often initialize prior to the tracing component. +The most recent tracing component instantiated is available through Tracing.current(). +You can also use Tracing.currentTracer() to get only the tracer. +If you use either of these methods, do not cache the result. +Instead, look them up each time you need them. + + +Current Span +Brave supports a "current span" concept which represents the in-flight operation. +You can use Tracer.currentSpan() to add custom tags to a span and Tracer.nextSpan() to create a child of whatever is in-flight. + +In Sleuth, you can autowire the Tracer bean to retrieve the current span via +tracer.currentSpan() method. To retrieve the current context just call +tracer.currentSpan().context(). To get the current trace id as String +you can use the traceIdString() method like this: tracer.currentSpan().context().traceIdString(). + +
    +Setting a span in scope manually +When writing new instrumentation, it is important to place a span you created in scope as the current span. +Not only does doing so let users access it with Tracer.currentSpan(), but it also allows customizations such as SLF4J MDC to see the current trace IDs. +Tracer.withSpanInScope(Span) facilitates this and is most conveniently employed by using the try-with-resources idiom. +Whenever external code might be invoked (such as proceeding an interceptor or otherwise), place the span in scope, as shown in the following example: +@Autowired Tracer tracer; + +try (SpanInScope ws = tracer.withSpanInScope(span)) { + return inboundRequest.invoke(); +} finally { // note the scope is independent of the span + span.finish(); +} +In edge cases, you may need to clear the current span temporarily (for example, launching a task that should not be associated with the current request). To do tso, pass null to withSpanInScope, as shown in the following example: +@Autowired Tracer tracer; + +try (SpanInScope cleared = tracer.withSpanInScope(null)) { + startBackgroundThread(); +} +
     Instrumentation -Spring Cloud Sleuth instruments all your Spring application -automatically, so you shouldn’t have to do anything to activate -it. The instrumentation is added using a variety of technologies -according to the stack that is available, e.g. for a servlet web -application we use a Filter, and for Spring Integration we use -ChannelInterceptors. -You can customize the keys used in span tags. To limit the volume of -span data, by default an HTTP request will be tagged only with a -handful of metadata like the status code, host and URL. You can add -request headers by configuring spring.sleuth.keys.http.headers (a -list of header names). +Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it. +The instrumentation is added by using a variety of technologies according to the stack that is available. For example, for a servlet web application, we use a Filter, and, for Spring Integration, we use ChannelInterceptors. +You can customize the keys used in span tags. +To limit the volume of span data, an HTTP request is, by default, tagged only with a handful of metadata, such as the status code, the host, and the URL. +You can add request headers by configuring spring.sleuth.keys.http.headers (a list of header names). -Remember that tags are only collected and exported if there is a -Sampler that allows it (by default there is not, so there is no -danger of accidentally collecting too much data without configuring -something). - - -Currently the instrumentation in Spring Cloud Sleuth is eager - it means that -we’re actively trying to pass the tracing context between threads. Also timing events -are captured even when sleuth isn’t exporting data to a tracing system. -This approach may change in the future towards being lazy on this matter. +Tags are collected and exported only if there is a Sampler that allows it. By default, there is no such Sampler, to ensure that there is no danger of accidentally collecting too much data without configuring something). Span lifecycle -You can do the following operations on the Span by means of org.springframework.cloud.sleuth.Tracer interface: +You can do the following operations on the Span by means of brave.Tracer: -start - when you start a span its name is assigned and start timestamp is recorded. +start: When you start a span, its name is assigned and the start timestamp is recorded. -close - the span gets finished (the end time of the span is recorded) and if -the span is exportable then it will be eligible for collection to Zipkin. -The span is also removed from the current thread. +close: The span gets finished (the end time of the span is recorded) and, if the span is sampled, it is eligible for collection (for example, to Zipkin). -continue - a new instance of span will be created whereas it will be a copy of the -one that it continues. +continue: A new instance of span is created. +It is a copy of the one that it continues. -detach - the span doesn’t get stopped or closed. It only gets removed from the current thread. +detach: The span does not get stopped or closed. +It only gets removed from the current thread. -create with explicit parent - you can create a new span and set an explicit parent to it +create with explicit parent: You can create a new span and set an explicit parent for it. -Spring creates the instance of Tracer for you. In order to use it all you need is to just autowire it. +Spring Cloud Sleuth creates an instance of Tracer for you. In order to use it, you can autowire it. -
    -Creating and closing spans -You can manually create spans by using the Tracer interface. +
    +Creating and finishing spans +You can manually create spans by using the Tracer, as shown in the following example: // Start a span. If there was a span present in this thread it will become // the `newSpan`'s parent. -Span newSpan = this.tracer.createSpan("calculateTax"); -try { +Span newSpan = this.tracer.nextSpan().name("calculateTax"); +try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(newSpan.start())) { // ... // You can tag a span - this.tracer.addTag("taxValue", taxValue); + newSpan.tag("taxValue", taxValue); // ... // You can log an event on a span - newSpan.logEvent("taxCalculated"); + newSpan.annotate("taxCalculated"); } finally { - // Once done remember to close the span. This will allow collecting + // Once done remember to finish the span. This will allow collecting // the span to send it to Zipkin - this.tracer.close(newSpan); + newSpan.finish(); } -In this example we could see how to create a new instance of span. Assuming that there already -was a span present in this thread then it would become the parent of that span. +In the preceding example, we could see how to create a new instance of the span. +If there is already a span in this thread, it becomes the parent of the new span. -Always clean after you create a span! Don’t forget to close a span if you want to send it to Zipkin. +Always clean after you create a span. Also, always finish any span that you want to send to Zipkin. -If your span contains a name greater than 50 chars, then that name will -be truncated to 50 chars. Your names have to be explicit and concrete. Big names lead to -latency issues and sometimes even thrown exceptions. +If your span contains a name greater than 50 chars, that name is truncated to 50 chars. +Your names have to be explicit and concrete. Big names lead to latency issues and sometimes even exceptions.
    -Continuing spans -Sometimes you don’t want to create a new span but you want to continue one. Example of such a -situation might be (of course it all depends on the use-case): +Continuing Spans +Sometimes, you do not want to create a new span but you want to continue one. An example of such a +situation might be as follows: -AOP - If there was already a span created before an aspect was reached then you might not want to create a new span. +AOP: If there was already a span created before an aspect was reached, you might not want to create a new span. -Hystrix - executing a Hystrix command is most likely a logical part of the current processing. It’s in fact -only a technical implementation detail that you wouldn’t necessarily want to reflect in tracing as a separate being. +Hystrix: Executing a Hystrix command is most likely a logical part of the current processing. +It is in fact merely a technical implementation detail that you would not necessarily want to reflect in tracing as a separate being. -The continued instance of span is equal to the one that it continues: -Span continuedSpan = this.tracer.continueSpan(spanToContinue); -assertThat(continuedSpan).isEqualTo(spanToContinue); -To continue a span you can use the Tracer interface. +To continue a span, you can use brave.Tracer, as shown in the following example: // let's assume that we're in a thread Y and we've received // the `initialSpan` from thread X -Span continuedSpan = this.tracer.continueSpan(initialSpan); +Span continuedSpan = this.tracer.toSpan(newSpan.context()); try { // ... // You can tag a span - this.tracer.addTag("taxValue", taxValue); + continuedSpan.tag("taxValue", taxValue); // ... // You can log an event on a span - continuedSpan.logEvent("taxCalculated"); + continuedSpan.annotate("taxCalculated"); } finally { - // Once done remember to detach the span. That way you'll - // safely remove it from the current thread without closing it - this.tracer.detach(continuedSpan); + // Once done remember to flush the span. That means that + // it will get reported but the span itself is not yet finished + continuedSpan.flush(); } - -Always clean after you create a span! Don’t forget to detach a span if some work was done started in one - thread (e.g. thread X) and it’s waiting for other threads (e.g. Y, Z) to finish. - Then the spans in the threads Y, Z should be detached at the end of their work. When the results are collected - the span in thread X should be closed. -
    -Creating spans with an explicit parent -There is a possibility that you want to start a new span and provide an explicit parent of that span. -Let’s assume that the parent of a span is in one thread and you want to start a new span in another thread. The -startSpan method of the Tracer interface is the method you are looking for. +Creating a Span with an explicit Parent +You might want to start a new span and provide an explicit parent of that span. +Assume that the parent of a span is in one thread and you want to start a new span in another thread. +In Brave, whenever you call nextSpan(), it creates a span in reference to the span that is currently in scope. +You can put the span in scope and then call nextSpan(), as shown in the following example: // let's assume that we're in a thread Y and we've received // the `initialSpan` from thread X. `initialSpan` will be the parent // of the `newSpan` -Span newSpan = this.tracer.createSpan("calculateCommission", initialSpan); -try { +Span newSpan = null; +try (Tracer.SpanInScope ws = this.tracer.withSpanInScope(initialSpan)) { + newSpan = this.tracer.nextSpan().name("calculateCommission"); // ... // You can tag a span - this.tracer.addTag("commissionValue", commissionValue); + newSpan.tag("commissionValue", commissionValue); // ... // You can log an event on a span - newSpan.logEvent("commissionCalculated"); + newSpan.annotate("commissionCalculated"); } finally { - // Once done remember to close the span. This will allow collecting + // Once done remember to finish the span. This will allow collecting // the span to send it to Zipkin. The tags and events set on the // newSpan will not be present on the parent - this.tracer.close(newSpan); + if (newSpan != null) { + newSpan.finish(); + } } -After having created such a span remember to close it. Otherwise you will see a lot of warnings in your logs - related to the fact that you have a span present in the current thread other than the one you’re trying to close. - What’s worse your spans won’t get closed properly thus will not get collected to Zipkin. +After creating such a span, you must finish it. Otherwise it is not reported (for example, to Zipkin).
    Naming spans -Picking a span name is not a trivial task. Span name should depict an operation name. The name should -be low cardinality (e.g. not include identifiers). -Since there is a lot of instrumentation going on some of the span names will be -artificial like: +Picking a span name is not a trivial task. A span name should depict an operation name. +The name should be low cardinality, so it should not include identifiers. +Since there is a lot of instrumentation going on, some span names are artificial: -controller-method-name when received by a Controller with a method name conrollerMethodName +controller-method-name when received by a Controller with a method name of controllerMethodName -async for asynchronous operations done via wrapped Callable and Runnable. +async for asynchronous operations done with wrapped Callable and Runnable interfaces. -@Scheduled annotated methods will return the simple name of the class. +Methods annotated with @Scheduled return the simple name of the class. -Fortunately, for the asynchronous processing you can provide explicit naming. -
    -@SpanName annotation -You can name the span explicitly via the @SpanName annotation. +Fortunately, for asynchronous processing, you can provide explicit naming. +
    +<literal>@SpanName</literal> Annotation +You can name the span explicitly by using the @SpanName annotation, as shown in the following example: @SpanName("calculateTax") class TaxCountingRunnable implements Runnable { @@ -874,20 +1282,21 @@ class TaxCountingRunnable implements Runnable { // perform logic } } -In this case, when processed in the following manner: -Runnable runnable = new TraceRunnable(tracer, spanNamer, new TaxCountingRunnable()); +In this case, when processed in the following manner, the span is named calculateTax: +Runnable runnable = new TraceRunnable(tracing, spanNamer, + new TaxCountingRunnable()); Future<?> future = executorService.submit(runnable); // ... some additional logic ... future.get(); -The span will be named calculateTax.
    -
    -toString() method -It’s pretty rare to create separate classes for Runnable or Callable. Typically one creates an anonymous -instance of those classes. You can’t annotate such classes thus to override that, if there is no @SpanName annotation present, -we’re checking if the class has a custom implementation of the toString() method. -So executing such code: -Runnable runnable = new TraceRunnable(tracer, spanNamer, new Runnable() { +
    +<literal>toString()</literal> method +It is pretty rare to create separate classes for Runnable or Callable. +Typically, one creates an anonymous instance of those classes. +You cannot annotate such classes. +To overcome that limitation, if there is no @SpanName annotation present, we check whether the class has a custom implementation of the toString() method. +Running such code leads to creating a span named calculateTax, as shown in the following example: +Runnable runnable = new TraceRunnable(tracing, spanNamer, new Runnable() { @Override public void run() { // perform logic } @@ -899,464 +1308,301 @@ we’re checking if the class has a custom implementation of the to Future<?> future = executorService.submit(runnable); // ... some additional logic ... future.get(); -will lead in creating a span named calculateTax.
    -Managing spans with annotations +Managing Spans with Annotations +You can manage spans with a variety of annotations.
    Rationale -The main arguments for this features are +There are a number of good reasons to manage spans with annotations, including: -api-agnostic means to collaborate with a span - - -use of annotations allows users to add to a span with no library dependency on a span api. -This allows Sleuth to change its core api less impact to user code. - - +API-agnostic means to collaborate with a span. Use of annotations lets users add to a span with no library dependency on a span api. +Doing so lets Sleuth change its core API to create less impact to user code. -reduced surface area for basic span operations. - - -without this feature one has to use the span api, which has lifecycle commands that -could be used incorrectly. By only exposing scope, tag and log functionality, users can -collaborate without accidentally breaking span lifecycle. - - +Reduced surface area for basic span operations. Without this feature, you must use the span api, which has lifecycle commands that could be used incorrectly. +By only exposing scope, tag, and log functionality, you can collaborate without accidentally breaking span lifecycle. -collaboration with runtime generated code - - -with libraries such as Spring Data / Feign the implementations of interfaces are generated -at runtime thus span wrapping of objects was tedious. Now you can provide annotations - over interfaces and arguments of those interfaces - - +Collaboration with runtime generated code. With libraries such as Spring Data and Feign, the implementations of interfaces are generated at runtime. +Consequently, span wrapping of objects was tedious. +Now you can provide annotations over interfaces and the arguments of those interfaces.
    -Creating new spans -If you really don’t want to take care of creating local spans manually you can profit from the -@NewSpan annotation. Also we give you the @SpanTag annotation to add tags in an automated -fashion. -Let’s look at some examples of usage. +Creating New Spans +If you do not want to create local spans manually, you can use the @NewSpan annotation. +Also, we provide the @SpanTag annotation to add tags in an automated fashion. +Now we can consider some examples of usage. @NewSpan void testMethod(); -Annotating the method without any parameter will lead to a creation of a new span whose name -will be equal to annotated method name. +Annotating the method without any parameter leads to creating a new span whose name equals the annotated method name. @NewSpan("customNameOnTestMethod4") void testMethod4(); -If you provide the value in the annotation (either directly or via the name parameter) then -the created span will have the name as the provided value. +If you provide the value in the annotation (either directly or by setting the name parameter), the created span has the provided value as the name. // method declaration @NewSpan(name = "customNameOnTestMethod5") void testMethod5(@SpanTag("testTag") String param); // and method execution this.testBean.testMethod5("test"); -You can combine both the name and a tag. Let’s focus on the latter. In this case whatever the value of -the annotated method’s parameter runtime value will be - that will be the value of the tag. In our sample -the tag key will be testTag and the tag value will be test. +You can combine both the name and a tag. Let’s focus on the latter. +In this case, the value of the annotated method’s parameter runtime value becomes the value of the tag. +In our sample, the tag key is testTag, and the tag value is test. @NewSpan(name = "customNameOnTestMethod3") @Override public void testMethod3() { } -You can place the @NewSpan annotation on both the class and an interface. If you override the -interface’s method and provide a different value of the @NewSpan annotation then the most -concrete one wins (in this case customNameOnTestMethod3 will be set). +You can place the @NewSpan annotation on both the class and an interface. +If you override the interface’s method and provide a different value for the @NewSpan annotation, the most +concrete one wins (in this case customNameOnTestMethod3 is set).
    -Continuing spans -If you want to just add tags and annotations to an existing span it’s enough -to use the @ContinueSpan annotation as presented below. Note that in contrast -with the @NewSpan annotation you can also add logs via the log parameter: +Continuing Spans +If you want to add tags and annotations to an existing span, you can use the @ContinueSpan annotation, as shown in the following example: // method declaration @ContinueSpan(log = "testMethod11") void testMethod11(@SpanTag("testTag11") String param); // method execution -this.testBean.testMethod11("test"); -That way the span will get continued and: +this.testBean.testMethod11("test"); +this.testBean.testMethod13(); +(Note that, in contrast with the @NewSpan annotation ,you can also add logs with the log parameter.) +That way, the span gets continued and: -logs with name testMethod11.before and testMethod11.after will be created +Log entries named testMethod11.before and testMethod11.after are created. -if an exception will be thrown a log testMethod11.afterFailure will also be created +If an exception is thrown, a log entry named testMethod11.afterFailure is also created. -tag with key testTag11 and value test will be created +A tag with a key of testTag11 and a value of test is created.
    -
    -More advanced tag setting +
    +Advanced Tag Setting There are 3 different ways to add tags to a span. All of them are controlled by the SpanTag annotation. -Precedence is: - +The precedence is as follows: + -try with the bean of TagValueResolver type and provided name +Try with a bean of TagValueResolver type and a provided name. -if one hasn’t provided the bean name, try to evaluate an expression. We’re searching for a TagValueExpressionResolver bean. -The default implementation uses SPEL expression resolution. +If the bean name has not been provided, try to evaluate an expression. +We search for a TagValueExpressionResolver bean. +The default implementation uses SPEL expression resolution. +IMPORTANT You can only reference properties from the SPEL expression. Method execution is not allowed due to security constraints. -if one hasn’t provided any expression to evaluate just return a toString() value of the parameter +If we do not find any expression to evaluate, return the toString() value of the parameter. - +
    Custom extractor -The value of the tag for following method will be computed by an implementation of TagValueResolver interface. +The value of the tag for the following method is computed by an implementation of TagValueResolver interface. Its class name has to be passed as the value of the resolver attribute. -Having such an annotated method: +Consider the following annotated method: @NewSpan public void getAnnotationForTagValueResolver(@SpanTag(key = "test", resolver = TagValueResolver.class) String test) { } -and such a TagValueResolver bean implementation +Now further consider the following TagValueResolver bean implementation: @Bean(name = "myCustomTagValueResolver") public TagValueResolver tagValueResolver() { return parameter -> "Value from myCustomTagValueResolver"; } -Will lead to setting of a tag value equal to Value from myCustomTagValueResolver. +The two preceding examples lead to setting a tag value equal to Value from myCustomTagValueResolver.
    -
    -Resolving expressions for value -Having such an annotated method: +
    +Resolving Expressions for a Value +Consider the following annotated method: @NewSpan -public void getAnnotationForTagValueExpression(@SpanTag(key = "test", expression = "length() + ' characters'") String test) { +public void getAnnotationForTagValueExpression(@SpanTag(key = "test", expression = "'hello' + ' characters'") String test) { } -and no custom implementation of a TagValueExpressionResolver will lead to evaluation of the SPEL expression and a tag with value 4 characters will be set on the span. -If you want to use some other expression resolution mechanism you can create your own implementation -of the bean. +No custom implementation of a TagValueExpressionResolver leads to evaluation of the SPEL expression, and a tag with a value of 4 characters is set on the span. +If you want to use some other expression resolution mechanism, you can create your own implementation of the bean.
    -
    -Using toString method -Having such an annotated method: +
    +Using the <literal>toString()</literal> method +Consider the following annotated method: @NewSpan public void getAnnotationForArgumentToString(@SpanTag("test") Long param) { } -if executed with a value of 15 will lead to setting of a tag with a String value of "15". +Running the preceding method with a value of 15 leads to setting a tag with a String value of "15".
    Customizations -Thanks to the SpanInjector and SpanExtractor you can customize the way spans -are created and propagated. -There are currently two built-in ways to pass tracing information between processes: - - -via Spring Integration - - -via HTTP - - -Span ids are extracted from Zipkin-compatible (B3) headers (either Message -or HTTP headers), to start or join an existing trace. Trace information is -injected into any outbound requests so the next hop can extract them. -The key change in comparison to the previous versions of Sleuth is that Sleuth is implementing -the Open Tracing’s TextMap notion. In Sleuth it’s called SpanTextMap. Basically the idea -is that any means of communication (e.g. message, http request, etc.) can be abstracted via -a SpanTextMap. This abstraction defines how one can insert data into the carrier and -how to retrieve it from there. Thanks to this if you want to instrument a new HTTP library -that uses a FooRequest as a mean of sending HTTP requests then you have to create an -implementation of a SpanTextMap that delegates calls to FooRequest in terms of retrieval -and insertion of HTTP headers. -
    -Spring Integration -For Spring Integration there are 2 interfaces responsible for creation of a Span from a Message. -These are: - - -MessagingSpanTextMapExtractor - - -MessagingSpanTextMapInjector - - -You can override them by providing your own implementation. -
    HTTP -For HTTP there are 2 interfaces responsible for creation of a Span from a Message. -These are: - - -HttpSpanExtractor - - -HttpSpanInjector - - -You can override them by providing your own implementation. +If a customization of client / server parsing of the HTTP related spans is required, +just register a bean of type brave.http.HttpClientParser or +brave.http.HttpServerParser. If client /server sampling is required, just +register a bean of type brave.http.HttpSampler and name the bean + sleuthClientSampler for client sampler and sleuthServerSampler for server sampler. + For your convenience the @ClientSampler and @ServerSampler + annotations can be used to inject the proper beans or to + reference the bean names via their static String NAME fields. +Check out Brave’s code to see an example of how to make a path-based sampler +https://github.com/openzipkin/brave/tree/master/instrumentation/http#sampling-policy +If you want to completely rewrite the HttpTracing bean you can use the SkipPatternProvider +interface to retrieve the URL Pattern for spans that should be not sampled. Below you can see +an example of usage of SkipPatternProvider inside a server side, HttpSampler. +@Configuration +class Config { + @Bean(name = ServerSampler.NAME) + HttpSampler myHttpSampler(SkipPatternProvider provider) { + Pattern pattern = provider.skipPattern(); + return new HttpSampler() { + + @Override public <Req> Boolean trySample(HttpAdapter<Req, ?> adapter, Req request) { + String url = adapter.path(request); + boolean shouldSkip = pattern.matcher(url).matches(); + if (shouldSkip) { + return false; + } + return null; + } + }; + } +}
    -
    -Example -Let’s assume that instead of the standard Zipkin compatible tracing HTTP header names -you have - - -for trace id - correlationId - - -for span id - mySpanId - - -This is a an example of a SpanExtractor -static class CustomHttpSpanExtractor implements HttpSpanExtractor { - - @Override public Span joinTrace(SpanTextMap carrier) { - Map<String, String> 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.traceIdString()); - carrier.put("mySpanId", Span.idToHex(span.getSpanId())); - } -} -And you could register it like this: -@Bean -HttpSpanInjector customHttpSpanInjector() { - return new CustomHttpSpanInjector(); -} - -@Bean -HttpSpanExtractor customHttpSpanExtractor() { - return new CustomHttpSpanExtractor(); -} -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 SpanInjector -that injects the headers into the Http Response and a Servlet filter which makes use of this can be added the following way: -static class CustomHttpServletResponseSpanInjector extends ZipkinHttpSpanInjector { - - @Override - public void inject(Span span, SpanTextMap carrier) { - super.inject(span, carrier); - carrier.put(Span.TRACE_ID_NAME, span.traceIdString()); - carrier.put(Span.SPAN_ID_NAME, Span.idToHex(span.getSpanId())); - } -} - -static class HttpResponseInjectingTraceFilter extends GenericFilterBean { +
    +<literal>TracingFilter</literal> +You can also modify the behavior of the TracingFilter, which is the component that is responsible for processing the input HTTP request and adding tags basing on the HTTP response. +You can customize the tags or modify the response headers by registering your own instance of the TracingFilter bean. +In the following example, we register the TracingFilter bean, add the ZIPKIN-TRACE-ID response header containing the current Span’s trace id, and add a tag with key custom and a value tag to the span. +@Component +@Order(TraceWebServletAutoConfiguration.TRACING_FILTER_ORDER + 1) +class MyFilter extends GenericFilterBean { private final Tracer tracer; - private final HttpSpanInjector spanInjector; - public HttpResponseInjectingTraceFilter(Tracer tracer, HttpSpanInjector spanInjector) { + MyFilter(Tracer tracer) { 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<Map.Entry<String, String>> iterator() { - Map<String, String> map = new HashMap<>(); - 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); - } - } -} -And you could register them like this: -@Bean HttpSpanInjector customHttpServletResponseSpanInjector() { - return new CustomHttpServletResponseSpanInjector(); -} - -@Bean -HttpResponseInjectingTraceFilter responseInjectingTraceFilter(Tracer tracer) { - return new HttpResponseInjectingTraceFilter(tracer, customHttpServletResponseSpanInjector()); -} -
    -
    -TraceFilter -You can also modify the behaviour of the TraceFilter - the component that is responsible -for processing the input HTTP request and adding tags basing on the HTTP response. You can customize -the tags, or modify the response headers by registering your own instance of the TraceFilter bean. -In the following example we will register the TraceFilter bean and we will add the -ZIPKIN-TRACE-ID response header containing the current Span’s trace id. Also we will -add to the Span a tag with key custom and a value tag. -@Bean -TraceFilter myTraceFilter(BeanFactory beanFactory, final Tracer tracer) { - return new TraceFilter(beanFactory) { - @Override protected void addResponseTags(HttpServletResponse response, - Throwable e) { - // execute the default behaviour - super.addResponseTags(response, e); - // for readability we're returning trace id in a hex form - response.addHeader("ZIPKIN-TRACE-ID", - Span.idToHex(tracer.getCurrentSpan().getTraceId())); - // we can also add some custom tags - tracer.addTag("custom", "tag"); + @Override public void doFilter(ServletRequest request, ServletResponse response, + FilterChain chain) throws IOException, ServletException { + Span currentSpan = this.tracer.currentSpan(); + if (currentSpan == null) { + chain.doFilter(request, response); + return; } - }; + // for readability we're returning trace id in a hex form + ((HttpServletResponse) response) + .addHeader("ZIPKIN-TRACE-ID", + currentSpan.context().traceIdString()); + // we can also add some custom tags + currentSpan.tag("custom", "tag"); + chain.doFilter(request, response); + } }
    -
    -Custom SA tag in Zipkin -Sometimes you want to create a manual Span that will wrap a call to an external service which is not instrumented. -What you can do is to create a span with the peer.service tag that will contain a value of the service that you want to call. -Below you can see an example of a call to Redis that is wrapped in such a span. -Unresolved directive in spring-cloud-sleuth.adoc - include::../../../..//spring-cloud-sleuth-zipkin-legacy/src/test/java/org/springframework/cloud/sleuth/zipkin/HttpZipkinSpanReporterTest.java[tags=service_name,indent=0] - -Remember not to add both peer.service tag and the SA tag! You have to add only peer.service. - -
    Custom service name -By default Sleuth assumes that when you send a span to Zipkin, you want the span’s service name - to be equal to spring.application.name value. That’s not always the case though. There - are situations in which you want to explicitly provide a different service name for all spans coming - from your application. To achieve that it’s enough to just pass the following property - to your application to override that value (example for foo service name): -spring.zipkin.service.name: foo +By default, Sleuth assumes that, when you send a span to Zipkin, you want the span’s service name to be equal to the value of the spring.application.name property. +That is not always the case, though. +There are situations in which you want to explicitly provide a different service name for all spans coming from your application. +To achieve that, you can pass the following property to your application to override that value (the example is for a service named myService): +spring.zipkin.service.name: myService
    -Customization of reported spans -Before reporting spans to e.g. Zipkin you can be interested in modifying that span in some way. - You can achieve that by using the SpanAdjuster interface. -Example of usage: -In Sleuth we’re generating spans with a fixed name. Some users want to modify the name depending on values -of tags. Implementation of the SpanAdjuster interface can be used to alter that name. Example: -@Bean -SpanAdjuster customSpanAdjuster() { - return span -> span.toBuilder().name(scrub(span.getName())).build(); +Customization of Reported Spans +Before reporting spans (for example, to Zipkin) you may want to modify that span in some way. +You can do so by using the SpanAdjuster interface. +In Sleuth, we generate spans with a fixed name. +Some users want to modify the name depending on values of tags. +You can implement the SpanAdjuster interface to alter that name. +The following example shows how to register two beans that implement SpanAdjuster: +@Bean SpanAdjuster adjusterOne() { + return span -> span.toBuilder().name("foo").build(); +} + +@Bean SpanAdjuster adjusterTwo() { + return span -> span.toBuilder().name(span.name() + " bar").build(); } -This will lead in changing the name of the reported span just before it gets sent to Zipkin. - -Your SpanReporter should inject the SpanAdjuster and - allow span manipulation before the actual reporting is done. - +The preceding example results in changing the name of the reported span to foo bar, just before it gets reported (for example, to Zipkin).
    -Host locator -In order to define the host that is corresponding to a particular span we need to resolve the host name -and port. The default approach is to take it from server properties. If those for some reason are not set -then we’re trying to retrieve the host name from the network interfaces. -If you have the discovery client enabled and prefer to retrieve the host address from the registered -instance in a service registry then you have to set the property (it’s applicable for both HTTP and -Stream based span reporting). +Host Locator + +This section is about defining host from service discovery. +It is NOT about finding Zipkin through service discovery. + +To define the host that corresponds to a particular span, we need to resolve the host name and port. +The default approach is to take these values from server properties. +If those are not set, we try to retrieve the host name from the network interfaces. +If you have the discovery client enabled and prefer to retrieve the host address from the registered instance in a service registry, you have to set the spring.zipkin.locator.discovery.enabled property (it is applicable for both HTTP-based and Stream-based span reporting), as follows: spring.zipkin.locator.discovery.enabled: true
    -Sending spans to Zipkin -By default if you add spring-cloud-starter-zipkin as a dependency to your project, -when the span is closed, it will be sent to Zipkin over HTTP. The communication -is asynchronous. You can configure the URL by setting the spring.zipkin.baseUrl -property as follows: +Sending Spans to Zipkin +By default, if you add spring-cloud-starter-zipkin as a dependency to your project, when the span is closed, it is sent to Zipkin over HTTP. +The communication is asynchronous. +You can configure the URL by setting the spring.zipkin.baseUrl property, as follows: spring.zipkin.baseUrl: http://192.168.99.100:9411/ -If you want to find Zipkin via service discovery it’s enough to pass the -Zipkin’s service id inside the URL (example for zipkinserver service id) +If you want to find Zipkin through service discovery, you can pass the Zipkin’s service ID inside the URL, as shown in the following example for zipkinserver service ID: spring.zipkin.baseUrl: http://zipkinserver/ - - -Span Data as Messages - -The suggested approach is to use the Zipkin’s -native support for message based span sending. Starting from -Edgware Zipkin Stream server is deprecated and in Finchley -it got removed. - -You can accumulate and send span data over -Spring Cloud Stream by -including the spring-cloud-sleuth-stream jar as a dependency, and -adding a Channel Binder implementation -(e.g. spring-cloud-starter-stream-rabbit for RabbitMQ or -spring-cloud-starter-stream-kafka for Kafka). This will -automatically turn your app into a producer of messages with payload -type Spans. -
    -Zipkin Consumer -Please refer to the Dalston Documentaion -on how to create a Stream Zipkin server. That approach has been -deprecated in Edgware and removed in Finchley release. -
    -
    -Custom Consumer -A custom consumer can also easily be implemented using -spring-cloud-sleuth-stream and binding to the SleuthSink. Example: -@EnableBinding(SleuthSink.class) -@SpringBootApplication(exclude = SleuthStreamAutoConfiguration.class) -@MessageEndpoint -public class Consumer { - - @ServiceActivator(inputChannel = SleuthSink.INPUT) - public void sink(Spans input) throws Exception { - // ... process spans - } -} - -the sample consumer application above explicitly excludes -SleuthStreamAutoConfiguration so it doesn’t send messages to itself, -but this is optional (you might actually want to trace requests into -the consumer app). - -In order to customize the polling mechanism you can create a bean of PollerMetadata type -with name equal to StreamSpanReporter.POLLER. Here you can find an example of such a configuration. +To disable this feature just set spring.zipkin.discoveryClientEnabled to `false. +When the Discovery Client feature is enabled, Sleuth uses +LoadBalancerClient to find the URL of the Zipkin Server. It means +that you can set up the load balancing configuration e.g. via Ribbon. +zipkinserver: + ribbon: + ListOfServers: host1,host2 +If you have web, rabbit, or kafka together on the classpath, you might need to pick the means by which you would like to send spans to zipkin. +To do so, set web, rabbit, or kafka to the spring.zipkin.sender.type property. +The following example shows setting the sender type for web: +spring.zipkin.sender.type: web +To customize the RestTemplate that sends spans to Zipkin via HTTP, you can register +the ZipkinRestTemplateCustomizer bean. @Configuration -public static class CustomPollerConfiguration { - - @Bean(name = StreamSpanReporter.POLLER) - PollerMetadata customPoller() { - PollerMetadata poller = new PollerMetadata(); - poller.setMaxMessagesPerPoll(500); - poller.setTrigger(new PeriodicTrigger(5000L)); - return poller; +class MyConfig { + @Bean ZipkinRestTemplateCustomizer myCustomizer() { + return new ZipkinRestTemplateCustomizer() { + @Override + void customize(RestTemplate restTemplate) { + // customize the RestTemplate + } + }; } } -
    +If, however, you would like to control the full process of creating the RestTemplate +object, you will have to create a bean of zipkin2.reporter.Sender type. + @Bean Sender myRestTemplateSender(ZipkinProperties zipkin, + ZipkinRestTemplateCustomizer zipkinRestTemplateCustomizer) { + RestTemplate restTemplate = mySuperCustomRestTemplate(); + zipkinRestTemplateCustomizer.customize(restTemplate); + return myCustomSender(zipkin, restTemplate); + }     - -Metrics -Currently Spring Cloud Sleuth registers very simple metrics related to spans. -It’s using the Spring Boot’s metrics support -to calculate the number of accepted and dropped spans. Each time a span gets -sent to Zipkin the number of accepted spans will increase. If there’s an error then -the number of dropped spans will get increased. + +Zipkin Stream Span Consumer + +We recommend using Zipkin’s native support for message-based span sending. +Starting from the Edgware release, the Zipkin Stream server is deprecated. +In the Finchley release, it got removed. + +If for some reason you need to create the deprecated Stream Zipkin server, see the Dalston Documentation. Integrations +
    +OpenTracing +Spring Cloud Sleuth is compatible with OpenTracing. +If you have OpenTracing on the classpath, we automatically register the OpenTracing Tracer bean. +If you wish to disable this, set spring.sleuth.opentracing.enabled to false +
    Runnable and Callable -If you’re wrapping your logic in Runnable or Callable it’s enough to wrap those classes in their Sleuth representative. -Example for Runnable: +If you wrap your logic in Runnable or Callable, you can wrap those classes in their Sleuth representative, as shown in the following example for Runnable: Runnable runnable = new Runnable() { @Override public void run() { @@ -1369,11 +1615,12 @@ the number of dropped spans will get increased. } }; // Manual `TraceRunnable` creation with explicit "calculateTax" Span name -Runnable traceRunnable = new TraceRunnable(tracer, spanNamer, runnable, "calculateTax"); -// Wrapping `Runnable` with `Tracer`. The Span name will be taken either from the -// `@SpanName` annotation or from `toString` method -Runnable traceRunnableFromTracer = tracer.wrap(runnable); -Example for Callable: +Runnable traceRunnable = new TraceRunnable(tracing, spanNamer, runnable, + "calculateTax"); +// Wrapping `Runnable` with `Tracing`. That way the current span will be available +// in the thread of `Runnable` +Runnable traceRunnableFromTracer = tracing.currentTraceContext().wrap(runnable); +The following example shows how to do so for Callable: Callable<String> callable = new Callable<String>() { @Override public String call() throws Exception { @@ -1386,33 +1633,33 @@ Runnable traceRunnableFromTracer = tracer.wrap(runnable); } }; // Manual `TraceCallable` creation with explicit "calculateTax" Span name -Callable<String> traceCallable = new TraceCallable<>(tracer, spanNamer, callable, "calculateTax"); -// Wrapping `Callable` with `Tracer`. The Span name will be taken either from the -// `@SpanName` annotation or from `toString` method -Callable<String> traceCallableFromTracer = tracer.wrap(callable); -That way you will ensure that a new Span is created and closed for each execution. +Callable<String> traceCallable = new TraceCallable<>(tracing, spanNamer, callable, + "calculateTax"); +// Wrapping `Callable` with `Tracing`. That way the current span will be available +// in the thread of `Callable` +Callable<String> traceCallableFromTracer = tracing.currentTraceContext().wrap(callable); +That way, you ensure that a new span is created and closed for each execution.
    Hystrix
    Custom Concurrency Strategy -We’re registering a custom HystrixConcurrencyStrategy -that wraps all Callable instances into their Sleuth representative - -the TraceCallable. The strategy either starts or continues a span depending on the fact whether tracing was already going -on before the Hystrix command was called. To disable the custom Hystrix Concurrency Strategy set the spring.sleuth.hystrix.strategy.enabled to false. +We register a custom HystrixConcurrencyStrategy called TraceCallable that wraps all Callable instances in their Sleuth representative. +The strategy either starts or continues a span, depending on whether tracing was already going on before the Hystrix command was called. +To disable the custom Hystrix Concurrency Strategy, set the spring.sleuth.hystrix.strategy.enabled to false.
    Manual Command setting -Assuming that you have the following HystrixCommand: +Assume that you have the following HystrixCommand: HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) { @Override protected String run() throws Exception { return someLogic(); } }; -In order to pass the tracing information you have to wrap the same logic in the Sleuth version of the HystrixCommand which is the -TraceCommand: -TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, traceKeys, setter) { +To pass the tracing information, you have to wrap the same logic in the Sleuth version of the HystrixCommand, which is called +TraceCommand, as shown in the following example: +TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, setter) { @Override public String doRun() throws Exception { return someLogic(); @@ -1422,108 +1669,99 @@ on before the Hystrix command was called. To disable the custom Hystrix Concurre
    RxJava -We’re registering a custom RxJavaSchedulersHook -that wraps all Action0 instances into their Sleuth representative - -the TraceAction. The hook either starts or continues a span depending on the fact whether tracing was already going -on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the spring.sleuth.rxjava.schedulers.hook.enabled to false. -You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list -of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property. +We registering a custom RxJavaSchedulersHook that wraps all Action0 instances in their Sleuth representative, which is called TraceAction. +The hook either starts or continues a span, depending on whether tracing was already going on before the Action was scheduled. +To disable the custom RxJavaSchedulersHook, set the spring.sleuth.rxjava.schedulers.hook.enabled to false. +You can define a list of regular expressions for thread names for which you do not want spans to be created. +To do so, provide a comma-separated list of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property. + +The suggest approach to reactive programming and Sleuth is to use +the Reactor support. +
    HTTP integration -Features from this section can be disabled by providing the spring.sleuth.web.enabled property with value equal to false. +Features from this section can be disabled by setting the spring.sleuth.web.enabled property with value equal to false.
    HTTP Filter -Via the TraceFilter all sampled incoming requests result in creation of a Span. That Span’s name is http: + the path to which - the request was sent. E.g. if the request was sent to /foo/bar then the name will be http:/foo/bar. You can configure which URIs you would - like to skip via the spring.sleuth.web.skipPattern property. If you have ManagementServerProperties on classpath then - its value of contextPath gets appended to the provided skip pattern. +Through the TracingFilter, all sampled incoming requests result in creation of a Span. +That Span’s name is http: + the path to which the request was sent. +For example, if the request was sent to /this/that then the name will be http:/this/that. +You can configure which URIs you would like to skip by setting the spring.sleuth.web.skipPattern property. +If you have ManagementServerProperties on classpath, its value of contextPath gets appended to the provided skip pattern. +If you want to reuse the Sleuth’s default skip patterns and just append your own, pass those patterns by using the spring.sleuth.web.additionalSkipPattern.
    HandlerInterceptor -Since we want the span names to be precise we’re using a TraceHandlerInterceptor that either wraps an - existing HandlerInterceptor or is added directly to the list of existing HandlerInterceptors. The - TraceHandlerInterceptor adds a special request attribute to the given HttpServletRequest. If the - the TraceFilter doesn’t see this attribute set it will create a "fallback" span which is an additional - span created on the server side so that the trace is presented properly in the UI. Seeing that most likely - signifies that there is a missing instrumentation. In that case please file an issue in Spring Cloud Sleuth. +Since we want the span names to be precise, we use a TraceHandlerInterceptor that either wraps an existing HandlerInterceptor or is added directly to the list of existing HandlerInterceptors. +The TraceHandlerInterceptor adds a special request attribute to the given HttpServletRequest. +If the the TracingFilter does not see this attribute, it creates a "fallback" span, which is an additional span created on the server side so that the trace is presented properly in the UI. +If that happens, there is probably missing instrumentation. +In that case, please file an issue in Spring Cloud Sleuth.
    Async Servlet support -If your controller returns a Callable or a WebAsyncTask Spring Cloud Sleuth will continue the existing span instead of creating a new one. +If your controller returns a Callable or a WebAsyncTask, Spring Cloud Sleuth continues the existing span instead of creating a new one.
    WebFlux support -Via the TraceWebFilter all sampled incoming requests result in creation of a Span. That Span’s name is http: + the path to which - the request was sent. E.g. if the request was sent to /foo/bar then the name will be http:/foo/bar. You can configure which URIs you would - like to skip via the spring.sleuth.web.skipPattern property. If you have ManagementServerProperties on classpath then - its value of contextPath gets appended to the provided skip pattern. +Through TraceWebFilter, all sampled incoming requests result in creation of a Span. +That Span’s name is http: + the path to which the request was sent. +For example, if the request was sent to /this/that, the name is http:/this/that. +You can configure which URIs you would like to skip by using the spring.sleuth.web.skipPattern property. +If you have ManagementServerProperties on the classpath, its value of contextPath gets appended to the provided skip pattern. +If you want to reuse Sleuth’s default skip patterns and append your own, pass those patterns by using the spring.sleuth.web.additionalSkipPattern. +
    +
    +Dubbo RPC support +Via the integration with Brave, Spring Cloud Sleuth supports Dubbo. +It’s enough to add the brave-instrumentation-dubbo-rpc dependency: +<dependency> + <groupId>io.zipkin.brave</groupId> + <artifactId>brave-instrumentation-dubbo-rpc</artifactId> +</dependency> +You need to also set a dubbo.properties file with the following contents: +dubbo.provider.filter=tracing +dubbo.consumer.filter=tracing +You can read more about Brave - Dubbo integration here. +An example of Spring Cloud Sleuth and Dubbo can be found here.
    -HTTP client integration +HTTP Client Integration
    Synchronous Rest Template -We’re injecting a RestTemplate interceptor that ensures that all the tracing information is passed to the requests. Each time a -call is made a new Span is created. It gets closed upon receiving the response. In order to block the synchronous RestTemplate features -just set spring.sleuth.web.client.enabled to false. +We inject a RestTemplate interceptor to ensure that all the tracing information is passed to the requests. +Each time a call is made, a new Span is created. +It gets closed upon receiving the response. +To block the synchronous RestTemplate features, set spring.sleuth.web.client.enabled to false. -You have to register RestTemplate as a bean so that the interceptors will get injected. -If you create a RestTemplate instance with a new keyword then the instrumentation WILL NOT work. +You have to register RestTemplate as a bean so that the interceptors get injected. +If you create a RestTemplate instance with a new keyword, the instrumentation does NOT work.
    Asynchronous Rest Template -A traced version of an AsyncRestTemplate bean is registered for you out of the box. If you -have your own bean you have to wrap it in a TraceAsyncRestTemplate representation. The best solution -is to only customize the ClientHttpRequestFactory and / or AsyncClientHttpRequestFactory. -If you have your own AsyncRestTemplate and you don’t wrap it your calls WILL NOT GET TRACED. +Starting with Sleuth 2.0.0, we no longer register a bean of AsyncRestTemplate type. +It is up to you to create such a bean. +Then we instrument it. -Custom instrumentation is set to create and close Spans upon sending and receiving requests. You can customize the ClientHttpRequestFactory -and the AsyncClientHttpRequestFactory by registering your beans. Remember to use tracing compatible implementations (e.g. don’t forget to -wrap ThreadPoolTaskScheduler in a TraceAsyncListenableTaskExecutor). Example of custom request factories: -@EnableAutoConfiguration -@Configuration -public static class TestConfiguration { - - @Bean - ClientHttpRequestFactory mySyncClientFactory() { - return new MySyncClientHttpRequestFactory(); - } - - @Bean - AsyncClientHttpRequestFactory myAsyncClientFactory() { - return new MyAsyncClientHttpRequestFactory(); - } -} -To block the AsyncRestTemplate features set spring.sleuth.web.async.client.enabled to false. -To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapper set spring.sleuth.web.async.client.factory.enabled -to false. If you don’t want to create AsyncRestClient at all set spring.sleuth.web.async.client.template.enabled to false. +To block the AsyncRestTemplate features, set spring.sleuth.web.async.client.enabled to false. +To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapper, set spring.sleuth.web.async.client.factory.enabled +to false. +If you do not want to create AsyncRestClient at all, set spring.sleuth.web.async.client.template.enabled to false.
    Multiple Asynchronous Rest Templates -Sometimes you need to use multiple implementations of Asynchronous Rest Template. In the following snippet you -can see an example of how to set up such a custom AsyncRestTemplate. +Sometimes you need to use multiple implementations of the Asynchronous Rest Template. +In the following snippet, you can see an example of how to set up such a custom AsyncRestTemplate: @Configuration @EnableAutoConfiguration static class Config { - @Autowired Tracer tracer; - @Autowired HttpTraceKeysInjector httpTraceKeysInjector; - @Autowired HttpSpanInjector spanInjector; @Bean(name = "customAsyncRestTemplate") - public AsyncRestTemplate traceAsyncRestTemplate(@Qualifier("customHttpRequestFactoryWrapper") - TraceAsyncClientHttpRequestFactoryWrapper wrapper, ErrorParser errorParser) { - return new TraceAsyncRestTemplate(wrapper, this.tracer, errorParser); - } - - @Bean(name = "customHttpRequestFactoryWrapper") - public TraceAsyncClientHttpRequestFactoryWrapper traceAsyncClientHttpRequestFactory() { - return new TraceAsyncClientHttpRequestFactoryWrapper(this.tracer, - this.spanInjector, - asyncClientFactory(), - clientHttpRequestFactory(), - this.httpTraceKeysInjector); + public AsyncRestTemplate traceAsyncRestTemplate() { + return new AsyncRestTemplate(asyncClientFactory(), clientHttpRequestFactory()); } private ClientHttpRequestFactory clientHttpRequestFactory() { @@ -1540,95 +1778,111 @@ static class Config { }
    -
    -WebClient -We inject a ExchangeFilterFunction implementation that creates a span and via on success and on -error callbacks takes care of closing client side spans. +
    +<literal>WebClient</literal> +We inject a ExchangeFilterFunction implementation that creates a span and, through on-success and on-error callbacks, takes care of closing client-side spans. +To block this feature, set spring.sleuth.web.client.enabled to false. -You have to register WebClient as a bean so that the tracing instrumention gets applied. -If you create a WebClient instance with a new keyword then the instrumentation WILL NOT work. +You have to register WebClient as a bean so that the tracing instrumentation gets applied. +If you create a WebClient instance with a new keyword, the instrumentation does NOT work.
    Traverson -If you’re using the Traverson library -it’s enough for you to inject a RestTemplate as a bean into your Traverson object. Since RestTemplate -is already intercepted, you will get full support of tracing in your client. Below you can find a pseudo code -of how to do that: +If you use the Traverson library, you can inject a RestTemplate as a bean into your Traverson object. +Since RestTemplate is already intercepted, you get full support for tracing in your client. The following pseudo code +shows how to do that: @Autowired RestTemplate restTemplate; Traverson traverson = new Traverson(URI.create("http://some/address"), MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate); // use Traverson
    +
    +Apache <literal>HttpClientBuilder</literal> and <literal>HttpAsyncClientBuilder</literal> +We instrument the HttpClientBuilder and HttpAsyncClientBuilder so that +tracing context gets injected to the sent requests. +To block these features, set spring.sleuth.web.client.enabled to false. +
    +
    +Netty <literal>HttpClient</literal> +We instrument the Netty’s HttpClient. +To block this feature, set spring.sleuth.web.client.enabled to false. + +You have to register HttpClient as a bean so that the instrumentation happens. +If you create a HttpClient instance with a new keyword, the instrumentation does NOT work. + +
    +
    +<literal>UserInfoRestTemplateCustomizer</literal> +We instrument the Spring Security’s UserInfoRestTemplateCustomizer. +To block this feature, set spring.sleuth.web.client.enabled to false. +
    Feign -By default Spring Cloud Sleuth provides integration with feign via the TraceFeignClientAutoConfiguration. You can disable it entirely -by setting spring.sleuth.feign.enabled to false. If you do so then no Feign related instrumentation will take place. -Part of Feign instrumentation is done via a FeignBeanPostProcessor. You can disable it by providing the spring.sleuth.feign.processor.enabled equal to false. -If you set it like this then Spring Cloud Sleuth will not instrument any of your custom Feign components. All the default instrumentation -however will be still there. +By default, Spring Cloud Sleuth provides integration with Feign through TraceFeignClientAutoConfiguration. +You can disable it entirely by setting spring.sleuth.feign.enabled to false. +If you do so, no Feign-related instrumentation take place. +Part of Feign instrumentation is done through a FeignBeanPostProcessor. +You can disable it by setting spring.sleuth.feign.processor.enabled to false. +If you set it to false, Spring Cloud Sleuth does not instrument any of your custom Feign components. +However, all the default instrumentation is still there.
    -Asynchronous communication -
    -@Async annotated methods -In Spring Cloud Sleuth we’re instrumenting async related components so that the tracing information is passed between threads. -You can disable this behaviour by setting the value of spring.sleuth.async.enabled to false. -If you annotate your method with @Async then we’ll automatically create a new Span with the following characteristics: +Asynchronous Communication +
    +<literal>@Async</literal> Annotated methods +In Spring Cloud Sleuth, we instrument async-related components so that the tracing information is passed between threads. +You can disable this behavior by setting the value of spring.sleuth.async.enabled to false. +If you annotate your method with @Async, we automatically create a new Span with the following characteristics: -if the method is annotated with @SpanName then the value of the annotation will be the Span’s name +If the method is annotated with @SpanName, the value of the annotation is the Span’s name. -if the method is not annotated with @SpanName the Span name will be the annotated method name +If the method is not annotated with @SpanName, the Span name is the annotated method name. -the Span will be tagged with that method’s class name and the method name too +The span is tagged with the method’s class name and method name.
    -
    -@Scheduled annotated methods -In Spring Cloud Sleuth we’re instrumenting scheduled method execution so that the tracing information is passed between threads. You can disable this behaviour -by setting the value of spring.sleuth.scheduled.enabled to false. -If you annotate your method with @Scheduled then we’ll automatically create a new Span with the following characteristics: +
    +<literal>@Scheduled</literal> Annotated Methods +In Spring Cloud Sleuth, we instrument scheduled method execution so that the tracing information is passed between threads. +You can disable this behavior by setting the value of spring.sleuth.scheduled.enabled to false. +If you annotate your method with @Scheduled, we automatically create a new span with the following characteristics: -the Span name will be the annotated method name +The span name is the annotated method name. -the Span will be tagged with that method’s class name and the method name too +The span is tagged with the method’s class name and method name. -If you want to skip Span creation for some @Scheduled annotated classes you can set the -spring.sleuth.scheduled.skipPattern with a regular expression that will match the fully qualified name of the -@Scheduled annotated class. - -If you are using spring-cloud-sleuth-stream and spring-cloud-netflix-hystrix-stream together, Span will be created for each Hystrix metrics and sent to Zipkin. This may be annoying. You can prevent this by setting spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask - +If you want to skip span creation for some @Scheduled annotated classes, you can set the spring.sleuth.scheduled.skipPattern with a regular expression that matches the fully qualified name of the @Scheduled annotated class. +If you use spring-cloud-sleuth-stream and spring-cloud-netflix-hystrix-stream together, a span is created for each Hystrix metrics and sent to Zipkin. +This behavior may be annoying. That’s why, by default, spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask.
    -Executor, ExecutorService and ScheduledExecutorService -We’re providing LazyTraceExecutor, TraceableExecutorService and TraceableScheduledExecutorService. Those implementations -are creating Spans each time a new task is submitted, invoked or scheduled. -Here you can see an example of how to pass tracing information with TraceableExecutorService when working with CompletableFuture: +Executor, ExecutorService, and ScheduledExecutorService +We provide LazyTraceExecutor, TraceableExecutorService, and TraceableScheduledExecutorService. Those implementations create spans each time a new task is submitted, invoked, or scheduled. +The following example shows how to pass tracing information with TraceableExecutorService when working with CompletableFuture: CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> { // perform some logic return 1_000_000L; -}, new TraceableExecutorService(executorService, +}, new TraceableExecutorService(beanFactory, executorService, // 'calculateTax' explicitly names the span - this param is optional - tracer, traceKeys, spanNamer, "calculateTax")); + "calculateTax")); -Sleuth doesn’t work with parallelStream() out of the box. If you want -to have the tracing information propagated through the stream you have to use the -approach with supplyAsync(...) as presented above. +Sleuth does not work with parallelStream() out of the box. +If you want to have the tracing information propagated through the stream, you have to use the approach with supplyAsync(...), as shown earlier.
    Customization of Executors -Sometimes you need to set up a custom instance of the AsyncExecutor. In the following snippet you -can see an example of how to set up such a custom Executor. +Sometimes, you need to set up a custom instance of the AsyncExecutor. +The following example shows how to set up such a custom Executor: @Configuration @EnableAutoConfiguration @EnableAsync @@ -1653,31 +1907,56 @@ static class CustomExecutorConfig extends AsyncConfigurerSupport {
    Messaging -Spring Cloud Sleuth integrates with Spring Integration. It creates spans for publish and -subscribe events. To disable Spring Integration instrumentation, set spring.sleuth.integration.enabled to false. -You can provide the spring.sleuth.integration.patterns pattern to explicitly -provide the names of channels that you want to include for tracing. By default all channels -are included. +Features from this section can be disabled by setting the spring.sleuth.messaging.enabled property with value equal to false. +
    +Spring Integration and Spring Cloud Stream +Spring Cloud Sleuth integrates with Spring Integration. +It creates spans for publish and subscribe events. +To disable Spring Integration instrumentation, set spring.sleuth.integration.enabled to false. +You can provide the spring.sleuth.integration.patterns pattern to explicitly provide the names of channels that you want to include for tracing. +By default, all channels but hystrixStreamOutput channel are included. -When using the Executor to build a Spring Integration IntegrationFlow remember to use the untraced version of the Executor. -Decorating Spring Integration Executor Channel with TraceableExecutorService will cause the spans to be improperly closed. +When using the Executor to build a Spring Integration IntegrationFlow, you must use the untraced version of the Executor. +Decorating the Spring Integration Executor Channel with TraceableExecutorService causes the spans to be improperly closed.
    +
    +Spring RabbitMq +We instrument the RabbitTemplate so that tracing headers get injected +into the message. +To block this feature, set spring.sleuth.messaging.rabbit.enabled to false. +
    +
    +Spring Kafka +We instrument the Spring Kafka’s ProducerFactory and ConsumerFactory +so that tracing headers get injected into the created Spring Kafka’s +Producer and Consumer. +To block this feature, set spring.sleuth.messaging.kafka.enabled to false. + +We do not support context propagation via @KafkaListener annotation. +Check this issue for more information. + +
    +
    Zuul -We’re registering Zuul filters to propagate the tracing information (the request header is enriched with tracing data). -To disable Zuul support set the spring.sleuth.zuul.enabled property to false. +We instrument the Zuul Ribbon integration by enriching the Ribbon requests with tracing information. +To disable Zuul support, set the spring.sleuth.zuul.enabled property to false.
    Running examples -You can find the running examples deployed in the Pivotal Web Services. Check them out in the following links: +You can see the running examples deployed in the Pivotal Web Services. +Check them out at the following links: -Zipkin for apps presented in the samples to the top +Zipkin for apps presented in the samples to the top. First make +a request to Service 1 and then check out the trace in Zipkin. -Zipkin for Brewery on PWS, its Github Code +Zipkin for Brewery on PWS, its Github Code. +Ensure that you’ve picked the lookback period of 7 days. If there are no traces, go to Presenting application +and order some beers. Then check Zipkin for traces.