diff --git a/2.1.x/multi/multi__current_span.html b/2.1.x/multi/multi__current_span.html
index 20f4099c3..e2c1d9852 100644
--- a/2.1.x/multi/multi__current_span.html
+++ b/2.1.x/multi/multi__current_span.html
@@ -6,13 +6,13 @@ You can use Tracer.currentSpan() to add custom tags
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;
+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;
+}
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();
diff --git a/2.1.x/multi/multi__customizations.html b/2.1.x/multi/multi__customizations.html
index 03020042a..6f5b39373 100644
--- a/2.1.x/multi/multi__customizations.html
+++ b/2.1.x/multi/multi__customizations.html
@@ -10,14 +10,14 @@ register a bean of type brave.http.HttpSampler and
reference the bean names via their static String NAME fields.
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
+an example of usage of SkipPatternProvider inside a server side, HttpSampler.
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)
+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 {
privatefinal Tracer tracer;
@@ -39,7 +39,7 @@ You can customize the tags or modify the response headers by registering your ow
this.tracer = tracer;
}
- @Override
+ @Overridepublicvoid doFilter(ServletRequest request, ServletResponse response,
FilterChain chain) throws IOException, ServletException {
Span currentSpan = this.tracer.currentSpan();
@@ -61,10 +61,10 @@ There are situations in which you want to explicitly provide a different service
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 FinishedSpanHandler 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 FinishedSpanHandler interface to alter that name.
The following example shows how to register two beans that implement FinishedSpanHandler:
@Bean
+You can implement the FinishedSpanHandler interface to alter that name.
The following example shows how to register two beans that implement FinishedSpanHandler:
@Bean
FinishedSpanHandler handlerOne() {
returnnew FinishedSpanHandler() {
- @Override
+ @Overridepublicboolean handle(TraceContext traceContext, MutableSpan span) {
span.name("foo");
return true; // keep this span
@@ -72,10 +72,10 @@ FinishedSpanHandler handlerOne() {
};
}
-@Bean
+@Bean
FinishedSpanHandler handlerTwo() {
returnnew FinishedSpanHandler() {
- @Override
+ @Overridepublicboolean handle(TraceContext traceContext, MutableSpan span) {
span.name(span.name() + " bar");
return true; // keep this span
diff --git a/2.1.x/multi/multi__features.html b/2.1.x/multi/multi__features.html
index 7f93ddcbd..39dfbe3a8 100644
--- a/2.1.x/multi/multi__features.html
+++ b/2.1.x/multi/multi__features.html
@@ -41,7 +41,7 @@ It also includes libraries to propagate the trace context over network boundarie
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 code that never leaves your process, run it inside a scoped span.
@Autowired Tracer tracer;
+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 code that never leaves your process, run it inside a scoped span.
@Autowired Tracer tracer;
// Start a new trace or a span within an existing trace representing an operation
ScopedSpan span = tracer.startScopedSpan("encode");
@@ -53,7 +53,7 @@ ScopedSpan span = tracer.startScopedSpan(throw e;
} finally {
span.finish(); // always finish the span
-}
When you need more features, or finer control, use the Span type:
@Autowired Tracer tracer;
+}
When you need more features, or finer control, use the Span type:
@Autowired Tracer tracer;
// Start a new trace or a span within an existing trace representing an operation
Span span = tracer.nextSpan().name("encode").start();
@@ -75,19 +75,19 @@ The former is simpler to understand and test and does not tempt users with span
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;
+@Autowired SpanCustomizer span;
void userCode() {
span.annotate("tx.started");
...
-}
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 Tracing tracing;
+@Autowired Tracer tracer;
// before you send a request, add metadata that describes the operation
span = tracer.nextSpan().name(service + "/" + method).kind(CLIENT);
span.tag("myrpc.version", "1.0.0");
span.remoteServiceName("backend");
-span.remoteIpAndPort("172.3.4.1", 8108);
+span.remoteIpAndPort("172.3.4.1", 8108);
// Add the trace context to the request, so it can be propagated in-band
tracing.propagation().injector(Request::addHeader)
@@ -105,8 +105,8 @@ span.error(exception);
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 Tracing tracing;
-@Autowired Tracer tracer;
+span.flush() instead, as you do not expect a response.
The following example shows how a client might model a one-way operation:
@Autowired Tracing tracing;
+@Autowired Tracer tracer;
// start a new span representing a client request
oneWaySend = tracer.nextSpan().name(service + "/" + method).kind(CLIENT);
@@ -119,8 +119,8 @@ tracing.propagation().injector(Request::addHeader)
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:
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
+ @Overridepublicvoid run() {
// do some work
}
- @Override
+ @Overridepublic String toString() {
return"spanNameFromToStringMethod";
}
@@ -20,12 +20,12 @@ Runnable traceRunnable = // in the thread of `Runnable`
Runnable traceRunnableFromTracer = this.tracing.currentTraceContext()
.wrap(runnable);
The following example shows how to do so for Callable:
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:
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
+ @Overridepublic String doRun() throws Exception {
return someLogic();
}
@@ -88,11 +88,11 @@ Then we instrument it.
To block the 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
+In the following snippet, you can see an example of how to set up such a custom AsyncRestTemplate:
@Configuration
+@EnableAutoConfigurationstaticclass Config {
- @Bean(name = "customAsyncRestTemplate")
+ @Bean(name = "customAsyncRestTemplate")public AsyncRestTemplate traceAsyncRestTemplate() {
returnnew AsyncRestTemplate(asyncClientFactory(),
clientHttpRequestFactory());
@@ -113,7 +113,7 @@ In the following snippet, you can see an example of how to set up such a custom
}
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
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;
+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);
@@ -138,30 +138,30 @@ You can disable this behavior by setting the value of spri
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.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
- return1_000_000L;
+ return1_000_000L;
}, new TraceableExecutorService(beanFactory, executorService,
// 'calculateTax' explicitly names the span - this param is optional"calculateTax"));
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.
If there are beans that implement the Executor interface that you would like
to exclude from span creation, you can use the spring.sleuth.async.ignored-beans
property where you can provide a list of bean names.
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
+The following example shows how to set up such a custom Executor:
@Configuration
+@EnableAutoConfiguration
+@EnableAsync// add the infrastructure role to ensure that the bean gets auto-proxied
-@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
+@Role(BeanDefinition.ROLE_INFRASTRUCTURE)staticclass CustomExecutorConfig extends AsyncConfigurerSupport {
- @Autowired
+ @Autowired
BeanFactory beanFactory;
- @Override
+ @Overridepublic Executor getAsyncExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
// CUSTOMIZE HERE
- executor.setCorePoolSize(7);
- executor.setMaxPoolSize(42);
- executor.setQueueCapacity(11);
+ executor.setCorePoolSize(7);
+ executor.setMaxPoolSize(42);
+ executor.setQueueCapacity(11);
executor.setThreadNamePrefix("MyExecutor-");
// DON'T FORGET TO INITIALIZE
executor.initialize();
diff --git a/2.1.x/multi/multi__introduction.html b/2.1.x/multi/multi__introduction.html
index 86b143d57..b0d5b28ce 100644
--- a/2.1.x/multi/multi__introduction.html
+++ b/2.1.x/multi/multi__introduction.html
@@ -53,7 +53,7 @@ An example from Kibana would resemble the following image:
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
Ensure that Logback is on the classpath (ch.qos.logback:logback-core).
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"?>
+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).
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).
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 nested dependencies get downloaded.
To automatically configure RabbitMQ, add the spring-rabbit dependency.
1.4 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.
If you want to override the provided beans you need to give them a specific name.
-To do this you can use respectively ZipkinAutoConfiguration.REPORTER_BEAN_NAME and ZipkinAutoConfiguration.SENDER_BEAN_NAME.
@Configuration
+To do this you can use respectively ZipkinAutoConfiguration.REPORTER_BEAN_NAME and ZipkinAutoConfiguration.SENDER_BEAN_NAME.
@Configurationprotectedstaticclass MyConfig {
- @Bean(ZipkinAutoConfiguration.REPORTER_BEAN_NAME)
+ @Bean(ZipkinAutoConfiguration.REPORTER_BEAN_NAME)
Reporter<zipkin2.Span> myReporter() {
return AsyncReporter.create(mySender());
}
- @Bean(ZipkinAutoConfiguration.SENDER_BEAN_NAME)
+ @Bean(ZipkinAutoConfiguration.SENDER_BEAN_NAME)
MySender mySender() {
returnnew MySender();
}
@@ -265,22 +265,22 @@ To do this you can use respectively ZipkinAutoConfiguratio
returnthis.spanSent;
}
- @Override
+ @Overridepublic Encoding encoding() {
return Encoding.JSON;
}
- @Override
+ @Overridepublicint messageMaxBytes() {
return Integer.MAX_VALUE;
}
- @Override
+ @Overridepublicint messageSizeInBytes(List<byte[]> encodedSpans) {
return encoding().listSizeInBytes(encodedSpans);
}
- @Override
+ @Overridepublic Call<Void> sendSpans(List<byte[]> encodedSpans) {
this.spanSent = true;
return Call.create(null);
diff --git a/2.1.x/multi/multi__managing_spans_with_annotations.html b/2.1.x/multi/multi__managing_spans_with_annotations.html
index cd81acde9..bb19500ba 100644
--- a/2.1.x/multi/multi__managing_spans_with_annotations.html
+++ b/2.1.x/multi/multi__managing_spans_with_annotations.html
@@ -5,23 +5,23 @@ Doing so lets Sleuth change its core API to create less impact to user code.
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")
+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.
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
+In our sample, the tag key is testTag, and the tag value is test.
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);
+@ContinueSpan(log = "testMethod11")
+void testMethod11(@SpanTag("testTag11") String param);
// method executionthis.testBean.testMethod11("test");
@@ -30,16 +30,16 @@ The precedence is as follows:
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 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
+Its class name has to be passed as the value of the resolver attribute.
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
-publicvoid getAnnotationForArgumentToString(@SpanTag("test") Long param) {
+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
+publicvoid getAnnotationForArgumentToString(@SpanTag("test") Long param) {
}
Running the preceding method with a value of 15 leads to setting a tag with a String value of "15".
![[Tip]](images/tip.png)
![[Important]](images/important.png)
