Spring Boot 4 集成 OpenTelemetry 实现可观测性（Metrics/Traces/Logs）

并且加入 Grafana + Loki，形成'PLGJ'栈（Prometheus + Loki + Grafana + Jaeger），成为 CNCF 推荐的云原生可观测性黄金组合。

使用 Spring 团队提供的 OpenTelemetry Spring Boot Starter

官方描述和文档：https://spring.io/blog/2025/11/18/opentelemetry-with-spring-boot Spring Boot 4.0 通过官方 spring-boot-starter-opentelemetry 提供了开箱即用、协议优先（OTLP）、与 Micrometer 深度集成的 OpenTelemetry 支持。 开发者只需少量配置，即可实现 Metrics、Traces、Logs 三位一体的可观测性，且能灵活对接任意 OTel 兼容后端。 虽然日志集成仍需手动步骤，但整体体验已非常接近'无缝'。

代码实现

1. Maven 依赖

只需要 spring-boot-starter-opentelemetry 就可以实现 Metrics + Traces + Logs 三合一。

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-opentelemetry</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry.instrumentation</groupId>
        <artifactId>opentelemetry-logback-appender-1.0</artifactId>
        <version>2.21.0-alpha</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
</dependencies>

2. 配置文件

使用 Prometheus + Jaeger otlp 协议来收集数据，可以配置 Loki 用来日志收集。 Prometheus 开启 otlp 协议需要额外配置一个参数。 配置地址：https://prometheus.io/docs/guides/opentelemetry/#enable-the-otlp-receiver

server:
  port: 8090
spring:
  application:
    name: test-service
management:
  otlp:
    metrics:
      export:
        url: http://localhost:9090/api/v1/otlp/v1/metrics #Prometheus otlp 协议 http 地址
        step: 30s
    opentelemetry:
      tracing:
        export:
          otlp:
            endpoint: http://localhost:4317/v1/traces #Jaeger otlp 协议 grpc 地址
            transport: grpc
            # endpoint: http://localhost:4318/v1/traces
            # transport: http
      logging:
        export:
          otlp:
            endpoint: http://localhost:3100/otlp/v1/logs #Loki otlp 协议 http 地址

3. 采集配置

手动配置一个采集的参数。

@Configuration(proxyBeanMethods = false)
public class OpenTelemetryConfiguration {
    @Bean
    public OpenTelemetryServerRequestObservationConvention openTelemetryServerRequestObservationConvention() {
        return new OpenTelemetryServerRequestObservationConvention();
    }

    @Bean
    public OpenTelemetryJvmCpuMeterConventions openTelemetryJvmCpuMeterConventions() {
        return new OpenTelemetryJvmCpuMeterConventions(Tags.empty());
    }

    @Bean
    public ProcessorMetrics processorMetrics() {
        return new ProcessorMetrics(List.of(), new OpenTelemetryJvmCpuMeterConventions(Tags.empty()));
    }

    @Bean
    public JvmMemoryMetrics jvmMemoryMetrics() {
        return new JvmMemoryMetrics(List.of(), new OpenTelemetryJvmMemoryMeterConventions(Tags.empty()));
    }

    @Bean
    public JvmThreadMetrics jvmThreadMetrics() {
        return new JvmThreadMetrics(List.of(), new OpenTelemetryJvmThreadMeterConventions(Tags.empty()));
    }

    @Bean
    public ClassLoaderMetrics classLoaderMetrics() {
        return new ClassLoaderMetrics(new OpenTelemetryJvmClassLoadingMeterConventions());
    }
}

4. 日志配置

1. 创建 src/main/resources/logback-spring.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/base.xml"/>
    <appender name="OTEL" class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender"></appender>
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="OTEL"/>
    </root>
</configuration>

2. 配置 Appender 初始化：

@Component
class InstallOpenTelemetryAppender implements InitializingBean {
    private final OpenTelemetry openTelemetry;

    InstallOpenTelemetryAppender(OpenTelemetry openTelemetry) {
        this.openTelemetry = openTelemetry;
    }

    @Override
    public void afterPropertiesSet() {
        OpenTelemetryAppender.install(this.openTelemetry);
    }
}

3. 配置 TraceId 过滤器：

@Component
class TraceIdFilter implements WebFilter {
    private final Tracer tracer;

    TraceIdFilter(Tracer tracer) {
        this.tracer = tracer;
    }

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        String traceId = getTraceId();
        if (traceId != null) {
            exchange.getRequest().mutate().header("X-Trace-Id", traceId).build();
        }
        return chain.filter(exchange);
    }

    private String getTraceId() {
        TraceContext context = this.tracer.currentTraceContext().context();
        return context != null ? context.traceId() : null;
    }
}

5. 测试接口

@RestController
public class TestController {
    @GetMapping("/test")
    public Mono<String> test() {
        return Mono.just("Hello World!");
    }
}

多运行几次接口查看效果。