From 682b7aee7c93ae87e56aec2ea38b3bee201a9ccb Mon Sep 17 00:00:00 2001 From: buildmaster Date: Tue, 4 Dec 2018 21:23:41 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- multi/multi__integrations.html | 24 +++++++++++++------- multi/multi_spring-cloud-sleuth.html | 2 +- single/spring-cloud-sleuth.html | 26 +++++++++++++-------- spring-cloud-sleuth.xml | 34 ++++++++++++++++++++++++++++ 4 files changed, 68 insertions(+), 18 deletions(-) diff --git a/multi/multi__integrations.html b/multi/multi__integrations.html index 285c4c2f5..03eeb3bec 100644 --- a/multi/multi__integrations.html +++ b/multi/multi__integrations.html @@ -121,11 +121,19 @@ You can disable it entirely by setting spring.sleuth.feign 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. +However, all the default instrumentation is still there.

15.8 gRPC

Spring Cloud Sleuth provides instrumentation for gRPC through TraceGrpcAutoConfiguration. You can disable it entirely by setting spring.sleuth.grpc.enabled to false.

15.8.1 Dependencies

[Important]Important

The gRPC integration relies on two external libraries to instrument clients and servers and both of those libraries must be on the class path to enable the instrumentation.

Maven:

		<dependency>
+			<groupId>io.github.lognet</groupId>
+			<artifactId>grpc-spring-boot-starter</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>io.zipkin.brave</groupId>
+			<artifactId>brave-instrumentation-grpc</artifactId>
+		</dependency>

Gradle:

    compile("io.github.lognet:grpc-spring-boot-starter")
+    compile("io.zipkin.brave:brave-instrumentation-grpc")

15.8.2 Server Instrumentation

Spring Cloud Sleuth leverages grpc-spring-boot-starter to register Brave’s gRPC server interceptor with all services annotated with @GRpcService.

15.8.3 Client Instrumentation

gRPC clients leverage a ManagedChannelBuilder to construct a ManagedChannel used to communicate to the gRPC server. The native ManagedChannelBuilder provides static methods as entry points for construction of ManagedChannel instances, however, this mechanism is outside the influence of the Spring application context.

[Important]Important

Spring Cloud Sleuth provides a SpringAwareManagedChannelBuilder that can be customized through the Spring application context and injected by gRPC clients. This builder must be used when creating ManagedChannel instances.

Sleuth creates a TracingManagedChannelBuilderCustomizer which inject Brave’s client interceptor into the SpringAwareManagedChannelBuilder.

15.9 Asynchronous Communication

15.9.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.9.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(() -> {
+This behavior may be annoying. That’s why, by default, spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask.

15.9.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(beanFactory, executorService,
@@ -155,14 +163,14 @@ The following example shows how to set up such a custom Ex
 		return new LazyTraceExecutor(this.beanFactory, executor);
 	}
 
-}

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. +}

15.10 Messaging

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

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

If you want to customize the way tracing context is read from and written to message headers, -it’s enough for you to register beans of types:

  • Propagation.Setter<MessageHeaderAccessor, String> - for writing headers to the message
  • Propagation.Getter<MessageHeaderAccessor, String> - for reading headers from the message

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 +it’s enough for you to register beans of types:

  • Propagation.Setter<MessageHeaderAccessor, String> - for writing headers to the message
  • Propagation.Getter<MessageHeaderAccessor, String> - for reading headers from the message

15.10.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.10.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.

15.9.4 Spring JMS

We instrument the JmsTemplate so that tracing headers get injected -into the message. We also support @JmsListener annotated methods on the consumer side.

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

[Important]Important

We don’t support baggage propagation for JMS

15.10 Zuul

We instrument the Zuul Ribbon integration by enriching the Ribbon requests with tracing information. +Producer and Consumer.

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

15.10.4 Spring JMS

We instrument the JmsTemplate so that tracing headers get injected +into the message. We also support @JmsListener annotated methods on the consumer side.

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

[Important]Important

We don’t support baggage propagation for JMS

15.11 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/multi/multi_spring-cloud-sleuth.html b/multi/multi_spring-cloud-sleuth.html index f6f005dc0..a7c7e0a1b 100644 --- a/multi/multi_spring-cloud-sleuth.html +++ b/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, 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.9.4. Spring JMS
15.10. Zuul
16. 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. gRPC
15.8.1. Dependencies
15.8.2. Server Instrumentation
15.8.3. Client Instrumentation
15.9. Asynchronous Communication
15.9.1. @Async Annotated methods
15.9.2. @Scheduled Annotated Methods
15.9.3. Executor, ExecutorService, and ScheduledExecutorService
Customization of Executors
15.10. Messaging
15.10.1. Spring Integration and Spring Cloud Stream
15.10.2. Spring RabbitMq
15.10.3. Spring Kafka
15.10.4. Spring JMS
15.11. Zuul
16. Running examples
   Next
   
\ No newline at end of file diff --git a/single/spring-cloud-sleuth.html b/single/spring-cloud-sleuth.html index a60840972..46565c481 100644 --- a/single/spring-cloud-sleuth.html +++ b/single/spring-cloud-sleuth.html @@ -1,6 +1,6 @@ - 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.9.4. Spring JMS
15.10. Zuul
16. Running examples

2.1.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. + 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. gRPC
15.8.1. Dependencies
15.8.2. Server Instrumentation
15.8.3. Client Instrumentation
15.9. Asynchronous Communication
15.9.1. @Async Annotated methods
15.9.2. @Scheduled Annotated Methods
15.9.3. Executor, ExecutorService, and ScheduledExecutorService
Customization of Executors
15.10. Messaging
15.10.1. Spring Integration and Spring Cloud Stream
15.10.2. Spring RabbitMq
15.10.3. Spring Kafka
15.10.4. Spring JMS
15.11. Zuul
16. Running examples

2.1.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. 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 @@ -907,11 +907,19 @@ You can disable it entirely by setting spring.sleuth.feign 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. +However, all the default instrumentation is still there.

15.8 gRPC

Spring Cloud Sleuth provides instrumentation for gRPC through TraceGrpcAutoConfiguration. You can disable it entirely by setting spring.sleuth.grpc.enabled to false.

15.8.1 Dependencies

[Important]Important

The gRPC integration relies on two external libraries to instrument clients and servers and both of those libraries must be on the class path to enable the instrumentation.

Maven:

		<dependency>
+			<groupId>io.github.lognet</groupId>
+			<artifactId>grpc-spring-boot-starter</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>io.zipkin.brave</groupId>
+			<artifactId>brave-instrumentation-grpc</artifactId>
+		</dependency>

Gradle:

    compile("io.github.lognet:grpc-spring-boot-starter")
+    compile("io.zipkin.brave:brave-instrumentation-grpc")

15.8.2 Server Instrumentation

Spring Cloud Sleuth leverages grpc-spring-boot-starter to register Brave’s gRPC server interceptor with all services annotated with @GRpcService.

15.8.3 Client Instrumentation

gRPC clients leverage a ManagedChannelBuilder to construct a ManagedChannel used to communicate to the gRPC server. The native ManagedChannelBuilder provides static methods as entry points for construction of ManagedChannel instances, however, this mechanism is outside the influence of the Spring application context.

[Important]Important

Spring Cloud Sleuth provides a SpringAwareManagedChannelBuilder that can be customized through the Spring application context and injected by gRPC clients. This builder must be used when creating ManagedChannel instances.

Sleuth creates a TracingManagedChannelBuilderCustomizer which inject Brave’s client interceptor into the SpringAwareManagedChannelBuilder.

15.9 Asynchronous Communication

15.9.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.9.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(() -> {
+This behavior may be annoying. That’s why, by default, spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask.

15.9.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(beanFactory, executorService,
@@ -941,16 +949,16 @@ The following example shows how to set up such a custom Ex
 		return new LazyTraceExecutor(this.beanFactory, executor);
 	}
 
-}

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. +}

15.10 Messaging

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

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

If you want to customize the way tracing context is read from and written to message headers, -it’s enough for you to register beans of types:

  • Propagation.Setter<MessageHeaderAccessor, String> - for writing headers to the message
  • Propagation.Getter<MessageHeaderAccessor, String> - for reading headers from the message

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 +it’s enough for you to register beans of types:

  • Propagation.Setter<MessageHeaderAccessor, String> - for writing headers to the message
  • Propagation.Getter<MessageHeaderAccessor, String> - for reading headers from the message

15.10.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.10.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.

15.9.4 Spring JMS

We instrument the JmsTemplate so that tracing headers get injected -into the message. We also support @JmsListener annotated methods on the consumer side.

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

[Important]Important

We don’t support baggage propagation for JMS

15.10 Zuul

We instrument the Zuul Ribbon integration by enriching the Ribbon requests with tracing information. +Producer and Consumer.

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

15.10.4 Spring JMS

We instrument the JmsTemplate so that tracing headers get injected +into the message. We also support @JmsListener annotated methods on the consumer side.

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

[Important]Important

We don’t support baggage propagation for JMS

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

  • 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. diff --git a/spring-cloud-sleuth.xml b/spring-cloud-sleuth.xml index 60d155b27..d6ad32db9 100644 --- a/spring-cloud-sleuth.xml +++ b/spring-cloud-sleuth.xml @@ -1898,6 +1898,40 @@ You can disable it by setting spring.sleuth.feign.processor.enabled
    • false, Spring Cloud Sleuth does not instrument any of your custom Feign components. However, all the default instrumentation is still there. +
    +gRPC +Spring Cloud Sleuth provides instrumentation for gRPC through TraceGrpcAutoConfiguration. You can disable it entirely by setting spring.sleuth.grpc.enabled to false. +
    +Dependencies + +The gRPC integration relies on two external libraries to instrument clients and servers and both of those libraries must be on the class path to enable the instrumentation. + +Maven: + <dependency> + <groupId>io.github.lognet</groupId> + <artifactId>grpc-spring-boot-starter</artifactId> + </dependency> + <dependency> + <groupId>io.zipkin.brave</groupId> + <artifactId>brave-instrumentation-grpc</artifactId> + </dependency> +Gradle: + compile("io.github.lognet:grpc-spring-boot-starter") + compile("io.zipkin.brave:brave-instrumentation-grpc") +
    +
    +Server Instrumentation +Spring Cloud Sleuth leverages grpc-spring-boot-starter to register Brave’s gRPC server interceptor with all services annotated with @GRpcService. +
    +
    +Client Instrumentation +gRPC clients leverage a ManagedChannelBuilder to construct a ManagedChannel used to communicate to the gRPC server. The native ManagedChannelBuilder provides static methods as entry points for construction of ManagedChannel instances, however, this mechanism is outside the influence of the Spring application context. + +Spring Cloud Sleuth provides a SpringAwareManagedChannelBuilder that can be customized through the Spring application context and injected by gRPC clients. This builder must be used when creating ManagedChannel instances. + +Sleuth creates a TracingManagedChannelBuilderCustomizer which inject Brave’s client interceptor into the SpringAwareManagedChannelBuilder. +
    +
    Asynchronous Communication