Spring Boot 如何启用分布式跟踪并让日志输出关联的 Correlation ID？

Spring Boot 如何启用分布式跟踪并让日志输出关联的 Correlation ID？

【免费下载链接】spring-bootSpring Boot helps you to create Spring-powered, production-grade applications and services with absolute minimum fuss.项目地址: https://gitcode.com/gh_mirrors/sp/spring-boot

如果你的 Spring Boot 应用需要把 HTTP 请求上报为分布式追踪（trace），并希望每行日志都带有可以和追踪关联的 Correlation ID，本文给出官方文档中的完整操作路径：添加追踪 starter 依赖、配置采样率、启动追踪后端、在 Zipkin UI 中确认 trace，以及理解/定制 Correlation ID 的日志格式。主路径使用 OpenZipkin Brave + Zipkin 组合，这是 Spring Boot 文档示例采用的组合；OpenTelemetry + OTLP 组合作为可选分支简要说明。

先准备一个带日志输出的示例应用

追踪效果依赖日志中的 Correlation ID，所以示例应用要在处理请求时打一条日志。文档中的示例代码如下（源文件见 MyApplication.java）：

import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @SpringBootApplication public class MyApplication { private static final Log logger = LogFactory.getLog(MyApplication.class); @RequestMapping("/") String home() { logger.info("home() has been called"); return "Hello World!"; } public static void main(String[] args) { SpringApplication.run(MyApplication.class, args); } }

关键点：home()方法里的logger.info(...)语句就是后面用来观察 Correlation ID 的日志来源，不要省略。

添加追踪依赖并配置采样

Spring Boot Actuator 为 Micrometer Tracing 提供了依赖管理和自动配置，并内置以下 tracer 的自动配置：

• OpenTelemetry（通过 OTLP 上报），starter 为org.springframework.boot:spring-boot-starter-opentelemetry；
• OpenZipkin Brave（上报到 Zipkin），starter 为org.springframework.boot:spring-boot-starter-zipkin。

主路径选用 Brave + Zipkin，在构建文件中添加：

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

然后添加以下application.yml配置：

management: tracing: sampling: probability: 1.0

原因：Spring Boot 默认只采样 10% 的请求，以避免压垮追踪后端。把management.tracing.sampling.probability设为1.0后，每个请求都会发送到追踪后端。如果你只需要部分请求上报，可以调低这个值，但要留意被采样丢弃的请求不会出现在后端里。

可选分支：如果选用 OpenTelemetry，则改用org.springframework.boot:spring-boot-starter-opentelemetry依赖，用management.opentelemetry.tracing.export.otlp.*系列属性配置 OTLP 上报，并可以通过management.opentelemetry.tracing.sampler选择采样器（默认值为parent-based-trace-id-ratio，即按management.tracing.sampling.probability的比例采样）。

启动追踪后端并验证 trace

Correlation ID 之外，要看到完整的 trace 还需要一个运行中的追踪后端。文档以 Zipkin 为例：按 Zipkin Quickstart guide 的说明在本地启动一个 Zipkin 实例（文档中 UI 地址为http://localhost:9411）。

Zipkin 启动后再启动你的应用，然后做两步验证：

1. 用浏览器打开http://localhost:8080，看到输出Hello World!（文档示例输出）。这一步同时触发了一次 HTTP 请求的 observation，它会被桥接到 Brave 并上报一条新 trace 到 Zipkin。
2. 打开 Zipkin UIhttp://localhost:9411，点击 "Run Query" 列出所有已收集的 trace，应该能看到一条 trace；点击 "Show" 可以查看这条 trace 的细节（见 tracing.adoc 的 Getting Started 一节）。

让日志输出关联的 Correlation ID

启用 Micrometer Tracing 后，Spring Boot 默认就会把 Correlation ID 写进日志，把日志行与 span/trace 关联起来，这一步不需要额外代码。

默认格式的构成：

• 默认 Correlation ID 由traceId和spanId两个 MDC 值组成，形如[traceId-spanId]。例如文档中的示例：MDCtraceId为803B448A0489F84084905D3093480352、spanId为3425F23BB2432450时，日志输出会包含 Correlation ID[803B448A0489F84084905D3093480352-3425F23BB2432450]（这是文档给出的示例值，实际运行中 ID 会不同）。
• 默认的 Correlation ID 格式会跟随 MDC 键名，并自动把键名填充到 32 和 16 个字符，因此无需额外配置就能继续工作。

两个需要注意的边界：

• Brave 的 baggage 影响 MDC 键名：使用 Brave 时，MDC 键名只在 baggage 开启时生效。把management.tracing.baggage.enabled设为false会阻止 Brave 把 trace/span ID 写入 MDC，从而直接禁用日志关联。如果你依赖日志里的 Correlation ID，不要关闭 baggage。
• 自定义 MDC 键名：可以用management.tracing.mdc.trace-id-key和management.tracing.mdc.span-id-key两个属性自定义traceId/spanId的 MDC 键名，默认 Correlation ID 格式会自动跟随新键名。

如果你想要别的格式（例如 Spring Cloud Sleuth 曾经使用的格式），用logging.pattern.correlation属性自定义。注意：自己设置的值会优先于从 MDC 键名推导的格式，所以它必须自行引用你自定义过的键名。文档给出的 Logback 示例：

logging: pattern: correlation: "[${spring.application.name:},%X{traceId:-},%X{spanId:-}] " include-application-name: false

两点说明：logging.pattern.correlation值末尾的空格用于把它和紧随其后的 logger 名称隔开；logging.include-application-name设为false是为了避免应用名在日志里重复出现（因为上面的 correlation 格式里已经包含了${spring.application.name}）。

Correlation ID 依赖上下文传播（context propagation）。如果你的应用跨线程或使用响应式管线，见 observability.adoc 的 Context Propagation 一节：默认情况下ThreadLocal值不会自动在响应式算子间恢复，可以通过spring.reactor.context-propagation设为auto启用自动传播；使用自动配置的AsyncTaskExecutor处理@Async方法时，需要用spring.task.execution.propagate-context显式开启上下文传播。

跨服务调用时传播 trace

要让 trace 在网络上自动传播（即下游服务收到请求时延续同一个 trace），客户端必须用自动配置的构造器创建：

• 注入自动配置的RestClient.Builder来构造RestClient；
• 注入自动配置的WebClient.Builder来构造WebClient。

文档明确警告：如果不用自动配置的 builder 而直接创建RestClient或WebClient，自动的 trace 传播不会生效。

限制与测试场景说明

• 采样：默认 10% 采样率，验证阶段建议先设为1.0，确认行为后再按需调低。
• 使用@SpringBootTest时，会上报数据的追踪组件不会被自动配置，测试中的追踪行为与生产运行不同（见 testing/spring-boot-applications.adoc 的 Tracing 一节）。
• OpenTelemetry 组合下还可以用management.opentelemetry.tracing.limits.*控制每个 span 的属性数、事件数、链接数上限及字符串属性值最大长度。

以上配置完成后，日志行里的[traceId-spanId]段就是 Correlation ID，拿它去 Zipkin UI 的 trace 详情中即可对应到具体的 span。更多细节（Baggage、自定义 span 等）见 tracing.adoc。

【免费下载链接】spring-bootSpring Boot helps you to create Spring-powered, production-grade applications and services with absolute minimum fuss.项目地址: https://gitcode.com/gh_mirrors/sp/spring-boot