From fbcc8292752996d72334421046fb2e25facbd141 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Sun, 30 Sep 2018 16:53:42 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- multi/multi__additional_resources.html | 2 +- multi/multi__current_span.html | 2 +- multi/multi__current_tracing_component.html | 2 +- multi/multi__customizations.html | 7 +++--- multi/multi__features.html | 2 +- multi/multi__instrumentation.html | 2 +- multi/multi__integrations.html | 14 +++++------ multi/multi__introduction.html | 2 +- ...ulti__managing_spans_with_annotations.html | 4 +-- multi/multi__naming_spans.html | 6 ++--- multi/multi__propagation.html | 2 +- multi/multi__running_examples.html | 2 +- multi/multi__sampling.html | 2 +- multi/multi__sending_spans_to_zipkin.html | 2 +- multi/multi__span_lifecycle.html | 2 +- multi/multi__zipkin_stream_span_consumer.html | 2 +- multi/multi_pr01.html | 2 +- multi/multi_spring-cloud-sleuth.html | 2 +- single/spring-cloud-sleuth.html | 25 ++++++++++--------- spring-cloud-sleuth.html | 2 +- spring-cloud-sleuth.xml | 25 ++++++++++--------- 21 files changed, 57 insertions(+), 54 deletions(-) diff --git a/multi/multi__additional_resources.html b/multi/multi__additional_resources.html index 244fa2c6d..2f351caf9 100644 --- a/multi/multi__additional_resources.html +++ b/multi/multi__additional_resources.html @@ -1,4 +1,4 @@ - 2. Additional Resources
2. Additional Resources
Prev   Next

2. Additional Resources

You can watch a video of Reshmi Krishna and Marcin Grzejszczak talking about Spring Cloud + 2. Additional Resources

2. Additional Resources
Prev   Next

2. Additional Resources

You can watch a video of Reshmi Krishna and Marcin Grzejszczak talking about Spring Cloud Sleuth and Zipkin by clicking here.

You can check different setups of Sleuth and Brave in the openzipkin/sleuth-webmvc-example repository.

Prev   Next
1. Introduction Home 3. Features
\ No newline at end of file diff --git a/multi/multi__current_span.html b/multi/multi__current_span.html index 6df2346f9..20f4099c3 100644 --- a/multi/multi__current_span.html +++ b/multi/multi__current_span.html @@ -1,6 +1,6 @@ - 7. Current Span
7. Current Span
Prev   Next

7. Current Span

Brave supports a "current span" concept which represents the in-flight operation. + 7. Current Span

7. Current Span
Prev   Next

7. Current Span

Brave supports a "current span" concept which represents the in-flight operation. You can use Tracer.currentSpan() to add custom tags to a span and Tracer.nextSpan() to create a child of whatever is in-flight.

[Important]Important

In Sleuth, you can autowire the Tracer bean to retrieve the current span via tracer.currentSpan() method. To retrieve the current context just call tracer.currentSpan().context(). To get the current trace id as String diff --git a/multi/multi__current_tracing_component.html b/multi/multi__current_tracing_component.html index 75511b6ac..99f56c3cd 100644 --- a/multi/multi__current_tracing_component.html +++ b/multi/multi__current_tracing_component.html @@ -1,6 +1,6 @@ - 6. Current Tracing Component

6. Current Tracing Component
Prev   Next

6. Current Tracing Component

Brave supports a "current tracing component" concept, which should only be used when you have no other way to get a reference. + 6. Current Tracing Component

6. Current Tracing Component
Prev   Next

6. Current Tracing Component

Brave supports a "current tracing component" concept, which should only be used when you have no other way to get a reference. This was made for JDBC connections, as they often initialize prior to the tracing component.

The most recent tracing component instantiated is available through Tracing.current(). You can also use Tracing.currentTracer() to get only the tracer. If you use either of these methods, do not cache the result. diff --git a/multi/multi__customizations.html b/multi/multi__customizations.html index 4b3d74485..6c076f043 100644 --- a/multi/multi__customizations.html +++ b/multi/multi__customizations.html @@ -1,6 +1,6 @@ - 12. Customizations

12. Customizations
Prev   Next

12. Customizations

12.1 HTTP

If a customization of client / server parsing of the HTTP related spans is required, + 12. Customizations

12. Customizations
Prev   Next

12. Customizations

12.1 HTTP

If a customization of client / server parsing of the HTTP related spans is required, just register a bean of type brave.http.HttpClientParser or brave.http.HttpServerParser. If client /server sampling is required, just register a bean of type brave.http.HttpSampler and name the bean @@ -27,7 +27,7 @@ an example of usage of SkipPatternProvider inside a } }; } -}

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

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

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 {
@@ -53,7 +53,8 @@ You can customize the tags or modify the response headers by registering your ow
 		currentSpan.tag("custom", "tag");
 		chain.doFilter(request, response);
 	}
-}

12.3 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. +} +//end::response_headers[]

12.3 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. There are situations in which you want to explicitly provide a different service name for all spans coming from your application. 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. diff --git a/multi/multi__features.html b/multi/multi__features.html index ec8619c5c..58c7029fa 100644 --- a/multi/multi__features.html +++ b/multi/multi__features.html @@ -1,6 +1,6 @@ - 3. Features

3. Features
Prev   Next

3. Features

  • Adds trace and span IDs to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator, as shown in the following example logs:

    2016-02-02 15:30:57.902  INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
+   3. Features
    3. Features
    Prev   Next
    3. Features
    • Adds trace and span IDs to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator, as shown in the following example logs:
      2016-02-02 15:30:57.902  INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
 2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
 2016-02-02 15:31:01.936  INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ...
      Notice the [appname,traceId,spanId,exportable] entries from the MDC:
      • spanId: The ID of a specific operation that took place.
      • appname: The name of the application that logged the span.
      • traceId: The ID of the latency graph that contains the span.
      • exportable: Whether the log should be exported to Zipkin.
 When would you like the span not to be exportable?
diff --git a/multi/multi__instrumentation.html b/multi/multi__instrumentation.html
index 82c1d45de..519547517 100644
--- a/multi/multi__instrumentation.html
+++ b/multi/multi__instrumentation.html
@@ -1,6 +1,6 @@
 
       
-   8. Instrumentation
        8. Instrumentation
        Prev   Next
        8. Instrumentation
        Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it.
+   8. Instrumentation
        8. Instrumentation
        Prev   Next
        8. Instrumentation
        Spring Cloud Sleuth automatically instruments all your Spring applications, so you should not have to do anything to activate it.
 The instrumentation is added by using a variety of technologies according to the stack that is available. For example, for a servlet web application, we use a Filter, and, for Spring Integration, we use ChannelInterceptors.
        You can customize the keys used in span tags.
 To limit the volume of span data, an HTTP request is, by default, tagged only with a handful of metadata, such as the status code, the host, and the URL.
 You can add request headers by configuring spring.sleuth.keys.http.headers (a list of header names).
        [Note]Note
        Tags are collected and exported only if there is a Sampler that allows it. By default, there is no such Sampler, to ensure that there is no danger of accidentally collecting too much data without configuring something).
        Prev   Next
        7. Current Span Home 9. Span lifecycle
        
\ No newline at end of file
diff --git a/multi/multi__integrations.html b/multi/multi__integrations.html
index 92ab2269c..03b3f2c12 100644
--- a/multi/multi__integrations.html
+++ b/multi/multi__integrations.html
@@ -1,6 +1,6 @@
 
       
-   15. Integrations
        15. Integrations
        Prev   Next
        15. Integrations
        15.1 OpenTracing
        Spring Cloud Sleuth is compatible with OpenTracing.
+   15. Integrations
        15. Integrations
        Prev   Next
        15. Integrations
        15.1 OpenTracing
        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
@@ -104,22 +104,22 @@ In the following snippet, you can see an example of how to set up such a custom
 		//CUSTOMIZE HERE
 		return factory;
 	}
-}
        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]Important
        You have to register WebClient as a bean so that the tracing instrumentation gets applied.
+}
        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]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;
 
 Traverson traverson = new Traverson(URI.create("http://some/address"),
     MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate);
-// use Traverson
        15.6.5 Apache HttpClientBuilder and HttpAsyncClientBuilder
        We instrument the HttpClientBuilder and HttpAsyncClientBuilder so that
-tracing context gets injected to the sent requests.
        To block these features, set spring.sleuth.web.client.enabled to false.
        15.6.6 Netty HttpClient
        We instrument the Netty’s HttpClient.
        To block this feature, set spring.sleuth.web.client.enabled to false.
        [Important]Important
        You have to register HttpClient as a bean so that the instrumentation happens.
-If you create a HttpClient instance with a new keyword, the instrumentation does NOT work.
        15.6.7 UserInfoRestTemplateCustomizer
        We instrument the Spring Security’s UserInfoRestTemplateCustomizer.
        To block this feature, set spring.sleuth.web.client.enabled to false.
        15.7 Feign
        By default, Spring Cloud Sleuth provides integration with Feign through TraceFeignClientAutoConfiguration.
+// use Traverson
        15.6.5 Apache HttpClientBuilder and HttpAsyncClientBuilder
        We instrument the HttpClientBuilder and HttpAsyncClientBuilder so that
+tracing context gets injected to the sent requests.
        To block these features, set spring.sleuth.web.client.enabled to false.
        15.6.6 Netty HttpClient
        We instrument the Netty’s HttpClient.
        To block this feature, set spring.sleuth.web.client.enabled to false.
        [Important]Important
        You have to register HttpClient as a bean so that the instrumentation happens.
+If you create a HttpClient instance with a new keyword, the instrumentation does NOT work.
        15.6.7 UserInfoRestTemplateCustomizer
        We instrument the Spring Security’s UserInfoRestTemplateCustomizer.
        To block this feature, set spring.sleuth.web.client.enabled to false.
        15.7 Feign
        By default, Spring Cloud Sleuth provides integration with Feign through TraceFeignClientAutoConfiguration.
 You can disable it entirely by setting spring.sleuth.feign.enabled to false.
 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 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.
 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(() -> {
diff --git a/multi/multi__introduction.html b/multi/multi__introduction.html
index 61fb20321..a06d05a27 100644
--- a/multi/multi__introduction.html
+++ b/multi/multi__introduction.html
@@ -1,6 +1,6 @@
 
       
-   1. Introduction
        1. Introduction
        Prev   Next
        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.
+   1. Introduction
        1. Introduction
        Prev   Next
        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
diff --git a/multi/multi__managing_spans_with_annotations.html b/multi/multi__managing_spans_with_annotations.html
index 2b8601f0a..ffce8c7e5 100644
--- a/multi/multi__managing_spans_with_annotations.html
+++ b/multi/multi__managing_spans_with_annotations.html
@@ -1,6 +1,6 @@
 
       
-   11. Managing Spans with Annotations
        11. Managing Spans with Annotations
        Prev   Next
        11. Managing Spans with Annotations
        You can manage spans with a variety of annotations.
        11.1 Rationale
        There are a number of good reasons to manage spans with annotations, including: