Add sleuth to the classpath of a Spring Boot application -(see “Adding Sleuth to the Project” for Maven and Gradle examples), and you will +(see “Adding Sleuth to your Project” for Maven and Gradle examples), and you will see trace IDs in logs.
This section addresses how to add Sleuth to your project with either Maven or Gradle.
If you want both Sleuth and Zipkin, add the spring-cloud-starter-zipkin dependency.
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.
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.
@@ -875,8 +885,8 @@ protected static class MyConfig {
If you want to use only Spring Cloud Sleuth without the Zipkin integration, add the spring-cloud-starter-sleuth module to your project.
To build the source you will need to install JDK 1.7.
.travis.yml (usually
The spring-cloud-build module has a "docs" profile, and if you switch that on it will try to build asciidoc sources from @@ -1044,7 +1053,7 @@ a modified file in the correct place. Just commit it and push the change.
If you don’t have an IDE preference we would recommend that you use Spring Tools Suite or @@ -1053,7 +1062,7 @@ a modified file in the correct place. Just commit it and push the change.
should also work without issue as long as they use Maven 3.3.3 or better.We recommend the m2eclipse eclipse plugin when working with
eclipse. If you don’t already have m2eclipse installed it is available from the "eclipse
@@ -1080,7 +1089,7 @@ pom into your settings.xml.
If you prefer not to use m2eclipse you can generate eclipse project metadata using the following command:
@@ -1114,7 +1123,7 @@ so, your app breaks during the Maven build.Spring Cloud is released under the non-restrictive Apache 2.0 license, @@ -1124,7 +1133,7 @@ to contribute even something trivial please do not hesitate, but follow the guidelines below.
Before we accept a non-trivial patch or pull request we will need you to sign the Contributor License Agreement. @@ -1135,7 +1144,7 @@ given the ability to merge pull requests.
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report @@ -1143,7 +1152,7 @@ unacceptable behavior to spri
None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.
@@ -1191,7 +1200,7 @@ message (where XXXX is the issue number).Spring Cloud Build comes with a set of checkstyle rules. You can find them in the spring-cloud-build-tools module. The most notable files under the module are:
Checkstyle rules are disabled by default. To add checkstyle to your project just define the following properties and plugins.
In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin. The following files can be found in the Spring Cloud Build project.
diff --git a/reference/html/index.html b/reference/html/index.html index 034fba49e..c2dc4e2ba 100644 --- a/reference/html/index.html +++ b/reference/html/index.html @@ -126,74 +126,81 @@ $(globalSwitch);TracingFilterThis section addresses how to add Sleuth to your project with either Maven or Gradle.
If you want both Sleuth and Zipkin, add the spring-cloud-starter-zipkin dependency.
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.
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,8 +851,8 @@ protected static class MyConfig {
If you want to use only Spring Cloud Sleuth without the Zipkin integration, add the spring-cloud-starter-sleuth module to your project.
Spring Cloud Sleuth is a layer over Brave.
@@ -957,7 +966,7 @@ looking for in the documentation, ask -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 @@ -982,7 +991,7 @@ are some pointers.
By default Spring Cloud Sleuth doesn’t sample spans. @@ -1033,7 +1042,7 @@ Doing so forces the current request to be sampled regardless of configuration.
Baggage are fields that are propagated with the trace, optionally out of process. You can use
@@ -1078,7 +1087,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.
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.
@@ -1091,7 +1100,7 @@ Remember that adding entries to MDC can drastically decrease the performance of
Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it.
@@ -1117,7 +1126,7 @@ Tags are collected and exported only if there is a Sampler that all
You can do the following operations on the Span by means of brave.Tracer:
Tracer for you. In order
You can manually create spans by using the Tracer, as shown in the following example:
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:
@@ -1248,7 +1257,7 @@ finally {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. @@ -1296,7 +1305,7 @@ After creating such a span, you must finish it. Otherwise it is not reported (fo
Picking a span name is not a trivial task. A span name should depict an operation name. @@ -1322,7 +1331,7 @@ The name should be low cardinality, so it should not include identifiers.
Fortunately, for asynchronous processing, you can provide explicit naming.
@SpanName Annotation@SpanName AnnotationYou can name the span explicitly by using the @SpanName annotation, as shown in the following example:
toString() methodtoString() methodIt is pretty rare to create separate classes for Runnable or Callable.
Typically, one creates an anonymous instance of those classes.
@@ -1385,13 +1394,13 @@ future.get();
You can manage spans with a variety of annotations.
There are a number of good reasons to manage spans with annotations, including:
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).
If you want to add tags and annotations to an existing span, you can use the @ContinueSpan annotation, as shown in the following example:
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:
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:
toString() methodtoString() methodConsider the following annotated method:
The Tracer object is fully managed by sleuth, so you rarely need to affect it. That said,
@@ -1631,9 +1640,9 @@ customize behaviour:
The default span data policy for HTTP requests is described in Brave: github.com/openzipkin/brave/tree/master/instrumentation/http#span-data-policy
@@ -1675,7 +1684,7 @@ class Config {If client /server sampling is required, just register a bean of type
brave.sampler.SamplerFunction<HttpRequest> and name the bean
@@ -1718,7 +1727,7 @@ class Config {
TracingFilterTracingFilterYou 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.
Sleuth automatically configures the MessagingTracing bean which serves as a
foundation for Messaging instrumentation such as Kafka or JMS.
Sleuth automatically configures the RpcTracing bean which serves as a
foundation for RPC instrumentation such as gRPC or Dubbo.
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.
@@ -1847,7 +1856,7 @@ To achieve that, you can pass the following property to your application to over
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.
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.
@@ -371,8 +379,8 @@ protected static class MyConfig {
If you want to use only Spring Cloud Sleuth without the Zipkin integration, add the spring-cloud-starter-sleuth module to your project.
TracingFilterThis section addresses how to add Sleuth to your project with either Maven or Gradle.
If you want both Sleuth and Zipkin, add the spring-cloud-starter-zipkin dependency.
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.
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,8 +851,8 @@ protected static class MyConfig {
If you want to use only Spring Cloud Sleuth without the Zipkin integration, add the spring-cloud-starter-sleuth module to your project.
Spring Cloud Sleuth is a layer over Brave.
@@ -957,7 +966,7 @@ looking for in the documentation, ask -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 @@ -982,7 +991,7 @@ are some pointers.
By default Spring Cloud Sleuth doesn’t sample spans. @@ -1033,7 +1042,7 @@ Doing so forces the current request to be sampled regardless of configuration.
Baggage are fields that are propagated with the trace, optionally out of process. You can use
@@ -1078,7 +1087,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.
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.
@@ -1091,7 +1100,7 @@ Remember that adding entries to MDC can drastically decrease the performance of
Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it.
@@ -1117,7 +1126,7 @@ Tags are collected and exported only if there is a Sampler that all
You can do the following operations on the Span by means of brave.Tracer:
Tracer for you. In order
You can manually create spans by using the Tracer, as shown in the following example:
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:
@@ -1248,7 +1257,7 @@ finally {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. @@ -1296,7 +1305,7 @@ After creating such a span, you must finish it. Otherwise it is not reported (fo
Picking a span name is not a trivial task. A span name should depict an operation name. @@ -1322,7 +1331,7 @@ The name should be low cardinality, so it should not include identifiers.
Fortunately, for asynchronous processing, you can provide explicit naming.
@SpanName Annotation@SpanName AnnotationYou can name the span explicitly by using the @SpanName annotation, as shown in the following example:
toString() methodtoString() methodIt is pretty rare to create separate classes for Runnable or Callable.
Typically, one creates an anonymous instance of those classes.
@@ -1385,13 +1394,13 @@ future.get();
You can manage spans with a variety of annotations.
There are a number of good reasons to manage spans with annotations, including:
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).
If you want to add tags and annotations to an existing span, you can use the @ContinueSpan annotation, as shown in the following example:
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:
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:
toString() methodtoString() methodConsider the following annotated method:
The Tracer object is fully managed by sleuth, so you rarely need to affect it. That said,
@@ -1631,9 +1640,9 @@ customize behaviour:
The default span data policy for HTTP requests is described in Brave: github.com/openzipkin/brave/tree/master/instrumentation/http#span-data-policy
@@ -1675,7 +1684,7 @@ class Config {If client /server sampling is required, just register a bean of type
brave.sampler.SamplerFunction<HttpRequest> and name the bean
@@ -1718,7 +1727,7 @@ class Config {
TracingFilterTracingFilterYou 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.
Sleuth automatically configures the MessagingTracing bean which serves as a
foundation for Messaging instrumentation such as Kafka or JMS.
Sleuth automatically configures the RpcTracing bean which serves as a
foundation for RPC instrumentation such as gRPC or Dubbo.
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.
@@ -1847,7 +1856,7 @@ To achieve that, you can pass the following property to your application to over
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.