1. Features
+1. Features
+Sleuth sets up instrumentation not only to track timing, but also to catch errors so that they can be analyzed or correlated with logs. This works the @@ -148,8 +149,8 @@ Zipkin screenshots. However, most services accepting Zipkin’s format[
1.1. Contextualizing errors
+1.1. Contextualizing errors
Without distributed tracing, it can be difficult to understand the impact of a an exception. For example, it can be hard to know if a specific request caused @@ -180,8 +181,8 @@ happened before the request hit another service or not:
"frontend" service to fail.1.2. Log correlation
+1.2. Log correlation
Sleuth configures the logging context with variables including the service name
(%{spring.zipkin.service.name}) and the trace ID (%{traceId}). These help
@@ -259,8 +260,8 @@ If you want to use Grok together with the logs from Cloud Foundry, you have to u
}
JSON Logback with Logstash
+1.2.1. 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).
1.3. Service Dependency Graph
+1.3. Service Dependency Graph
When you consider distributed tracing tracks requests, it makes sense that trace data can paint a picture of your architecture.
@@ -417,8 +418,8 @@ need to run a separate service to aggregate the dependency graph. You can learn more here.1.4. Request scoped properties (Baggage)
+1.4. Request scoped properties (Baggage)
Distributed tracing works by propagating fields inside and across services that connect the trace together: traceId and spanId notably. The context that holds @@ -455,8 +456,8 @@ to exceeding transport-level message or header capacity.
Baggage versus Tags
+1.4.1. Baggage versus Tags
Like trace IDs, Baggage is attached to messages or requests, usually as headers. Tags are key value pairs sent in a Span to Zipkin. Baggage values are @@ -483,6 +484,7 @@ like so:
-
-
- 1. Overview +
- 1. Overview +
- 2. Features -
- 2. How Sleuth works +
- 3. How Sleuth works -
- 3. Sampling -
- 4. Baggage +
- 4. Sampling +
- 5. Baggage -
- 5. Instrumentation -
- 6. Span lifecycle +
- 6. Instrumentation +
- 7. Span lifecycle -
- 7. Naming spans +
- 8. Naming spans -
- 8. Managing Spans with Annotations +
- 9. Managing Spans with Annotations -
- 9. Customizations +
- 10. Customizations -
- 10. Sending Spans to Zipkin -
- 11. Zipkin Stream Span Consumer -
- 12. Integrations +
- 11. Sending Spans to Zipkin +
- 12. Zipkin Stream Span Consumer +
- 13. Integrations
-
-
- 12.1. OpenTracing -
- 12.2. Runnable and Callable -
- 12.3. Spring Cloud CircuitBreaker -
- 12.4. RxJava -
- 12.5. HTTP integration -
- 12.6. HTTP Client Integration -
- 12.7. Feign -
- 12.8. gRPC -
- 12.9. Asynchronous Communication -
- 12.10. Messaging -
- 12.11. Redis -
- 12.12. Quartz -
- 12.13. Project Reactor +
- 13.1. OpenTracing +
- 13.2. Runnable and Callable +
- 13.3. Spring Cloud CircuitBreaker +
- 13.4. RxJava +
- 13.5. HTTP integration +
- 13.6. HTTP Client Integration +
- 13.7. Feign +
- 13.8. gRPC +
- 13.9. Asynchronous Communication +
- 13.10. Messaging +
- 13.11. Redis +
- 13.12. Quartz +
- 13.13. Project Reactor
- - 13. Configuration properties -
- 14. Running examples +
- 14. Configuration properties +
- 15. Running examples
To keep things simple, the same example is used throughout documentation using basic HTTP communication.
2. Features
+Sleuth sets up instrumentation not only to track timing, but also to catch errors so that they can be analyzed or correlated with logs. This works the @@ -254,8 +261,8 @@ Zipkin screenshots. However, most services accepting Zipkin’s format[
1.1.1. Contextualizing errors
+2.1. Contextualizing errors
Without distributed tracing, it can be difficult to understand the impact of a an exception. For example, it can be hard to know if a specific request caused @@ -286,8 +293,8 @@ happened before the request hit another service or not:
"frontend" service to fail.1.1.2. Log correlation
+2.2. Log correlation
Sleuth configures the logging context with variables including the service name
(%{spring.zipkin.service.name}) and the trace ID (%{traceId}). These help
@@ -365,8 +372,8 @@ If you want to use Grok together with the logs from Cloud Foundry, you have to u
}
JSON Logback with Logstash
+2.2.1. 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).
1.1.3. Service Dependency Graph
+2.3. Service Dependency Graph
When you consider distributed tracing tracks requests, it makes sense that trace data can paint a picture of your architecture.
@@ -523,8 +530,8 @@ need to run a separate service to aggregate the dependency graph. You can learn more here.1.1.4. Request scoped properties (Baggage)
+2.4. Request scoped properties (Baggage)
Distributed tracing works by propagating fields inside and across services that connect the trace together: traceId and spanId notably. The context that holds @@ -561,8 +568,8 @@ to exceeding transport-level message or header capacity.
Baggage versus Tags
+2.4.1. Baggage versus Tags
Like trace IDs, Baggage is attached to messages or requests, usually as headers. Tags are key value pairs sent in a Span to Zipkin. Baggage values are @@ -587,9 +594,8 @@ like so:
1.2. Adding Sleuth to the Project
+2.5. Adding Sleuth to the Project
This section addresses how to add Sleuth to your project with either Maven or Gradle.
1.2.1. Sleuth with Zipkin via HTTP
+2.5.1. Sleuth with Zipkin via HTTP
If you want both Sleuth and Zipkin, add the spring-cloud-starter-zipkin dependency.
1.2.2. Sleuth with Zipkin over RabbitMQ or Kafka
+2.5.2. 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.
1.2.3. Overriding the auto-configuration of Zipkin
+2.5.3. Overriding the auto-configuration of Zipkin
Spring Cloud Sleuth supports sending traces to multiple tracing systems as of version 2.1.0.
In order to get this to work, every tracing system needs to have a Reporter<Span> and Sender.
@@ -841,7 +847,7 @@ protected static class MyConfig {
1.2.4. Only Sleuth (log correlation)
+2.5.4. 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.
2. How Sleuth works
+3. How Sleuth works
Spring Cloud Sleuth is a layer over Brave.
@@ -956,7 +962,7 @@ looking for in the documentation, ask -2.1. Brave Basics
+3.1. Brave Basics
Most instrumentation work is done for you by default. Sleuth provides beans to allow you to change what’s traced, and it even provides annotations to avoid @@ -981,7 +987,7 @@ are some pointers.
3. Sampling
+4. Sampling
By default Spring Cloud Sleuth doesn’t sample spans. @@ -1032,7 +1038,7 @@ Doing so forces the current request to be sampled regardless of configuration.
4. Baggage
+5. Baggage
Baggage are fields that are propagated with the trace, optionally out of process. You can use
@@ -1077,7 +1083,7 @@ Remember that adding entries to MDC can drastically decrease the performance of
spring.sleuth.baggage.tag-fields with a list of whitelisted baggage keys. To disable the feature you have to pass the spring.sleuth.propagation.tag.enabled=false property.
4.1. Java configuration
+5.1. Java configuration
If you need to do anything more advanced than above, do not define properties and instead use a
@Bean config for the baggage fields you use.
@@ -1090,7 +1096,7 @@ Remember that adding entries to MDC can drastically decrease the performance of
5. Instrumentation
+6. Instrumentation
Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it.
@@ -1116,7 +1122,7 @@ Tags are collected and exported only if there is a Sampler that all
6. Span lifecycle
+7. Span lifecycle
You can do the following operations on the Span by means of brave.Tracer:
Tracer for you. In order
6.1. Creating and finishing spans
+7.1. Creating and finishing spans
You can manually create spans by using the Tracer, as shown in the following example:
6.2. Continuing Spans
+7.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:
@@ -1247,7 +1253,7 @@ finally {6.3. Creating a Span with an explicit Parent
+7.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. @@ -1295,7 +1301,7 @@ After creating such a span, you must finish it. Otherwise it is not reported (fo
7. Naming spans
+8. Naming spans
Picking a span name is not a trivial task. A span name should depict an operation name. @@ -1321,7 +1327,7 @@ The name should be low cardinality, so it should not include identifiers.
Fortunately, for asynchronous processing, you can provide explicit naming.
7.1. @SpanName Annotation
+8.1. @SpanName Annotation
You can name the span explicitly by using the @SpanName annotation, as shown in the following example:
7.2. toString() method
+8.2. toString() method
It is pretty rare to create separate classes for Runnable or Callable.
Typically, one creates an anonymous instance of those classes.
@@ -1384,13 +1390,13 @@ future.get();
8. Managing Spans with Annotations
+9. Managing Spans with Annotations
You can manage spans with a variety of annotations.
8.1. Rationale
+9.1. Rationale
There are a number of good reasons to manage spans with annotations, including:
8.2. Creating New Spans
+9.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.
customNameOnTestMethod3 is set).
8.3. Continuing Spans
+9.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:
8.4. Advanced Tag Setting
+9.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:
8.4.1. Custom extractor
+9.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.
8.4.2. Resolving Expressions for a Value
+9.4.2. Resolving Expressions for a Value
Consider the following annotated method:
8.4.3. Using the toString() method
+9.4.3. Using the toString() method
Consider the following annotated method:
9. Customizations
+10. Customizations
The Tracer object is fully managed by sleuth, so you rarely need to affect it. That said,
@@ -1630,9 +1636,9 @@ customize behaviour:
9.1. HTTP
+10.1. HTTP
9.1.1. Data Policy
+10.1.1. Data Policy
The default span data policy for HTTP requests is described in Brave: github.com/openzipkin/brave/tree/master/instrumentation/http#span-data-policy
@@ -1674,7 +1680,7 @@ class Config {9.1.2. Sampling
+10.1.2. Sampling
If client /server sampling is required, just register a bean of type
brave.sampler.SamplerFunction<HttpRequest> and name the bean
@@ -1717,7 +1723,7 @@ class Config {
9.2. TracingFilter
+10.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.
9.3. Messaging
+10.3. Messaging
Sleuth automatically configures the MessagingTracing bean which serves as a
foundation for Messaging instrumentation such as Kafka or JMS.
9.4. RPC
+10.4. RPC
Sleuth automatically configures the RpcTracing bean which serves as a
foundation for RPC instrumentation such as gRPC or Dubbo.
9.5. Custom service name
+10.5. 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.
@@ -1846,7 +1852,7 @@ To achieve that, you can pass the following property to your application to over
9.6. Customization of Reported Spans
+10.6. 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 FinishedSpanHandler interface.