Spring Boot 4.0 Actuator、Prometheus 与 OpenTelemetry 监控体系

作者：苏三2026-11-07Spring Boot 4.0Spring Boot 4ActuatorPrometheusOpenTelemetry

前言

线上问题不能只靠一条异常日志定位。健康状态、请求量、延迟、错误率和跨服务 Trace 需要放在同一套观测体系里，才能回答“哪台实例不健康、哪个接口变慢、慢在哪个下游”。

本章为订单项目加入 Actuator 健康探针、Micrometer 业务指标、Prometheus 抓取端点和 OpenTelemetry OTLP 导出配置。

读者需要完成前面的 Web、日志和性能章节。完整代码位于 dvsusan/spring-boot4-demo。

最终结果

新增可观测接口和端点：

GET /api/v1/chapter8/observability/orders/{orderNo}
GET /actuator/health
GET /actuator/health/liveness
GET /actuator/health/readiness
GET /actuator/prometheus

指标、追踪和日志

图 1：指标、追踪和日志各自承担不同问题，并通过应用名、Trace ID 和时间关联。

第 1 步：添加监控依赖

Actuator Starter 已在项目中，继续添加：

<!-- Prometheus 端点把 Micrometer 指标转换为标准抓取格式。 -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
<!-- HTTP 请求和自定义 Observation 通过 OTLP 导出到追踪后端。 -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

Micrometer 是应用内指标门面，Prometheus 是抓取协议与存储系统，OpenTelemetry 负责跨服务 Trace 语义与导出。

第 2 步：配置端点和采样

application-chapter8.yml：

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: ${MANAGEMENT_HEALTH_SHOW_DETAILS:always}
      probes:
        enabled: true
  metrics:
    tags:
      application: ${spring.application.name:demo-platform}
  tracing:
    sampling:
      probability: ${OTEL_SAMPLING_PROBABILITY:1.0}
  otlp:
    tracing:
      export:
        enabled: ${OTEL_TRACING_EXPORT_ENABLED:false}
      endpoint: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:http://localhost:4318/v1/traces}

server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 20s

本地默认使用 show-details=always 观察组件状态。生产环境通过 MANAGEMENT_HEALTH_SHOW_DETAILS=never 隐藏内部详情，或由认证网关保护管理端点。

第 3 步：增加业务指标和 Observation

Chapter8MonitoringService 创建 Counter、Timer 和业务 Observation：

this.orderQueries = Counter.builder("chapter8.orders")
        .description("订单可观测性示例查询次数")
        .tag("status", "SUCCESS")
        .register(meterRegistry);
this.queryLatency = Timer.builder("chapter8.direct.lookup")
        .description("订单查询示例耗时")
        .publishPercentileHistogram()
        .register(meterRegistry);

return Observation.createNotStarted(
                "chapter8.order.lookup",
                observationRegistry
        )
        .lowCardinalityKeyValue("order.type", "demo")
        .observe(() -> {
            long startedAt = System.nanoTime();
            sleep(Duration.ofMillis(15));
            orderQueries.increment();
            queryLatency.record(
                    System.nanoTime() - startedAt,
                    TimeUnit.NANOSECONDS
            );
            return new OrderObservation(orderNo, "OBSERVED",
                    "chapter8.order.lookup");
        });

标签只能使用低基数维度。订单号、用户 ID 和完整 URL 放进标签会造成 Prometheus 时间序列爆炸，应放在日志或 Trace 属性中。

第 4 步：启动应用并调用接口

mvn clean package -DskipTests

java -jar demo-web/target/demo-web-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=chapter8 \
  --server.port=18108

curl -sS \
  http://localhost:18108/api/v1/chapter8/observability/orders/SO1001

预期 status=OBSERVED。随后检查：

curl -sS http://localhost:18108/actuator/health
curl -sS http://localhost:18108/actuator/health/liveness
curl -sS http://localhost:18108/actuator/health/readiness
curl -sS http://localhost:18108/actuator/prometheus | \
  grep chapter8_orders_total

真实测试结果为健康总状态、liveness 和 readiness 都返回 200，Prometheus 响应包含 chapter8_orders_total 与 chapter8_direct_lookup_seconds。

第 5 步：接入 OTLP Collector

启动 Collector 后设置：

OTEL_TRACING_EXPORT_ENABLED=true \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces \
OTEL_SAMPLING_PROBABILITY=0.2 \
java -jar demo-web/target/demo-web-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=chapter8

采样率是进入追踪后端请求的比例。故障排查可临时提高，长期高流量系统要结合成本和实际告警需求设置。

第 6 步：运行自动化测试

mvn -pl demo-web -am \
  -Dtest=Chapter8ObservabilityIntegrationTest \
  -Dsurefire.failIfNoSpecifiedTests=false \
  test

测试主动关闭未启动的 Redis 和 Elasticsearch 健康检查，验证应用自身健康状态、两个 Kubernetes 探针和 Prometheus 指标。

三种信号如何协同

告警发现订单接口 P95 升高。
指标把范围缩小到某个实例或下游。
Trace 展示慢调用的具体 Span。
使用 Trace ID 在日志平台找到业务上下文。

缺少任意一环，定位成本都会明显上升。

常见问题排查

现象	原因	处理方式
没有 `/prometheus`	缺少 Registry 或未暴露端点	检查依赖和 exposure include
健康检查始终 DOWN	Redis/ES 等外部依赖未启动	启动依赖或按环境关闭对应 Indicator
Prometheus 时间序列过多	标签使用高基数值	移除订单号、用户 ID 等标签
没有 Trace	采样率为 0 或 Collector 未启用	检查采样与 OTLP 配置
Pod 启动就被杀死	liveness 初始延迟过短	延长 initialDelay 并区分 readiness

练习题

为支付接口增加成功、失败两个 Counter，并为“查询订单” Observation 添加数据库 Span。验收标准是 Prometheus 能看到两种状态，Trace 中能看到 HTTP 与数据库父子 Span。

总结

Actuator 提供运行状态入口，Micrometer 定义应用指标，Prometheus 保存时间序列，OpenTelemetry 连接跨服务 Trace，日志继续提供最丰富的业务上下文。

下一篇把应用打包为安全、可探活的容器，并部署到 Kubernetes。

上一节：Testcontainers 集成测试
 下一节：Docker 与 Kubernetes 部署
 相关阅读：MDC 日志链路
 返回课程目录

13 个企业级实战项目 · 源码 + 教程 + 答疑

简历包装指导AI Agent 实战高并发·微服务Offer 导向持续更新3000+ 同行交流1V1 答疑3 天包退

覆盖高并发、微服务、分布式与 AI Agent：100万QPS短链、企业智能知识库、商城微服务、SaaS点餐、秒杀、刷题小程序、代码生成器、AI Agent 等。券后 ¥129（原价 ¥159），不满意 3 天包退。

立即获取 13 个项目源码 →