Spring Boot 3 WebFlux集成OpenTelemetry TraceID实现日志链路标识

1. 添加依赖 #

在pom.xml（Maven）或build.gradle（Gradle）中引入OpenTelemetry相关依赖：

Maven #

<dependencies>
    <!-- Spring WebFlux Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    <!-- OpenTelemetry Spring Boot Starter -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-spring-boot-starter</artifactId>
        <version>1.32.0</version>
    </dependency>
    <!-- OpenTelemetry Logback Appender（日志集成用） -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-logback-appender-1.0</artifactId>
        <version>1.32.0</version>
    </dependency>
    <!-- 可选：测试用日志导出器，生产环境替换为OTLP -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-logging</artifactId>
        <version>1.32.0</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

Gradle #

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webflux'
    implementation 'io.opentelemetry:opentelemetry-spring-boot-starter:1.32.0'
    implementation 'io.opentelemetry:opentelemetry-logback-appender-1.0:1.32.0'
    runtimeOnly 'io.opentelemetry:opentelemetry-exporter-logging:1.32.0'
}

2. 配置OpenTelemetry #

在application.yml中添加基础配置：

otel:
  service:
    name: your-api-service-name # 替换为你的服务名称
  traces:
    exporter: logging # 测试用，生产建议改为otlp
  instrumentation:
    spring-webflux:
      enabled: true # 开启WebFlux链路追踪支持

3. 修改日志配置（以Logback为例） #

Spring Boot默认使用Logback，修改src/main/resources/logback-spring.xml，在日志格式中加入traceId和spanId：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - traceId:%X{traceId}, spanId:%X{spanId} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

若使用Log4j2，只需在日志pattern中加入%X{traceId}和%X{spanId}即可，原理一致。

4. 验证效果 #

启动服务后调用任意REST接口，控制台日志会输出包含TraceID的内容，示例：

2024-05-20 14:30:00.123 [reactor-http-nio-2] INFO  com.example.demo.controller.DemoController - traceId:abc123def456ghi789jkl0, spanId:mno123pqr456 - 处理请求成功

关键说明 #

• OpenTelemetry的Spring WebFlux instrumentation会自动将TraceID/SpanID同步到Reactor上下文，并映射到MDC（映射诊断上下文）中，因此日志框架可直接通过%X{traceId}获取。
• 生产环境需将otel.traces.exporter改为otlp，并配置OTLP Collector地址，实现链路数据集中收集。

内容的提问来源于stack exchange，提问作者vivi