SamplerConfiguration -> SamplerProperties

Plus tidy up docs a bit

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%).

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.
 

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

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;
 	}
 

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

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();
 

spring-cloud-sleuth-samples/spring-cloud-sleuth-sample-zipkin/pom.xml

@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 
 	<artifactId>spring-cloud-sleuth-sample-zipkin</artifactId>

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);
 	}
 

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);
 	}