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. 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.
@@ -438,15 +438,263 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-bAdds 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:
+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).
Optionally log span data in JSON format for harvesting in a log aggregator (set spring.sleuth.log.json.enabled=true).
Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations, key-value annotations. Loosely based on HTrace, but Zipkin (Dapper) compatible.
+Instruments common ingress and egress points from Spring applications (servlet filter, rest template, scheduled actions, message channels, zuul filters, feign client).
+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 using Zipkin or Stream, configure the percentage of spans exported using spring.sleuth.sampler.percentage (default 0.1, i.e. 10%).
|
+ Note
+ |
+
+the SLF4J MDC is always set and logback users will immediately see the trace and span ids in logs per the example above. Other logging systems have to configure their own formatter to get the same result. The default is logging.pattern.level set to %clr(%5p) %clr([${spring.application.name:},%X{X-Trace-Id:-},%X{X-Span-Id:-},%X{X-Span-Export:-}]){yellow} (this is a Spring Boot feature for logback users).
+ |
+
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. 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:
+@Bean
+public Sampler<?> defaultSampler() {
+ return new AlwaysSampler();
+}Spring Cloud Sleuth instruments all your Spring application
+automatically, so you shouldn’t have to do anything to activate
+it. The instrumentation is added using a variety of technologies
+according to the stack that is available, e.g. 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, by default an HTTP request will be tagged only with a
+handful of metadata like the status code, host and URL. You can add
+request headers by configuring spring.sleuth.keys.http.headers (a
+list of header names).
|
+ Note
+ |
+
+Remember that tags are only collected and exported if there is a
+Sampler that allows it (by default there is not, so there is no
+danger of accidentally collecting too much data without configuring
+something).
+ |
+
You can accumulate and send span data over
+Spring Cloud Stream by
+including the spring-cloud-sleuth-stream jar as a dependency, and
+adding a Channel Binder implementation
+(e.g. spring-cloud-starter-stream-rabbit for RabbitMQ or
+spring-cloud-starter-stream-kafka for Kafka). This will
+automatically turn your app into a producer of messages with payload
+type Spans.
There is a special convenience annotation for setting up a message consumer
+for the Span data and pushing it into a Zipkin SpanStore. This application
@SpringBootApplication
+@EnableZipkinStreamServer
+public class Consumer {
+ public static void main(String[] args) {
+ SpringApplication.run(Consumer.class, args);
+ }
+}will listen for the Span data on whatever transport you provide via a
+Spring Cloud Stream Binder (e.g. include
+spring-cloud-starter-stream-rabbit for RabbitMQ, and similar
+starters exist for Redis and Kafka). The app will also be a
+Zipkin query server, so you
+can point a standard Zipkin UI at it (e.g. run the consumer app on
+port 9411 if you want the query server on the same host and the
+default configuration).
The deafult SpanStore is in-memory (good for demos and getting
+started quickly). For a more robust solution you can add MySQL and
+spring-boot-starter-jdbc to your classpath and enable the JDBC
+SpanStore via configuration, e.g.:
spring:
+ rabbitmq:
+ host: ${RABBIT_HOST:localhost}
+ datasource:
+ schema: classpath:/mysql.sql
+ url: jdbc:mysql://${MYSQL_HOST:localhost}/test
+ username: root
+ password: root
+# Switch this on to create the schema on startup:
+ initialize: true
+ continueOnError: true
+ sleuth:
+ enabled: false
+zipkin:
+ store:
+ 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.
+ |
+
A custom consumer can also easily be implemented using
+spring-cloud-sleuth-stream and binding to the SleuthSink. Example:
@EnableBinding(SleuthSink.class)
+@SpringBootApplication(exclude = SleuthStreamAutoConfiguration.class)
+@MessageEndpoint
+public class Consumer {
+ @ServiceActivator(inputChannel = SleuthSink.INPUT)
+ public void sink(Spans input) throws Exception {
+ // ... process spans
+ }
+}|
+ Note
+ |
+
+the sample consumer application above explicitly excludes
+SleuthStreamAutoConfiguration so it doesn’t send messages to itself,
+but this is optional (you might actually want to trace requests into
+the consumer app).
+ |
+