From 8582a45b1baa9864163b41f36157b937dd7a02bd Mon Sep 17 00:00:00 2001 From: buildmaster Date: Thu, 17 Aug 2017 12:07:15 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- spring-cloud-sleuth.html | 143 ++++++++++++++++++++------------------- 1 file changed, 73 insertions(+), 70 deletions(-) diff --git a/spring-cloud-sleuth.html b/spring-cloud-sleuth.html index e4b6f3ccd..e89f7c371 100644 --- a/spring-cloud-sleuth.html +++ b/spring-cloud-sleuth.html @@ -562,7 +562,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
-

Terminology

+

Terminology

Spring Cloud Sleuth borrows Dapper’s terminology.

@@ -650,12 +650,12 @@ Client Sent
-

Purpose

+

Purpose

In the following sections the example from the image above will be taken into consideration.

-

Distributed tracing with Zipkin

+

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:

@@ -721,7 +721,7 @@ to service1 and 3 spans related to RPC calls.

-

Visualizing errors

+

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 @@ -748,7 +748,7 @@ setting proper tags on the span which Zipkin can properly colorize. You could se

-

Live examples

+

Live examples

Zipkin deployed on Pivotal Web Services @@ -771,7 +771,7 @@ setting proper tags on the span which Zipkin can properly colorize. You could se
-

Log correlation

+

Log correlation

When grepping the logs of those four applications by trace id equal to e.g. 2485ec27856c56f4 one would get the following:

@@ -832,7 +832,7 @@ If you want to use Grok together with the logs from Cloud Foundry you have to us
-
JSON Logback with Logstash
+
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.

@@ -965,7 +965,7 @@ If you’re using a custom logback-spring.xml then you have to
-

Propagating Span Context

+

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. @@ -1001,7 +1001,7 @@ initialSpan.setBaggageItem("UPPER_CASE", "someValue");

-
Baggage vs. Span Tags
+
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.

@@ -1028,9 +1028,9 @@ tracer.addTag(baggageKey, baggageValue);
-

Adding to the project

+

Adding to the project

-

Only Sleuth (log correlation)

+

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.

@@ -1094,7 +1094,7 @@ the Spring BOM

-

Sleuth with Zipkin via HTTP

+

Sleuth with Zipkin via HTTP

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

@@ -1157,7 +1157,7 @@ the Spring BOM

-

Sleuth with Zipkin via Spring Cloud Stream

+

Sleuth with Zipkin via Spring Cloud Stream

If you want both Sleuth and Zipkin just add the spring-cloud-sleuth-stream dependency.

@@ -1244,7 +1244,7 @@ the Spring BOM

-

Spring Cloud Sleuth Stream Zipkin Collector

+

Spring Cloud Sleuth Stream Zipkin Collector

If you want to start a Spring Cloud Sleuth Stream Zipkin collector just add the spring-cloud-sleuth-zipkin-stream dependency

@@ -1355,7 +1355,7 @@ public class ZipkinStreamServerApplication {
-

Additional resources

+

Additional resources

Marcin Grzejszczak talking about Spring Cloud Sleuth and Zipkin

@@ -1371,7 +1371,7 @@ public class ZipkinStreamServerApplication {
-

Features

+

Features

    @@ -1493,7 +1493,7 @@ the SLF4J MDC is always set and logback users will immediately see the trace and
-

Sampling

+

Sampling

In distributed tracing the data volumes can be very high so sampling @@ -1556,7 +1556,7 @@ regardless of the sampling decision.

-

Instrumentation

+

Instrumentation

Spring Cloud Sleuth instruments all your Spring application @@ -1606,7 +1606,7 @@ This approach may change in the future towards being lazy on this matter.

-

Span lifecycle

+

Span lifecycle

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

@@ -1646,7 +1646,7 @@ Spring creates the instance of Tracer for you. In order to use it a
-

Creating and closing spans

+

Creating and closing spans

You can manually create spans by using the Tracer interface.

@@ -1701,7 +1701,7 @@ latency issues and sometimes even thrown exceptions.
-

Continuing spans

+

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

@@ -1765,7 +1765,7 @@ Always clean after you create a span! Don’t forget to detach a span if som
-

Creating spans with an explicit parent

+

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 @@ -1810,7 +1810,7 @@ After having created such a span remember to close it. Otherwise you will see a

-

Naming spans

+

Naming spans

Picking a span name is not a trivial task. Span name should depict an operation name. The name should @@ -1837,7 +1837,7 @@ artificial like:

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

-

@SpanName annotation

+

@SpanName annotation

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

@@ -1868,7 +1868,7 @@ future.get();
-

toString() method

+

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, @@ -1900,10 +1900,10 @@ future.get();

-

Managing spans with annotations

+

Managing spans with annotations

-

Rationale

+

Rationale

The main arguments for this features are

@@ -1948,7 +1948,7 @@ at runtime thus span wrapping of objects was tedious. Now you can provide annota
-

Creating new spans

+

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 @@ -2007,7 +2007,7 @@ concrete one wins (in this case customNameOnTestMethod3 will be set

-

Continuing spans

+

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 @@ -2041,7 +2041,7 @@ this.testBean.testMethod11("test");

-

More advanced tag setting

+

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:

@@ -2061,7 +2061,7 @@ The default implementation uses SPEL expression resolution.

-

Custom extractor

+

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.

@@ -2092,7 +2092,7 @@ public TagValueResolver tagValueResolver() {
-

Resolving expressions for value

+

Resolving expressions for value

Having such an annotated method:

@@ -2110,7 +2110,7 @@ of the bean.

-

Using toString method

+

Using toString method

Having such an annotated method:

@@ -2129,7 +2129,7 @@ public void getAnnotationForArgumentToString(@SpanTag("test") Long param) {
-

Customizations

+

Customizations

Thanks to the SpanInjector and SpanExtractor you can customize the way spans @@ -2164,7 +2164,7 @@ implementation of a SpanTextMap that delegates calls to FooR and insertion of HTTP headers.

-

Spring Integration

+

Spring Integration

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

@@ -2184,7 +2184,7 @@ These are:

-

HTTP

+

HTTP

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

@@ -2204,7 +2204,7 @@ These are:

-

Example

+

Example

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

@@ -2339,7 +2339,7 @@ HttpResponseInjectingTraceFilter responseInjectingTraceFilter(Tracer tracer) {
-

Custom SA tag in Zipkin

+

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. @@ -2377,7 +2377,7 @@ Remember not to add both peer.service tag and the SA t

-

Custom service name

+

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 @@ -2392,7 +2392,7 @@ Remember not to add both peer.service tag and the SA t

-

Customization of reported spans

+

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.

@@ -2430,7 +2430,7 @@ Your SpanReporter should inject the SpanAdjuster and
-

Host locator

+

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 @@ -2450,7 +2450,7 @@ Stream based span reporting).

-

Sending spans to Zipkin

+

Sending spans to Zipkin

By default if you add spring-cloud-starter-zipkin as a dependency to your project, @@ -2475,7 +2475,7 @@ Zipkin’s service id inside the URL (example for zipkinserver

-

Span Data as Messages

+

Span Data as Messages

You can accumulate and send span data over @@ -2488,7 +2488,7 @@ automatically turn your app into a producer of messages with payload type Spans.

-

Zipkin Consumer

+

Zipkin Consumer

There is a special convenience annotation for setting up a message consumer for the Span data and pushing it into a Zipkin SpanStore. This application

@@ -2564,7 +2564,7 @@ querying in the Zipkin Web UI.
-

Custom Consumer

+

Custom Consumer

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

@@ -2621,7 +2621,7 @@ public static class CustomPollerConfiguration {
-

Metrics

+

Metrics

Currently Spring Cloud Sleuth registers very simple metrics related to spans. @@ -2633,10 +2633,10 @@ the number of dropped spans will get increased.

-

Integrations

+

Integrations

-

Runnable and Callable

+

Runnable and Callable

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

@@ -2691,9 +2691,9 @@ Callable<String> traceCallableFromTracer = tracer.wrap(callable);
-

Hystrix

+

Hystrix

-

Custom Concurrency Strategy

+

Custom Concurrency Strategy

We’re registering a custom HystrixConcurrencyStrategy that wraps all Callable instances into their Sleuth representative - @@ -2702,7 +2702,7 @@ on before the Hystrix command was called. To disable the custom Hystrix Concurre

-

Manual Command setting

+

Manual Command setting

Assuming that you have the following HystrixCommand:

@@ -2733,7 +2733,7 @@ on before the Hystrix command was called. To disable the custom Hystrix Concurre
-

RxJava

+

RxJava

We’re registering a custom RxJavaSchedulersHook that wraps all Action0 instances into their Sleuth representative - @@ -2746,12 +2746,12 @@ of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthrea

-

HTTP integration

+

HTTP integration

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

-

HTTP Filter

+

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 @@ -2760,7 +2760,7 @@ of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthrea

-

HandlerInterceptor

+

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 @@ -2771,16 +2771,16 @@ of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthrea

-

Async Servlet support

+

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.

-

HTTP client integration

+

HTTP client integration

-

Synchronous Rest Template

+

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 @@ -2801,7 +2801,7 @@ If you create a RestTemplate instance with a new keywo

-

Asynchronous Rest Template

+

Asynchronous Rest Template

@@ -2846,7 +2846,7 @@ To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapp 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
+
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.

@@ -2893,7 +2893,7 @@ static class Config {
-

Feign

+

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.

@@ -2905,9 +2905,9 @@ however will be still there.

-

Asynchronous communication

+

Asynchronous communication

-

@Async annotated methods

+

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

@@ -2918,7 +2918,10 @@ You can disable this behaviour by setting the value of spring.sleuth.async
  • -

    the Span name will be the annotated method name

    +

    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

    @@ -2927,7 +2930,7 @@ You can disable this behaviour by setting the value of spring.sleuth.async
-

@Scheduled annotated methods

+

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

@@ -2964,7 +2967,7 @@ If you are using spring-cloud-sleuth-stream and spring-cloud-
-

Executor, ExecutorService and ScheduledExecutorService

+

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.

@@ -2983,7 +2986,7 @@ are creating Spans each time a new task is submitted, invoked or scheduled.

-
Customization of Executors
+
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.

@@ -3015,7 +3018,7 @@ static class CustomExecutorConfig extends AsyncConfigurerSupport {
-

Messaging

+

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.

@@ -3040,7 +3043,7 @@ Decorating Spring Integration Executor Channel with TraceableExecutorServi
-

Zuul

+

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.

@@ -3049,7 +3052,7 @@ To disable Zuul support set the spring.sleuth.zuul.enabled property
-

Running examples

+

Running examples

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