Home
Projects
Guides
Blog
Training & Certification

Spring Cloud Sleuth

2.1.0 RC2

Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud, borrowing heavily from Dapper, Zipkin and HTrace. For most users Sleuth should be invisible, and all your interactions with external systems should be instrumented automatically. You can capture data simply in logs, or by sending it to a remote collector service.

Features

A Span is 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). 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. A set of spans forming a tree-like structure called a Trace. For example, if you are running a distributed big-data store, a trace might be formed by a put request.

Spring Cloud Sleuth 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.

  • 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 is available then the app will generate and collect Zipkin-compatible traces via HTTP. By default it sends them to a Zipkin collector service on localhost (port 9411). Configure the location of the service using spring.zipkin.baseUrl.

Spring Boot Config

Add Sleuth to your classpath:

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-sleuth</artifactId>
            <version>${spring-cloud-sleuth.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-sleuth</artifactId>
    </dependency>
</dependencies>

Gradle

buildscript {
    dependencies {
        classpath "io.spring.gradle:dependency-management-plugin:0.5.2.RELEASE"
    }
}

apply plugin: "io.spring.dependency-management"

dependencyManagement {
     imports {
          mavenBom "org.springframework.cloud:spring-cloud-sleuth:${springCloudSleuthVersion}"
     }
}
dependencies {
    compile 'org.springframework.cloud:spring-cloud-starter-sleuth'
}

As long as Spring Cloud Sleuth is on the classpath any Spring Boot application will generate trace data:

@SpringBootApplication
@RestController
public class Application {

  private static Logger log = LoggerFactory.getLogger(DemoController.class);

  @RequestMapping("/")
  public String home() {
    log.info("Handling home");
    return "Hello World";
  }

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

}

Run this app and then hit the home page. You will see traceId and spanId populated in the logs. If this app calls out to another one (e.g. with RestTemplate) it will send the trace data in headers and if the receiver is another Sleuth app you will see the trace continue there.

Important
 instead of logging the request in the handler explicitly, you could set logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG
Important
 If you use Zipkin, configure the probability of spans exported by setting (for 2.0.x) spring.sleuth.sampler.probability or (up till 2.0.x)spring.sleuth.sampler.percentage (default: 0.1, which is 10 percent). Otherwise, you might think that Sleuth is not working because it omits some spans.
Important
 Set spring.application.name=bar (for instance) to see the service name as well as the trace and span ids.

Quick start

Bootstrap your application with Spring Initializr.

Documentation

Each Spring project has its own; it explains in great details how you can use project features and what you can achieve with them.
2.1.0 RC2 PRE CURRENT Reference Doc. API Doc.
2.0.3 SNAPSHOT CURRENT Reference Doc. API Doc.
2.0.2 CURRENT GA Reference Doc. API Doc.
1.3.5 SNAPSHOT CURRENT Reference Doc. API Doc.
1.3.4 CURRENT GA Reference Doc. API Doc.
1.2.7 SNAPSHOT Reference Doc. API Doc.
1.2.6 GA Reference Doc. API Doc.
1.2.5 GA Reference Doc. API Doc.
1.1.4 SNAPSHOT Reference Doc. API Doc.
1.1.3 GA Reference Doc. API Doc.
1.0.12 GA Reference Doc. API Doc.