Skip to content

配置与可观测性:Profiles、Actuator 与 Micrometer ​

本篇要点:让一个 Spring Boot 4 服务在出事时能回答「哪个接口、多慢、哪一步、哪个租户」,而不是只有一张整体 QPS 图。前置文章:《并发与异步:虚拟线程、@Async 与任务调度》讲了虚拟线程与上下文传递,本篇的 traceId 丢失问题正好接在那里。

为什么需要它 ​

凌晨两点,订单服务 P99 从 180ms 涨到 4 秒。值班的人打开三块屏幕:Grafana 上只有整体 QPS 和错误率,没有按接口拆开的延迟;日志系统里搜不到出事那条请求的 traceId;Prometheus 的抓取间隔是 15 秒,出事那一分钟的数据刚好缺失。

四十分钟后定位到原因:一个下游接口在特定租户下超时。数据其实一直都在,缺的是三块屏幕之间的联系。

装过 spring-boot-starter-actuator 不等于可观测。Actuator 只做一件事——把进程内部状态通过 HTTP 暴露出来,它不解决另外三件事:多环境配置怎么分开且优先级可预测、哪些端点能暴露给谁、指标与链路怎么用同一个埋点产出。这三件事分别落在本篇的 Profile、端点安全、Micrometer Observation 上。

核心概念 ​

配置档(Profile)与配置优先级 ​

Profile 是给一组配置起的名字。启动时选中 spring.profiles.active=prod,Spring 就去找文件名匹配的 application-prod.yml,其余文件不动。

优先级从高到低是:命令行参数 > 操作系统环境变量 > application-{profile}.yml > application.yml。同一条属性出现在多处时,靠前的覆盖靠后的。

一个 profile 还可以是一组:spring.profiles.group.prod=prod-db,prod-cache 让 --spring.profiles.active=prod 一次激活三个文件,避免启动命令越拉越长。反过来,spring.profiles.include 只能追加、不能取消,用它「关掉」某个配置注定失败。

反例:以为 profile 文件之间互相隔离。不是。application.yml 每次都会加载,profile 文件只是在它之上叠加,所以写进默认文件的数据库密码,任何 profile 都带着走。生产事故里「测试环境连了生产库」,多半就出在这一层。

配置属性绑定(@ConfigurationProperties)与校验 ​

把这组前缀相同的配置绑定到一个类型安全的 Java 对象,就是这个注解的职责。再配 @Validated 和 Jakarta Bean Validation 约束,绑定发生在启动期——写错的配置会让进程起不来,而不是拖到第一次调用才炸。

反例:以为在字段上写了 @Min 就会生效。缺 @Validated 时约束被完全忽略,值越界也照绑不误。

观测(Observation):一次埋点,三个出口 ​

Micrometer Observation 是 Spring Boot 4 统一埋点的抽象。一次 Observation 走完,指标由 MeterRegistry 导出,span 由 Tracer 导出,traceId 写进 MDC(Mapped Diagnostic Context,日志框架的线程上下文),日志组件从那里取值。整体形状如图 8-1 所示。

图 8-1 一次埋点的三个出口,以及一拉一推两条传输方向

图 8-1 里两条箭头方向不一样:指标由 Prometheus 周期性拉取(pull),追踪由应用主动推送(push)。这决定了故障时的数据形态——抓取间隔内进程挂掉,那一段指标直接没有;推送失败则进本地缓冲,重启后再一起打上去。

反例:以为三件套是三套独立 SDK,于是只加 Prometheus 依赖就期待有链路。Spring Boot 不会自动导出 OpenTelemetry 的指标和日志,只有和 Micrometer Tracing 一起用时,OTLP 追踪导出才是自动配置的。

指标基数(Cardinality) ​

基数是一个指标下不同标签组合的数量,数值上等于时间序列条数。每多一个组合,就多一条常驻堆内存的序列。

反例:把 userId、orderId、原始 URL 放进标签。一轮压测能把序列数从几百推到四万多,表现是 Full GC 次数上去了、接口耗时看起来没变——因为慢在 GC,不在业务。判断标准很朴素:一个标签的取值空间超过几十个,它只该进 trace,不该进指标。

健康检查与探针(Probe) ​

Actuator 把健康检查拆成两个语义不同的探针,在 Kubernetes 环境下自动启用:liveness 表示进程还活着,失败应重启;readiness 表示能接流量,失败应摘流。

反例:以为「一个 /actuator/health 够用了」。把 readiness 绑到数据库连通性,下游抖动一下,全部副本被同时摘流,故障被放大成整体不可用。

还有一层容易被忽略:探针的判定精度取决于 kubelet 的探测周期(periodSeconds),不是应用多快就绪就算多快。这一笔启动预算在《进阶:GraalVM Native Image 与 AOT 优化》讲 Native Image 时会重新算一次。

概念你手上的开关弄错的后果
配置档spring.profiles.active默认文件里的配置被带进生产
属性绑定@ConfigurationProperties + @Validated错误配置延迟到运行期才暴露
观测ObservationRegistry只有指标没有链路,或反过来
基数标签的取值空间序列爆炸,堆与 Prometheus 内存一起涨
探针management.endpoint.health.probes下游抖动被放大成全量不可用

动手实践 ​

准备一个 Boot 4.1.x 的 Web 项目,下面四步按顺序做。截至 2026 年 11 月,版本全部由 BOM 管理,不手写 version。

第一步,三份依赖。第三个 spring-boot-starter-opentelemetry 是 Boot 4 的官方 starter。

xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-opentelemetry</artifactId>
</dependency>

预期输出(mvn dependency:tree 过滤 micrometer,版本号由 BOM 决定):

[INFO] +- org.springframework.boot:spring-boot-starter-actuator:jar
[INFO] +- io.micrometer:micrometer-registry-prometheus:jar:runtime
[INFO] +- org.springframework.boot:spring-boot-starter-opentelemetry:jar

这一步有个副作用要提前掐掉:别和 OpenTelemetry 的 Java Agent 同时用。两者叠加会重复埋点,甚至出现两套 traceId。排查时先看启动命令里那行 -javaagent 是否还留着。

第二步,配置。默认文件放公共项,application-prod.yml 只放差异项。

yaml
# application.yml —— 每个 profile 都会加载
spring:
  application:
    name: order-api

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus   # 只开这三个,别用 "*"
  endpoint:
    health:
      probes:
        enabled: true
      show-details: when-authorized
    prometheus:
      access: read-only                    # Boot 4 的三级 access,替代旧的 enabled
  observations:
    key-values:
      deployment.environment: ${spring.profiles.active:default}
  metrics:
    distribution:
      percentiles-histogram:
        http.server.requests: true         # 没有直方图算不出 P99
  prometheus:
    metrics:
      export:
        descriptions: false                # 不输出 HELP/TYPE,抓取体积小两三成
  tracing:
    sampling:
      probability: 0.1
  opentelemetry:
    resource-attributes:
      service.name: order-api
    tracing:
      export:
        otlp:
          endpoint: http://otel-collector:4318/v1/traces

预期输出(--spring.profiles.active=prod 启动,然后抓一次指标):

The following 1 profile is active: "prod"
# 抓取结果里没有 # HELP / # TYPE 注释行,只有样本行
http_server_requests_seconds_bucket{uri="/api/orders",le="0.1",} 812.0

descriptions: false 这一行值得单独说:它砍掉的只是 HELP 与 TYPE 注释,对 Grafana 里的查询没有影响,而一个大服务的抓取体积能小两三成,Prometheus 的内存跟着降。

include 里放哪几个端点也要挑。env 会吐出全部配置项和部分环境变量,heapdump 能导出一份完整堆快照,里面可能有明文凭据,threaddump 在虚拟线程场景下一次会打出成千上万个栈。真要开到这类端点,就用独立的 management.server.port 只在内网可达,再按端点粒度用 management.endpoint.<id>.access 收窄。

OTLP(OpenTelemetry Protocol)端点要写全路径。只有走环境变量 OTEL_EXPORTER_OTLP_ENDPOINT 时 Boot 才自动补 /v1/traces;直接配 management.opentelemetry.tracing.export.otlp.endpoint 时少写这一段,表现是启动不报错、日志不报错、collector 那边一条数据都没有。

第三步,让错误配置在启动期失败。

java
@ConfigurationProperties(prefix = "app.obs")
@Validated
public record ObsProperties(
        @NotBlank String serviceName,
        @DecimalMin("0.0") @DecimalMax("1.0") double samplingProbability,
        @NotNull URI otlpEndpoint) {
}

预期输出(app.obs.sampling-probability 误写成 1.5,启动直接失败):

APPLICATION FAILED TO START
Property: app.obs.sampling-probability
Value: "1.5"
Reason: must be less than or equal to 1.0

记得用 @ConfigurationPropertiesScan 或 @EnableConfigurationProperties 注册这个类,否则它只是个没人读的普通 Java 对象。

第四步,三条自检命令,一条验指标、一条验探针、一条验链路。

bash
# 直方图在不在,_bucket 后缀是关键
curl -s localhost:8080/actuator/prometheus | grep -c http_server_requests_seconds_bucket

# readiness 探针
curl -s localhost:8080/actuator/health/readiness

# 本地起个 collector,看有没有 v1/traces 打进来
docker run --rm -p 4318:4318 otel/opentelemetry-collector:latest

预期输出:

24
{"status":"UP"}
# collector 日志里出现 TracesExporter,spans 计数持续增长

第一条返回 0 说明直方图没开。此时 histogram_quantile 算出来的 P99 全是 NaN,而 Grafana 不报错,只画一条空白。

promql
histogram_quantile(0.99,
  sum by (le, uri) (rate(http_server_requests_seconds_bucket[5m])))

预期输出:按 uri 分组的一条 P99 曲线;依赖 _bucket,缺了它就是 NaN。

常见误解 ​

很多人以为日志里没有 traceId 是埋点失效,其实是上下文没传过去。 四个真实原因:一是线程切换,observation 上下文在 ThreadLocal 里,@Async 用自动配置的执行器要开 spring.task.execution.propagate-context=true,自己 new 的执行器必须注册 ContextPropagatingTaskDecorator,Reactor 链路另配 spring.reactor.context-propagation=auto;二是 HTTP 客户端没走自动配置,必须用 RestClient.Builder、RestTemplateBuilder 或 WebClient.Builder 构造,自己 new RestTemplate() 不带 traceparent,链路到下游就断,而且断得很安静;三是 @SpringBootTest 下上报组件本来就不自动配置,这是刻意设计;四是自定义线程池里手动 MDC.put 之后忘了 remove,上一个请求的 traceId 被下一个用掉,这种串号只在压测时暴露。

很多人以为降低采样率会让指标失真,其实指标是全量的。 采样只影响 trace。默认概率 0.1,调低它的代价在个案排查:出问题时那一条恰好没被采到,你只能从指标知道「哪个接口慢」,定位不到「哪一步慢」。正确做法是低采样率加尾部兜底,错误请求强制采。还有个连带细节:exemplar 是从图点进链路的桥梁,但 Prometheus 用普通文本格式抓取时会把它静默丢掉,抓取端得按 OpenMetrics 格式接收才看得见。

很多人以为在 Controller 上加 @Observed 会更全,其实指标会翻倍。 MVC 的 http.server.requests 已经自动埋过了,叠加之后 P99 直接失真,注解本身还要 management.observations.annotations.enabled=true 加 AOP starter 才生效,两样加完常被忘掉。需要补埋点时优先用 Observation API,并且把 tag 按基数分开:几十个取值以内的进指标,超出的只进 trace。

小结 ​

  • 配置按优先级叠:命令行 > 环境变量 > profile 文件 > 默认文件;默认文件永远加载,别往里放生产凭据。
  • @ConfigurationProperties 配 @Validated,把配置错误提前到启动期;漏掉注解则约束静默失效。
  • 三件套不是三个系统,是一条流水线的三个出口:一次 Observation 出指标、span、MDC 里的 traceId;指标被拉、追踪被推。
  • /actuator/** 不要裸奔到公网,prometheus 端点会暴露全部指标名与标签;用网关鉴权或只在内网端口开放。
  • 看板只留四类:流量与错误率、延迟分位、依赖健康度、业务关键指标。延迟用分位不用平均——P99 八秒的接口,平均值可能只有两百毫秒。链路到日志的跳转靠 Grafana 的 derived field,把 traceId 配成指向 Tracing 数据源的跳转字段,这一步比多埋十个自定义指标更能压缩排障时间。

回看《并发与异步:虚拟线程、@Async 与任务调度》:虚拟线程把并发模型换了,但上下文传递的规则没变。本篇那四个 traceId 陷阱里,线程切换与 MDC 未清理这两个就出在线程边界上。

相关主题 ​

相关文章把这些配置与埋点放进测试里验证:《测试体系:单元测试、切片测试与 Testcontainers》讲测试金字塔在 Spring 项目怎么落地、@WebMvcTest 与 @DataJpaTest 切片,以及用 Testcontainers 跑真实 MySQL——毕竟本篇的自检命令只能证明端口活着,证明不了行为正确。