Note: {@code fieldName} will be implicitly lower-cased. @see brave.propagation.ExtraFieldPropagation.FactoryBuilder#addField(String) +|spring.sleuth.propagation.tag.enabled | true | Enables a {@link TagPropagationFinishedSpanHandler} that adds extra propagated fields to span tags. +|spring.sleuth.propagation.tag.whitelisted-keys | | A list of keys to be put from extra propagation fields to span tags. +|spring.sleuth.reactor.enabled.enabled | true | When true enables instrumentation for reactor. +|spring.sleuth.redis.enabled | true | Enable span information propagation when using Redis. +|spring.sleuth.rxjava.schedulers.hook.enabled | true | Enable support for RxJava via RxJavaSchedulersHook. +|spring.sleuth.rxjava.schedulers.ignoredthreads | [HystrixMetricPoller, ^RxComputation.*$] | Thread names for which spans will not be sampled. +|spring.sleuth.sampler.probability | | Probability of requests that should be sampled. E.g. 1.0 - 100% requests should be sampled. The precision is whole-numbers only (i.e. there's no support for 0.1% of the traces). +|spring.sleuth.sampler.rate | 10 | A rate per second can be a nice choice for low-traffic endpoints as it allows you surge protection. For example, you may never expect the endpoint to get more than 50 requests per second. If there was a sudden surge of traffic, to 5000 requests per second, you would still end up with 50 traces per second. Conversely, if you had a percentage, like 10%, the same surge would end up with 500 traces per second, possibly overloading your storage. Amazon X-Ray includes a rate-limited sampler (named Reservoir) for this purpose. Brave has taken the same approach via the {@link brave.sampler.RateLimitingSampler}. +|spring.sleuth.scheduled.enabled | true | Enable tracing for {@link org.springframework.scheduling.annotation.Scheduled}. +|spring.sleuth.scheduled.skip-pattern | org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask | Pattern for the fully qualified name of a class that should be skipped. +|spring.sleuth.supports-join | true | True means the tracing system supports sharing a span ID between a client and server. +|spring.sleuth.trace-id128 | false | When true, generate 128-bit trace IDs instead of 64-bit ones. +|spring.sleuth.web.additional-skip-pattern | | Additional pattern for URLs that should be skipped in tracing. This will be appended to the {@link SleuthWebProperties#skipPattern}. +|spring.sleuth.web.client.enabled | true | Enable interceptor injecting into {@link org.springframework.web.client.RestTemplate}. +|spring.sleuth.web.client.skip-pattern | | Pattern for URLs that should be skipped in client side tracing. +|spring.sleuth.web.enabled | true | When true enables instrumentation for web applications. +|spring.sleuth.web.exception-logging-filter-enabled | true | Flag to toggle the presence of a filter that logs thrown exceptions. +|spring.sleuth.web.exception-throwing-filter-enabled | true | Flag to toggle the presence of a filter that logs thrown exceptions. @deprecated use {@link #exceptionLoggingFilterEnabled} +|spring.sleuth.web.filter-order | | Order in which the tracing filters should be registered. Defaults to {@link TraceHttpAutoConfiguration#TRACING_FILTER_ORDER}. +|spring.sleuth.web.ignore-auto-configured-skip-patterns | false | If set to true, auto-configured skip patterns will be ignored. @see TraceWebAutoConfiguration +|spring.sleuth.web.skip-pattern | /api-docs.*\|/swagger.*\|.*\.png\|.*\.css\|.*\.js\|.*\.html\|/favicon.ico\|/hystrix.stream | Pattern for URLs that should be skipped in tracing. +|spring.sleuth.zuul.enabled | true | Enable span information propagation when using Zuul. +|spring.zipkin.activemq.message-max-bytes | 100000 | Maximum number of bytes for a given message with spans sent to Zipkin over ActiveMQ. +|spring.zipkin.activemq.queue | zipkin | Name of the ActiveMQ queue where spans should be sent to Zipkin. +|spring.zipkin.base-url | http://localhost:9411/ | URL of the zipkin query server instance. You can also provide the service id of the Zipkin server if Zipkin's registered in service discovery (e.g. https://zipkinserver/). +|spring.zipkin.compression.enabled | false | +|spring.zipkin.discovery-client-enabled | | If set to {@code false}, will treat the {@link ZipkinProperties#baseUrl} as a URL always. +|spring.zipkin.enabled | true | Enables sending spans to Zipkin. +|spring.zipkin.encoder | | Encoding type of spans sent to Zipkin. Set to {@link SpanBytesEncoder#JSON_V1} if your server is not recent. +|spring.zipkin.kafka.topic | zipkin | Name of the Kafka topic where spans should be sent to Zipkin. +|spring.zipkin.locator.discovery.enabled | false | Enabling of locating the host name via service discovery. +|spring.zipkin.message-timeout | 1 | Timeout in seconds before pending spans will be sent in batches to Zipkin. +|spring.zipkin.rabbitmq.queue | zipkin | Name of the RabbitMQ queue where spans should be sent to Zipkin. +|spring.zipkin.sender.type | | Means of sending spans to Zipkin. +|spring.zipkin.service.name | | The name of the service, from which the Span was sent via HTTP, that should appear in Zipkin. + +|=== diff --git a/docs/src/main/asciidoc/appendix.adoc b/docs/src/main/asciidoc/appendix.adoc new file mode 100644 index 000000000..2c18b8653 --- /dev/null +++ b/docs/src/main/asciidoc/appendix.adoc @@ -0,0 +1,14 @@ +:numbered!: +[appendix] +[[common-application-properties]] +== Common application properties + +include::_attributes.adoc[] + +Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. +This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them. + +NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list. +Also, you can define your own properties. + +include::_configprops.adoc[] \ No newline at end of file diff --git a/docs/src/main/asciidoc/features.adoc b/docs/src/main/asciidoc/features.adoc index 9123b260f..7fa30f13c 100644 --- a/docs/src/main/asciidoc/features.adoc +++ b/docs/src/main/asciidoc/features.adoc @@ -1,3 +1,5 @@ +include::_attributes.adoc[] + == 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: diff --git a/docs/src/main/asciidoc/spring-cloud-sleuth.adoc b/docs/src/main/asciidoc/spring-cloud-sleuth.adoc index 547bfda2d..c2c7fa371 100644 --- a/docs/src/main/asciidoc/spring-cloud-sleuth.adoc +++ b/docs/src/main/asciidoc/spring-cloud-sleuth.adoc @@ -1,16 +1,9 @@ -:github-tag: master -:github-repo: spring-cloud/spring-cloud-sleuth -:github-raw: https://raw.githubusercontent.com/{github-repo}/{github-tag} -:github-code: https://github.com/{github-repo}/tree/{github-tag} -:toc: left -:toclevels: 8 -:nofooter: -:sectlinks: true - Spring Cloud Sleuth ==================== Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer, Jay Bryant +include::_attributes.adoc[] + *{spring-cloud-version}* :doctype: book @@ -324,7 +317,7 @@ A sampler can be installed by creating a bean definition, as shown in the follow [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=always_sampler,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=always_sampler,indent=0] ---- TIP: You can set the HTTP header `X-B3-Flags` to `1`, or, when doing messaging, you can set the `spanFlags` header to `1`. @@ -609,7 +602,7 @@ You can manually create spans by using the `Tracer`, as shown in the following e [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=manual_span_creation,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=manual_span_creation,indent=0] ---- In the preceding example, we could see how to create a new instance of the span. @@ -634,7 +627,7 @@ To continue a span, you can use `brave.Tracer`, as shown in the following exampl [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=manual_span_continuation,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=manual_span_continuation,indent=0] ---- [[creating-spans-with-explicit-parent]] @@ -647,7 +640,7 @@ You can put the span in scope and then call `nextSpan()`, as shown in the follow [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=manual_span_joining,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=manual_span_joining,indent=0] ---- IMPORTANT: After creating such a span, you must finish it. Otherwise it is not reported (for example, to Zipkin). @@ -671,14 +664,14 @@ You can name the span explicitly by using the `@SpanName` annotation, as shown i [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=span_name_annotation,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=span_name_annotation,indent=0] ---- In this case, when processed in the following manner, the span is named `calculateTax`: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=span_name_annotated_runnable_execution,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=span_name_annotated_runnable_execution,indent=0] ---- === `toString()` method @@ -692,7 +685,7 @@ Running such code leads to creating a span named `calculateTax`, as shown in the [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=span_name_to_string_runnable_execution,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=span_name_to_string_runnable_execution,indent=0] ---- == Managing Spans with Annotations @@ -720,14 +713,14 @@ Now we can consider some examples of usage. [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=annotated_method,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=annotated_method,indent=0] ---- Annotating the method without any parameter leads to creating a new span whose name equals the annotated method name. [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=custom_name_on_annotated_method,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=custom_name_on_annotated_method,indent=0] ---- If you provide the value in the annotation (either directly or by setting the `name` parameter), the created span has the provided value as the name. @@ -735,10 +728,10 @@ If you provide the value in the annotation (either directly or by setting the `n [source,java] ---- // method declaration -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=custom_name_and_tag_on_annotated_method,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=custom_name_and_tag_on_annotated_method,indent=0] // and method execution -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=execution,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=execution,indent=0] ---- You can combine both the name and a tag. Let's focus on the latter. @@ -747,7 +740,7 @@ In our sample, the tag key is `testTag`, and the tag value is `test`. [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=name_on_implementation,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=name_on_implementation,indent=0] ---- You can place the `@NewSpan` annotation on both the class and an interface. @@ -761,10 +754,10 @@ If you want to add tags and annotations to an existing span, you can use the `@C [source,java] ---- // method declaration -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=continue_span,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=continue_span,indent=0] // method execution -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=continue_span_execution,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SleuthSpanCreatorAspectTests.java[tags=continue_span_execution,indent=0] ---- (Note that, in contrast with the `@NewSpan` annotation ,you can also add logs with the `log` parameter.) @@ -796,14 +789,14 @@ Consider the following annotated method: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=resolver_bean,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=resolver_bean,indent=0] ---- Now further consider the following `TagValueResolver` bean implementation: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=custom_resolver,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=custom_resolver,indent=0] ---- The two preceding examples lead to setting a tag value equal to `Value from myCustomTagValueResolver`. @@ -814,7 +807,7 @@ Consider the following annotated method: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=spel,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=spel,indent=0] ---- 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. @@ -826,7 +819,7 @@ Consider the following annotated method: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=toString,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/annotation/SpanTagAnnotationHandlerTests.java[tags=toString,indent=0] ---- Running the preceding method with a value of `15` leads to setting a tag with a String value of `"15"`. @@ -865,7 +858,7 @@ an example of usage of `SkipPatternProvider` inside a server side, `HttpSampler` ---- @Configuration class Config { -include::{github-raw}/tests/spring-cloud-sleuth-instrumentation-mvc-tests/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterWebIntegrationTests.java[tags=custom_server_sampler,indent=2] +include::{project-root}/tests/spring-cloud-sleuth-instrumentation-mvc-tests/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterWebIntegrationTests.java[tags=custom_server_sampler,indent=2] } ---- @@ -878,7 +871,7 @@ In the following example, we register the `TracingFilter` bean, add the `ZIPKIN- [source,java] ---- -include::{github-raw}/tests/spring-cloud-sleuth-instrumentation-mvc-tests/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterIntegrationTests.java[tags=response_headers,indent=0] +include::{project-root}/tests/spring-cloud-sleuth-instrumentation-mvc-tests/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterIntegrationTests.java[tags=response_headers,indent=0] ---- === Custom service name @@ -906,7 +899,7 @@ The following example shows how to register two beans that implement `FinishedSp [source,java] ---- -include::{github-raw}//spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/FinishedSpanHandlerTests.java[tags=finishedSpanHandler,indent=0] +include::{project-root}//spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/FinishedSpanHandlerTests.java[tags=finishedSpanHandler,indent=0] ---- The preceding example results in changing the name of the reported span to `foo bar`, just before it gets reported (for example, to Zipkin). @@ -1020,14 +1013,14 @@ If you wrap your logic in `Runnable` or `Callable`, you can wrap those classes i [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=trace_runnable,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=trace_runnable,indent=0] ---- The following example shows how to do so for `Callable`: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=trace_callable,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java[tags=trace_callable,indent=0] ---- That way, you ensure that a new span is created and closed for each execution. @@ -1047,7 +1040,7 @@ Assume that you have the following `HystrixCommand`: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/hystrix/TraceCommandTests.java[tags=hystrix_command,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/hystrix/TraceCommandTests.java[tags=hystrix_command,indent=0] ---- To pass the tracing information, you have to wrap the same logic in the Sleuth version of the `HystrixCommand`, which is called @@ -1055,7 +1048,7 @@ To pass the tracing information, you have to wrap the same logic in the Sleuth v [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/hystrix/TraceCommandTests.java[tags=trace_hystrix_command,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/hystrix/TraceCommandTests.java[tags=trace_hystrix_command,indent=0] ---- === RxJava @@ -1170,7 +1163,7 @@ In the following snippet, you can see an example of how to set up such a custom [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/client/MultipleAsyncRestTemplateTests.java[tags=custom_async_rest_template,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/client/MultipleAsyncRestTemplateTests.java[tags=custom_async_rest_template,indent=0] ---- ==== `WebClient` @@ -1309,7 +1302,7 @@ The following example shows how to pass tracing information with `TraceableExecu [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/async/TraceableExecutorServiceTests.java[tags=completablefuture,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/async/TraceableExecutorServiceTests.java[tags=completablefuture,indent=0] ---- IMPORTANT: Sleuth does not work with `parallelStream()` out of the box. @@ -1326,7 +1319,7 @@ The following example shows how to set up such a custom `Executor`: [source,java] ---- -include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/client/MultipleAsyncRestTemplateTests.java[tags=custom_executor,indent=0] +include::{project-root}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/client/MultipleAsyncRestTemplateTests.java[tags=custom_executor,indent=0] ---- TIP: To ensure that your configuration gets post processed, remember @@ -1404,6 +1397,10 @@ We instrument quartz jobs by adding Job/Trigger listeners to the Quartz Schedule To turn off this feature, set the `spring.sleuth.quartz.enabled` property to `false`. +== Configuration properties + +To see the list of all Sleuth related configuration properties please check link:appendix.html[the Appendix page]. + == Running examples You can see the running examples deployed in the https://run.pivotal.io/[Pivotal Web Services]. diff --git a/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java b/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java index 0742a15dc..ead5999b8 100644 --- a/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java +++ b/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/documentation/SpringCloudSleuthDocTests.java @@ -114,7 +114,6 @@ public class SpringCloudSleuthDocTests { then(spans.get(0).name()).isEqualTo("calculatetax"); executorService.shutdown(); } - // end::span_name_annotation[] @Test public void should_create_a_span_with_tracer() { @@ -305,5 +304,6 @@ public class SpringCloudSleuthDocTests { } } + // end::span_name_annotation[] }