From 9bfe36451804e25cb6500ba9d7e3a2839ea0e16f Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Tue, 2 Feb 2016 16:15:35 +0000 Subject: [PATCH] SamplerConfiguration -> SamplerProperties Plus tidy up docs a bit --- docs/src/main/asciidoc/features.adoc | 15 +++++----- docs/src/main/asciidoc/intro.adoc | 2 +- .../main/asciidoc/spring-cloud-sleuth.adoc | 28 +++++++++++++------ .../sampler/PercentageBasedSampler.java | 4 +-- ...figuration.java => SamplerProperties.java} | 2 +- .../sampler/PercentageBasedSamplerTests.java | 2 +- .../spring-cloud-sleuth-sample-zipkin/pom.xml | 5 ++-- .../stream/SleuthStreamAutoConfiguration.java | 6 ++-- .../zipkin/ZipkinAutoConfiguration.java | 6 ++-- 9 files changed, 41 insertions(+), 29 deletions(-) rename spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/{SamplerConfiguration.java => SamplerProperties.java} (93%) diff --git a/docs/src/main/asciidoc/features.adoc b/docs/src/main/asciidoc/features.adoc index 0e9f91b80..4470cf909 100644 --- a/docs/src/main/asciidoc/features.adoc +++ b/docs/src/main/asciidoc/features.adoc @@ -1,15 +1,14 @@ == 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. Example configuration: +* 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. Example logs: + -[source,yaml] ---- -logging: - pattern: - level: '[trace=%X{X-Trace-Id:-},span=%X{X-Span-Id:-}] %5p' +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 `%X` entries from the MDC). +(notice the `[appname,traceId,spanId,exportable]` entries from the MDC). * Optionally log span data in JSON format for harvesting in a log aggregator (set `spring.sleuth.log.json.enabled=true`). @@ -19,4 +18,6 @@ logging: * If `spring-cloud-sleuth-zipkin` then the app will generate and collect Zipkin-compatible traces (using Brave). By default it sends them via HTTP to a Zipkin server on localhost (port 9411). Configure the location of the service using `spring.zipkin.[host,port]`. -* If `spring-cloud-sleuth-stream` then the app will generate and collect traces via Spring Cloud Stream. Your app automatically becomes a producer of tracer messages that are sent over your broker of choice (e.g. RabbitMQ, Apache Kafka, Redis). +* If `spring-cloud-sleuth-stream` then the app will generate and collect traces via Spring Cloud Stream. Your app automatically becomes a producer of tracer messages that are sent over your broker of choice (e.g. RabbitMQ, Apache Kafka, Redis). + +If using Zipkin or Stream, configure the percentage of spans exported using `spring.sleuth.sampler.percentage` (default 0.1, i.e. 10%). diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/src/main/asciidoc/intro.adoc index a82ec40e1..fa252f7ae 100644 --- a/docs/src/main/asciidoc/intro.adoc +++ b/docs/src/main/asciidoc/intro.adoc @@ -6,7 +6,7 @@ Spring Cloud Sleuth implements a distributed tracing solution for http://cloud.s Spring Cloud Sleuth borrows http://research.google.com/pubs/pub36356.html[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. Span's 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, key-value annotations, the ID of the span that caused them, and process ID's (normally IP address). +*Span:* The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an RPC. Span's 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 ID's (normally IP address). Spans are 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. diff --git a/docs/src/main/asciidoc/spring-cloud-sleuth.adoc b/docs/src/main/asciidoc/spring-cloud-sleuth.adoc index e7817f071..b8a4bcfc7 100644 --- a/docs/src/main/asciidoc/spring-cloud-sleuth.adoc +++ b/docs/src/main/asciidoc/spring-cloud-sleuth.adoc @@ -14,14 +14,21 @@ In distributed tracing the data volumes can be very high so sampling can be important (you usually don't need to export all spans to get a good picture of what is happening). Spring Cloud Sleuth has a `Sampler` strategy that you can implement to take control of the -sampling algorithm. By default you get a strategy that continues to -trace if a span is already active, but never starts a new one with the -exportable flag set. If all your apps run with this sampler you will -see traces in logs, but not in any remote store. For testing the -default is often enough, and it probably is all you need if you are -only using the logs (e.g. with an ELK aggregator). If you are -exporting span data to Zipkin or Spring Cloud Stream, there is also an -`AlwaysSampler` that exports everything. +sampling algorithm. Samplers do not stop span (correlation) ids from +being generated, but they do prevent the tags and events being +attached and exported. By default you get a strategy that continues to +trace if a span is already active, but new ones are always marked as +non-exportable. If all your apps run with this sampler you will see +traces in logs, but not in any remote store. For testing the default +is often enough, and it probably is all you need if you are only using +the logs (e.g. with an ELK aggregator). If you are exporting span data +to Zipkin or Spring Cloud Stream, there is also an `AlwaysSampler` +that exports everything and a `PercentageBasedSampler` that samples a +fixed fraction of spans. + +NOTE: the `PercentageBasedSampler` is the default if you are using +`spring-cloud-sleuth-zipkin` or `spring-cloud-sleuth-stream`. You can +configure the exports using `spring.sleuth.sampler.percentage`. A sampler can be installed just by creating a bean definition, e.g: @@ -114,6 +121,11 @@ zipkin: type: mysql ---- +NOTE: The `@EnableZipkinStreamServer` is also annotated with +`@EnableZipkinServer` so the process will also expose the standard +Zipkin server endpoints for collecting spans over HTTP, and for +querying in the Zipkin Web UI. + === Custom Consumer A custom consumer can also easily be implemented using diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java index 1aeffa3a7..03bbbdc44 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSampler.java @@ -21,9 +21,9 @@ import org.springframework.cloud.sleuth.Span; */ public class PercentageBasedSampler implements Sampler { - private final SamplerConfiguration configuration; + private final SamplerProperties configuration; - public PercentageBasedSampler(SamplerConfiguration configuration) { + public PercentageBasedSampler(SamplerProperties configuration) { this.configuration = configuration; } diff --git a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerConfiguration.java b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerProperties.java similarity index 93% rename from spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerConfiguration.java rename to spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerProperties.java index ce06c250b..986ef55f0 100644 --- a/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerConfiguration.java +++ b/spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/sampler/SamplerProperties.java @@ -10,7 +10,7 @@ import lombok.Data; */ @ConfigurationProperties("spring.sleuth.sampler") @Data -public class SamplerConfiguration { +public class SamplerProperties { /** * Percentage of requests that should be sampled. E.g. 1.0 - 100% requests should be diff --git a/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSamplerTests.java b/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSamplerTests.java index 2e4fb5331..685aef142 100644 --- a/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSamplerTests.java +++ b/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/sampler/PercentageBasedSamplerTests.java @@ -11,7 +11,7 @@ import org.springframework.cloud.sleuth.Span; public class PercentageBasedSamplerTests { - SamplerConfiguration samplerConfiguration = new SamplerConfiguration(); + SamplerProperties samplerConfiguration = new SamplerProperties(); private Span span; private static Random RANDOM = new Random(); diff --git a/spring-cloud-sleuth-samples/spring-cloud-sleuth-sample-zipkin/pom.xml b/spring-cloud-sleuth-samples/spring-cloud-sleuth-sample-zipkin/pom.xml index 87713bf70..edbd23635 100644 --- a/spring-cloud-sleuth-samples/spring-cloud-sleuth-sample-zipkin/pom.xml +++ b/spring-cloud-sleuth-samples/spring-cloud-sleuth-sample-zipkin/pom.xml @@ -1,7 +1,6 @@ - + 4.0.0 spring-cloud-sleuth-sample-zipkin diff --git a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java index 72af18f12..528a1e738 100644 --- a/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java +++ b/spring-cloud-sleuth-stream/src/main/java/org/springframework/cloud/sleuth/stream/SleuthStreamAutoConfiguration.java @@ -30,7 +30,7 @@ import org.springframework.cloud.sleuth.Sampler; import org.springframework.cloud.sleuth.Span; import org.springframework.cloud.sleuth.metric.SpanReporterService; import org.springframework.cloud.sleuth.sampler.PercentageBasedSampler; -import org.springframework.cloud.sleuth.sampler.SamplerConfiguration; +import org.springframework.cloud.sleuth.sampler.SamplerProperties; import org.springframework.cloud.stream.annotation.EnableBinding; import org.springframework.cloud.stream.config.ChannelBindingAutoConfiguration; import org.springframework.context.annotation.Bean; @@ -52,7 +52,7 @@ import org.springframework.messaging.support.ChannelInterceptorAdapter; * @author Dave Syer */ @Configuration -@EnableConfigurationProperties({SleuthStreamProperties.class, SamplerConfiguration.class}) +@EnableConfigurationProperties({SleuthStreamProperties.class, SamplerProperties.class}) @AutoConfigureBefore(ChannelBindingAutoConfiguration.class) @EnableBinding(SleuthSource.class) @ConditionalOnProperty(value = "spring.sleuth.stream.enabled", matchIfMissing = true) @@ -60,7 +60,7 @@ public class SleuthStreamAutoConfiguration { @Bean @ConditionalOnMissingBean - public Sampler defaultTraceSampler(SamplerConfiguration config) { + public Sampler defaultTraceSampler(SamplerProperties config) { return new PercentageBasedSampler(config); } diff --git a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java index 28635ba40..2093e6ebf 100644 --- a/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java +++ b/spring-cloud-sleuth-zipkin/src/main/java/org/springframework/cloud/sleuth/zipkin/ZipkinAutoConfiguration.java @@ -30,7 +30,7 @@ import org.springframework.cloud.sleuth.Sampler; import org.springframework.cloud.sleuth.autoconfig.TraceAutoConfiguration; import org.springframework.cloud.sleuth.metric.SpanReporterService; import org.springframework.cloud.sleuth.sampler.PercentageBasedSampler; -import org.springframework.cloud.sleuth.sampler.SamplerConfiguration; +import org.springframework.cloud.sleuth.sampler.SamplerProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @@ -39,7 +39,7 @@ import org.springframework.context.annotation.Configuration; * @author Spencer Gibb */ @Configuration -@EnableConfigurationProperties({ZipkinProperties.class, SamplerConfiguration.class}) +@EnableConfigurationProperties({ZipkinProperties.class, SamplerProperties.class}) @ConditionalOnProperty(value = "spring.zipkin.enabled", matchIfMissing = true) @AutoConfigureBefore(TraceAutoConfiguration.class) public class ZipkinAutoConfiguration { @@ -53,7 +53,7 @@ public class ZipkinAutoConfiguration { @Bean @ConditionalOnMissingBean - public Sampler defaultTraceSampler(SamplerConfiguration config) { + public Sampler defaultTraceSampler(SamplerProperties config) { return new PercentageBasedSampler(config); }