Theo Dõi Request Xuyên Dịch Vụ Với Spring Cloud Sleuth | Lộ Trình Java Spring

Spring Cloud Sleuth không còn là thứ bạn cài vào dự án mới: dự án đã archive ở dòng 3.1 và không có bản nào chạy trên Boot 3+. Nhưng mô hình phía sau nó — trace, span, lan truyền context — vẫn là nền tảng của theo dõi request xuyên dịch vụ. Bài này giữ phần khái niệm và thay phần triển khai bằng Micrometer Tracing 1.7.2 + OpenTelemetry trên Boot 4.1.2, kèm bảng mapping cho code Sleuth cũ.

Cập nhật 2026

  • Sleuth đã archive. Dòng cuối là 3.1, không hỗ trợ Boot 3+; starter của nó chỉ chạy trên Boot 2.x và không nhận bản vá.
  • Thay thế: Micrometer Tracing 1.7.2, bridge OpenTelemetry (OTel SDK 1.62.0) hoặc bridge Brave 6.3.1, exporter OTLP hoặc Zipkin.
  • Boot 4.1.2 có starter riêng: spring-boot-starter-opentelemetry gói sẵn bridge, exporter OTLP và registry metric; spring-boot-starter-zipkin lo đường Zipkin, không phải tự ghép bridge với reporter.
  • Property đổi tên: spring.sleuth.* → management.tracing.*. Sampling mặc định là 0.1, propagation produce mặc định chỉ W3C.

Theo dõi request xuyên dịch vụ giải quyết vấn đề gì

Một đơn hàng đi qua gateway, order-service, inventory-service, payment-service rồi notification-service. Khách báo đơn chậm bốn giây. Bạn có log ở cả năm service, mỗi service ghi timestamp riêng và không biết request đã đi qua đâu; ghép chúng bằng tay là đọc hàng nghìn dòng, có khi đã bị log rotation cắt mất.

Distributed tracing sinh một trace ID khi request vào hệ thống; mỗi bước xử lý tạo một span mang cùng trace ID và ID của span cha. Kết quả là cây thời gian thay vì log rời rạc, trả lời nhanh ba câu: chặng nào chiếm phần lớn độ trễ, service nào lỗi trước, request có đi đúng đường không.

Trace, span, trace ID và span ID

  • Trace: toàn bộ hành trình của một request, gồm nhiều span có quan hệ cha–con.
  • Span: một đơn vị công việc có thời điểm bắt đầu và kết thúc — một lời gọi HTTP, một truy vấn DB, một lần publish message, hoặc một hàm nghiệp vụ bạn tự bọc.
  • Trace ID: 128-bit, giống nhau ở mọi span của cùng một trace. Đây là khoá bạn dùng để tìm log và trace.
  • Span ID: 64-bit, định danh một span; mỗi span (trừ span gốc) có parent span ID trỏ tới span đã gọi nó.
trace 7f3a9c... (một request)
├─ gateway (12 ms)
│  └─ order.place (380 ms)
│     ├─ POST inventory/reserve (120 ms)
│     │  └─ SELECT inventory (40 ms)
│     └─ POST payment/charge (210 ms)
└─ kafka consume OrderPlaced (…)

Span cha–con quyết định cách đọc latency: 380 ms của order.place bao gồm hai lời gọi con, không phải thời gian xử lý riêng. Chỉ nhìn span gốc, bạn sẽ kết luận sai rằng order-service chậm trong khi thời gian thật nằm ở payment.

Lan truyền context: W3C traceparent và tracestate

Trace chỉ xuyên được service khi context đi theo request. Chuẩn hiện hành là W3C Trace Context với header traceparent, dạng 00-<trace-id>-<parent-id>-<flags>: phiên bản, trace ID 16 byte hex, span ID 8 byte hex, và byte cờ. Bit sampled cho downstream biết request có được ghi nhận, để service sau không tự đổi quyết định.

tracestate đi kèm để vendor thêm trạng thái riêng mà không phá định dạng chuẩn. baggage là header thứ ba, chở các cặp key–value nghiệp vụ như tenant-id qua mọi chặng. Micrometer Tracing mặc định chỉ sản xuất W3C nhưng vẫn đọc được B3, nên hệ thống cũ chuyển dần mà không phải cắt phanh.

Ba header này là hợp đồng giữa các service. Nếu một chặng không forward traceparent, trace bị đứt và span phía sau thành trace mới — triệu chứng điển hình là “cùng một request nhưng ba trace ID khác nhau”.

Vì sao Sleuth dừng, và cái gì thay thế nó

Sleuth từng làm hai việc: instrument các điểm tích hợp của Spring và nói chuyện với backend qua Brave. Khi Spring chuyển sang Observation API, phần instrument và vòng đời span vào Micrometer Tracing, phần format và export do bridge quyết định. Sleuth 3.1 không được port sang Boot 3+ nên là ngõ cụt.

Stack mới có bốn lớp, và biết lớp nào làm gì sẽ giúp bạn đọc tài liệu mà không lẫn:

  • Observation API (Micrometer): nơi code nghiệp vụ tạo span, tag, event. Đây là API bạn dùng hằng ngày.
  • Micrometer Tracing: vòng đời span, quan hệ cha–con, lấy trace ID cho log.
  • Bridge: micrometer-tracing-bridge-otel hoặc micrometer-tracing-bridge-brave — chuyển abstraction của Micrometer sang model của backend.
  • Exporter: OTLP (qua Collector) hoặc Zipkin reporter — gửi span ra ngoài tiến trình.

Điểm quan trọng: Sleuth từng gộp bốn lớp và ẩn chúng đi; stack mới tách ra, nên bạn chọn bridge và exporter, nhưng đổi backend không cần sửa code.

Cài đặt trên Spring Boot 4.1.2

Đường ngắn nhất là một dependency: spring-boot-starter-opentelemetry (4.1.2) kéo bridge OTel 1.7.2, exporter OTLP 1.62.0 và registry metric. Nếu chỉ cần trace, dùng micrometer-tracing-bridge-otel + opentelemetry-exporter-otlp; Boot quản lý phiên bản.

Muốn giữ backend Zipkin thì đổi sang spring-boot-starter-zipkin (bridge Brave 6.3.1, reporter 3.5.3). Đừng trộn hai bridge trong một ứng dụng: cả hai cùng giành quyền tạo span, kết quả là span bị nhân đôi hoặc mất cha.

# File: src/main/resources/application.yml
spring:
  application:
    name: order-service

management:
  tracing:
    sampling:
      probability: 1.0          # chỉ dùng ở dev; xem phần sampling
    propagation:
      produce: W3C
    baggage:
      remote-fields: tenant-id
      correlation:
        fields: tenant-id
  opentelemetry:
    tracing:
      export:
        otlp:
          endpoint: http://localhost:4318/v1/traces

spring.application.name trở thành service name trong backend, nên đặt đúng ngay từ đầu. management.tracing.sampling.probability nhận giá trị 0.0–1.0, mặc định 0.1; đặt 1.0 khi dev. management.opentelemetry.tracing.export.otlp.endpoint là URL đầy đủ tới API của Collector, không phải hostname trần.

Với Zipkin, property là management.tracing.export.zipkin.endpoint, mặc định http://localhost:9411/api/v2/spans. Chạy OTel Collector (OTLP HTTP cổng 4318) hoặc Zipkin (9411) bằng Docker. Tracing không có exporter thì chỉ là span nằm trong bộ nhớ rồi biến mất.

Trace ID và span ID trong log

Micrometer Tracing ghi trace ID và span ID vào MDC với hai key traceId và spanId. Nhưng pattern mặc định của Boot 4.1 để trống phần correlation, nên bạn phải đặt logging.pattern.correlation (giá trị kiểu [%X{traceId:-},%X{spanId:-}]) hoặc tự sửa pattern Logback. Thiếu bước này, ID nằm trong MDC mà không in ra, và bạn sẽ tưởng tracing không chạy.

Đây là phần thay thế trực tiếp cho định dạng [app,traceId,spanId,exportable] của Sleuth. Bạn mất cột exportable, nhưng có thể thêm baggage vào log bằng management.tracing.baggage.correlation.fields; chỉ nên đưa field thật sự cần lọc.

Instrument code với Observation API

ObservationRegistry là bean do Boot cấu hình sẵn. Với một việc cần đo riêng — chấm điểm tín dụng, tính giá, gọi đối tác — bọc nó bằng Observation.createNotStarted. Tên observation trở thành tên span và tự nằm dưới span đang active, nên cây cha–con vẫn đúng.

// File: src/main/java/com/example/order/OrderService.java
package com.example.order;

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

@Service
public class OrderService {

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

    private final ObservationRegistry registry;
    private final RestClient inventoryClient;

    OrderService(ObservationRegistry registry, RestClient.Builder builder) {
        this.registry = registry;
        this.inventoryClient = builder.baseUrl("http://inventory-service:8081").build();
    }

    public Order place(OrderRequest request) {
        return Observation.createNotStarted("order.place", registry)
                .lowCardinalityKeyValue("order.channel", request.channel())
                .observe(() -> {
                    log.info("Đặt hàng {}", request.productId());
                    InventoryReply reply = inventoryClient.post()
                            .uri("/inventory/reserve")
                            .body(request)
                            .retrieve()
                            .body(InventoryReply.class);
                    return new Order(request.productId(), reply.reserved());
                });
    }
}

Ba điều đáng chú ý. observe nhận lambda và tự đóng span kể cả khi lambda ném exception, nên không có span treo khi lỗi. lowCardinalityKeyValue dành cho giá trị ít lựa chọn (order.channel, http.method); giá trị gần như duy nhất như mã đơn phải dùng highCardinalityKeyValue, nếu không backend sẽ nổ số lượng tag. Và RestClient.Builder do Boot cấp đã gắn observation registry, nên lời gọi sang inventory tự tạo span con và chèn traceparent; nếu tự gọi RestClient.create(), cả hai việc đó không xảy ra.

Với WebClient, builder do Boot cấu hình cũng instrument và propagate tương tự. Với messaging, Spring Kafka và Spring AMQP có observation convention riêng; điều cần kiểm tra là header tracing có mặt trong message và consumer có đọc lại hay không, vì đó là ranh giới tiến trình thật sự.

@Observed thay cho @NewSpan và @SpanTag

Các annotation của Sleuth — @NewSpan, @ContinueSpan, @SpanTag — không tồn tại trong stack mới. Tương đương gần nhất là @Observed của Micrometer, đặt trên phương thức của bean Spring:

// File: src/main/java/com/example/inventory/InventoryService.java
import io.micrometer.observation.annotation.Observed;

@Observed(name = "inventory.reserve")
public InventoryReply reserve(OrderRequest request) {
    // ...
}

@Observed cần AspectJ trên classpath (spring-boot-starter-aop); Boot đăng ký ObservedAspect để biến annotation thành observation. Giới hạn cần biết: annotation này không có chỗ để gắn tag động như @SpanTag. Khi tag phụ thuộc dữ liệu runtime, dùng Observation.createNotStarted(...).lowCardinalityKeyValue(...) hoặc thêm key–value vào Observation.Context. Đừng cố nhét mọi thứ vào annotation tĩnh.

Mapping từ Sleuth sang stack mới

Sleuth 3.1 2026 Ghi chú
spring-cloud-starter-sleuth spring-boot-starter-opentelemetry hoặc bridge + exporter Không còn artifact Sleuth cho Boot 3+
spring.sleuth.sampler.probability management.tracing.sampling.probability Mặc định mới là 0.1
spring.zipkin.base-url management.tracing.export.zipkin.endpoint Cần spring-boot-starter-zipkin
spring.sleuth.baggage-keys management.tracing.baggage.remote-fields Kèm correlation.fields nếu muốn vào log
@NewSpan, @SpanTag, @ContinueSpan @Observed + Observation API Tag động làm bằng code
X-B3-TraceId, X-B3-SpanId traceparent B3 vẫn được đọc để tương thích
[app,traceId,spanId,exportable] trong log MDC traceId, spanId Không còn cột exportable

Một chỗ không map được: Sleuth tự instrument mọi thứ qua Brave, còn stack mới chỉ instrument những gì Micrometer hoặc OTel biết. Thư viện bên thứ ba không có instrumentation thì phải bọc tay hoặc dùng OTel Java agent.

Sampling trong production

Sampling quyết định span nào được export, không quyết định trace có tồn tại. Ở mức 0.1, cứ mười request thì một được gửi ra backend; chín request còn lại vẫn có trace ID trong log nhưng không có trace để mở. Đừng đặt 0, và cũng đừng quên vì mặc định 0.1: với service ít request bạn sẽ mất gần hết dữ liệu.

Sampler mặc định là parent-based-trace-id-ratio: service gốc quyết định theo tỷ lệ, service sau tuân theo span cha, nên một trace không bị lấy nửa chừng — điều tệ nhất khi debug. Cần giữ 100% trace lỗi nhưng chỉ 5% trace thành công thì giải pháp là tail sampling ở Collector, không phải probability cao toàn hệ thống.

Baggage cũng có chi phí: mỗi field được chép vào mọi span, gửi trên mọi hop và có thể vào mọi dòng log nếu bật correlation. Ba field là hợp lý; mười field khiến header phình và backend từ chối span. Không đặt email, số điện thoại hay token vào baggage — nó đi qua network và nằm trong cả log lẫn trace.

Tên span là chiều cardinality thứ hai. Đặt tên GET /orders/12345 nghĩa là mỗi đơn hàng thành một tên span, backend phải giữ hàng triệu tên và dashboard mất tác dụng. Tên phải là mẫu cố định (GET /orders/{id}, order.place), còn ID cụ thể đưa vào high-cardinality attribute.

Pitfall thường gặp

  • Thêm dependency nhưng không export. Không có exporter hoặc endpoint sai thì span chỉ nằm trong bộ nhớ; kiểm tra bằng một trace thật trong backend, đừng tin log có trace ID.
  • Sampling 0 hoặc quên cấu hình. 0 thì không có gì để xem; để mặc định 0.1 thì 90% request không có trace. Ghi rõ giá trị theo từng profile.
  • Mất context ở async và virtual thread. Thread pool tự tạo, CompletableFuture.supplyAsync hay executor riêng không mang context. Dùng ContextPropagatingTaskDecorator cho TaskExecutor; structured concurrency còn preview nên không tự propagate.
  • Một span cho mỗi câu SQL. Bật instrumentation JDBC ở mức thấp nhất cần thiết; mỗi span là một lần export và một dòng trong cây, N+1 query sẽ biến trace thành danh sách hàng trăm span vô nghĩa.
  • PII trong baggage hoặc tag. Dữ liệu đó đi ra collector và vào log; trace không phải nơi chứa dữ liệu khách hàng.
  • Tên span theo ID. Cardinality nổ, chi phí lưu trữ tăng, biểu đồ theo tên span không còn đọc được.
  • Hai bridge cùng lúc. OTel và Brave cùng đăng ký instrumentation sẽ tạo span trùng hoặc mất quan hệ cha–con; chọn một.

Hướng 2026–2027

OpenTelemetry là chuẩn trao đổi giữa các ngôn ngữ và backend; Spring không còn giữ tracing format riêng. Vai trò của Spring là lớp API — Micrometer Tracing và Observation — còn OTel lo vận chuyển và ngữ nghĩa. Vì vậy code nghiệp vụ nên bám Observation và @Observed, không bám class của OTel SDK, để đổi backend chỉ là đổi dependency và endpoint. Với thư viện không được instrument, OTel Java agent vẫn là lựa chọn, nhưng đừng dùng agent để bù cho cấu hình thiếu.

Checklist trước khi lên production

  • Chọn đúng một bridge, exporter có endpoint thật và đã thấy trace trong backend.
  • Sampling đặt theo profile: 1.0 ở dev, giá trị thấp và có chủ đích ở production.
  • Pattern log có traceId và spanId, đã xác nhận bằng request thật.
  • RestClient/WebClient lấy builder từ Boot, không tạo client trực tiếp.
  • Thread pool và luồng async đã có ContextPropagatingTaskDecorator hoặc tương đương.
  • Không có PII trong baggage; tên span là mẫu cố định, không chứa ID.

Đọc tiếp trong series