Master Distributed Tracing in Spring Cloud with Sleuth: A Hands‑On Guide

Key concepts of distributed tracing

When a request enters a distributed system, the tracing framework creates a unique TraceId that is propagated through all subsequent service calls, enabling correlation of logs.

Each processing unit, called a span , receives a unique SpanId . By recording the start and end timestamps of a span, its latency can be measured. A span may also carry metadata such as event names or request details.

Enabling tracing with Spring Cloud Sleuth

Adding the spring-cloud-starter-sleuth starter to a Spring Boot project automatically creates tracing for common communication mechanisms (RabbitMQ, Kafka, Zuul, RestTemplate, etc.). Sleuth injects the following B3 headers into outgoing requests: X-B3-TraceId: unique identifier for the entire request chain. X-B3-SpanId: unique identifier for the current span. X-B3-ParentSpanId: identifier of the parent span (empty for the root span). X-B3-Sampled: flag indicating whether the trace should be sampled (1) or not (0). X-Span-Name: name of the span.

Customising header output

The controller below logs the injected tracing headers so they can be observed in the console:

@RequestMapping(value = "/trace-2", method = RequestMethod.GET)
public String trace(HttpServletRequest request) {
    logger.info("=== trace-2, TraceId={}, SpanId={} ===",
        request.getHeader("X-B3-TraceId"),
        request.getHeader("X-B3-SpanId"));
    return "Trace";
}

Running the example and invoking /trace-1 (which calls /trace-2 via RestTemplate) produces log entries similar to:

INFO [trace-1,a6e9175ffd5d2c88,8524f519b8a9e399,true] ...
INFO [trace-2,a6e9175ffd5d2c88,be4949ec115e554e,true] ...

The first log shows the TraceId and SpanId for the initial request; the second log shows the identifiers for the downstream request, demonstrating propagation.

Viewing detailed tracing information

To see the full set of tracing headers and dispatcher‑servlet processing steps, increase the logging level for Spring MVC's dispatcher servlet to DEBUG:

logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG

With this setting, the console prints additional debug entries that include the exact header values and the request handling flow.

Running the example

The complete source code is available in a public Git repository. Clone the repository, build the project with Maven or Gradle, and start the Spring Boot application. Access the endpoints /trace-1 and /trace-2 to observe the generated TraceId and SpanId values and verify that the headers are correctly propagated across service calls.

These steps provide a practical foundation for adding distributed tracing to any Spring Cloud microservice architecture.