Integrating Spring Cloud Sleuth with Zipkin for Distributed Tracing and Persistence

This article introduces the concept of distributed tracing in large microservice systems and explains why it is needed to visualize service dependencies, quickly locate exceptions, and identify performance bottlenecks.

Common tracing technologies

Popular open‑source tracing projects include Cat, Zipkin, Pinpoint, SkyWalking, and Spring Cloud Sleuth. Zipkin, originally from Twitter, works together with Spring Cloud Sleuth to collect and display trace data.

What is Spring Cloud Sleuth?

Spring Cloud Sleuth generates trace information for each request and logs it, but it does not provide a UI. Key concepts are:

Span : the basic unit of work with a unique ID and timestamps.

Trace : a tree of spans identified by a traceId that propagates across services.

Annotation : markers such as cs (client send), sr (server received), ss (server send), and cr (client received) that describe the lifecycle of a request.

Integrating Sleuth into a Spring Cloud project

Three example services are used:

gateway‑sleuth9031 – gateway service

sleuth‑product9032 – product microservice

sleuth‑order9033 – order microservice

The services call each other as shown in the diagram (gateway → order → product). Add the Sleuth starter dependency:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>

Set the log level to debug for both Sleuth and OpenFeign in each service’s application.yml :

logging:
  level:
    org.springframework.cloud.openfeign: debug
    org.springframework.cloud.sleuth: debug

After starting the three services, accessing http://localhost:9031/order/get/12 shows detailed trace logs in the console.

Zipkin overview

Zipkin consists of four core components: Collector, Storage, RESTful API, and UI. It receives trace data from clients (e.g., Sleuth) and visualizes it.

Running a Zipkin server

Download the executable JAR and start it:

java -jar zipkin-server-2.23.4-exec.jar

The UI is available at http://localhost:9411 .

Adding Zipkin to the client services

Include the Zipkin starter (which already pulls in Sleuth):

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-zipkin</artifactId>
</dependency>

Configure the Zipkin server address and sampling rate in application.yml :

spring:
  cloud:
    sleuth:
      sampler:
        probability: 1.0
    zipkin:
      base-url: http://127.0.0.1:9411
      discovery-client-enabled: false

Switching transport to MQ (RabbitMQ)

Start Zipkin with RabbitMQ collector:

java -jar zipkin-server-2.23.4-exec.jar \
  --zipkin.collector.rabbitmq.addresses=localhost \
  --zipkin.collector.rabbitmq.username=guest \
  --zipkin.collector.rabbitmq.password=guest

Add the RabbitMQ starter to each service:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-amqp</artifactId>
</dependency>

Configure RabbitMQ connection and set the sender type to rabbit :

spring:
  cloud:
    zipkin:
      sender:
        type: rabbit

Persisting Zipkin data with MySQL

Run Zipkin with MySQL storage:

java -jar zipkin-server-2.23.4-exec.jar \
  --STORAGE_TYPE=mysql \
  --MYSQL_HOST=127.0.0.1 \
  --MYSQL_TCP_PORT=3306 \
  --MYSQL_DB=zipkin \
  --MYSQL_USER=root \
  --MYSQL_PASS=Nov2014

The required schema is provided in zipkin-storage/mysql-v1/src/main/resources/mysql.sql . After starting the server, trace data is stored in the MySQL tables.

Conclusion

Spring Cloud Sleuth provides trace data generation; Zipkin offers visualization and analysis.

For production, use MQ transport (e.g., RabbitMQ) to avoid data loss and improve performance.

MySQL can persist traces, but for large volumes Elasticsearch is recommended.