配置与可观测性: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。
<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 只放差异项。
# 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.0descriptions: 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 那边一条数据都没有。
第三步,让错误配置在启动期失败。
@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 对象。
第四步,三条自检命令,一条验指标、一条验探针、一条验链路。
# 直方图在不在,_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 不报错,只画一条空白。
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——毕竟本篇的自检命令只能证明端口活着,证明不了行为正确。