Micrometer 系列【33】Spring Boot Micrometer Metrics 自动配置模块解析

文章目录

[1. 概述](#1. 概述)
[2. 包结构与模块划分](#2. 包结构与模块划分)
- [2.1 整体分层](#2.1 整体分层)
- [2.2 根包：全局Filter + 故障诊断](#2.2 根包：全局Filter + 故障诊断)
- [2.3 actuate/endpoint 指标端点](#2.3 actuate/endpoint 指标端点)
- [2.3 autoconfigure 核心自动配置包](#2.3 autoconfigure 核心自动配置包)
- - [2.3.1 核心自动配置类](#2.3.1 核心自动配置类)
  - [2.3.2 autoconfigure/export 导出到监控系统](#2.3.2 autoconfigure/export 导出到监控系统)
  - [2.3.3 内置指标 Binder 模块](#2.3.3 内置指标 Binder 模块)
- [2.4 OTLP 开发测试辅助](#2.4 OTLP 开发测试辅助)
- [2.5 prometheus 独立导出端点](#2.5 prometheus 独立导出端点)
- [2.6 顶层独立组件](#2.6 顶层独立组件)
[3. 核心类](#3. 核心类)
- [3.1 MetricsAutoConfiguration：主配置入口](#3.1 MetricsAutoConfiguration：主配置入口)
- [3.2 MetricsProperties：外部化配置模型](#3.2 MetricsProperties：外部化配置模型)
- [3.3 SimpleMetricsExportAutoConfiguration：简易注册表](#3.3 SimpleMetricsExportAutoConfiguration：简易注册表)
- [3.4 导出后端统一模式](#3.4 导出后端统一模式)
- [3.5 MeterRegistryPostProcessor：度量体系组装中枢](#3.5 MeterRegistryPostProcessor：度量体系组装中枢)
- [3.6 JvmMetricsAutoConfiguration：JVM 指标](#3.6 JvmMetricsAutoConfiguration：JVM 指标)
- [3.7 SystemMetricsAutoConfiguration：系统指标](#3.7 SystemMetricsAutoConfiguration：系统指标)
- [3.8 其他指标自动配置](#3.8 其他指标自动配置)
[4. AOT 编译支持](#4. AOT 编译支持)
[5. 导出后端总览](#5. 导出后端总览)
[6. 总结](#6. 总结)

1. 概述

spring-boot-micrometer-metrics 是 Spring Boot 4.1.0 中负责 Micrometer 指标（Metrics）自动配置的模块。它在 Spring Boot 4.0 时随模块化拆分首次引入，将原先分散在 spring-boot-actuator-autoconfigure 中的 Micrometer 相关代码独立为一级模块。

Maven 坐标：org.springframework.boot:spring-boot-micrometer-metrics:4.1.0

Actuator 负责暴露端点，本模块负责 Meter 体系的初始化、导出、JVM/系统/日志指标绑定。

2. 包结构与模块划分

2.1 整体分层

整体结构：

分层	目录	核心职责
通用工具 & Filter	根包	MeterFilter、异常诊断分析器，全局指标拦截校验
Actuator 端点	`actuate/endpoint/`	对外暴露 HTTP 指标接口 `/actuator/metrics`
自动配置核心	`autoconfigure/`	★整个模块的心脏，自动装配所有 MeterRegistry、Binder、Customizer、切面、导出
导出适配器	`autoconfigure/export/`	20+监控后端适配（Prometheus、OTLP、Datadog...）
内置指标采集器	`autoconfigure/jvm/ system/ logging/ ssl/ task/ startup/`	JVM、系统、日志、线程池、SSL、启动耗时内置指标
扩展端点/推送管理	`export/prometheus/`	Prometheus 专属：抓取端点、PushGateway管理器
测试开发辅助	`docker/compose/otlp` `testcontainers/otlp`	开发测试环境自动对接 OTLP Collector
独立监听器	根下 startup / system	启动时间监听、磁盘指标Binder

2.2 根包：全局Filter + 故障诊断

MaximumAllowableTagsMeterFilter
- 属于 MeterFilter 实现，拦截 Meter 注册；限制单个指标 Tag 最大数量，防止 Tag 爆炸（高基数维度）引发内存暴涨。
- 由 management.metrics.maximum-allowable-tags 属性控制。
ValidationFailureAnalyzer
- Spring Boot FailureAnalyzer，捕获 Micrometer 指标注册校验异常，输出可读提示，而不是堆栈乱码；比如 tag key 非法、tag 过多等问题。

2.3 actuate/endpoint 指标端点

Actuator 的 @Endpoint，提供 /actuator/metrics、/actuator/metrics/{name}。
从 MeterRegistry 查询已注册指标，做格式化输出，不负责采集、不负责导出，只做查询对外暴露。
由 MetricsEndpointAutoConfiguration 装配 Bean。

2.3 autoconfigure 核心自动配置包

绝大部分开发者的配置、Bean 都在这里完成。

2.3.1 核心自动配置类

类名	关键说明
MetricsAutoConfiguration	根配置；创建`CompositeMeterRegistry`、Clock、ObservationRegistry；加载全局MeterFilter
MetricsProperties	绑定 `management.metrics.*` yml/properties全部配置项
MetricsEndpointAutoConfiguration	条件装配，开启actuator metrics端点才创建`MetricsEndpoint`
MetricsAspectsAutoConfiguration	AOP切面，支持注解 `@Timed`、`@Counted` 自动对方法埋点
CompositeMeterRegistryAutoConfiguration	组装组合注册表：把各个导出后端的MeterRegistry加到Composite，一份指标多输出
MeterRegistryPostProcessor	`BeanPostProcessor`；收集所有`MeterFilter`、`MeterBinder`、`MeterRegistryCustomizer`，回调应用到MeterRegistry
MeterRegistryCustomizer	SPI接口，业务可实现，对MeterRegistry做自定义修改
PropertiesMeterFilter	将配置文件里`management.metrics.tags`、filter配置转成Micrometer `MeterFilter`
MeterValue / ServiceLevelObjectiveBoundary	配置SLO阈值DSL，解析duration/number阈值，用于SLO分桶
NoOpMeterRegistryConfiguration	关闭metrics时，注入空实现，避免代码报错

2.3.2 autoconfigure/export 导出到监控系统

ConditionalOnEnabledMetricsExport：组合条件注解，判断该导出器是否开启。
PropertiesConfigAdapter：模板模式，把 SpringBoot 配置类映射为 Micrometer 原生RegistryConfig。
StepRegistryProperties：拉模式后端公共配置 （Prometheus 属于StepRegistry，按 step 周期聚合指标）。
PushRegistryProperties：推模式后端公共配置 （Datadog、OTLP、Influx 等主动上报）。
每个子目录对应一个监控系统的自动配置；引入对应依赖 + 开启配置，就会实例化对应 MeterRegistry，注册到 Composite。

区分：

StepRegistry：服务端来拉取指标，本地按时间窗口聚合；Prometheus 属于此类。

PushRegistry：应用主动把指标推送到远端网关/服务。

2.3.3 内置指标 Binder 模块

全部为 MeterBinder 实现，Spring Boot 自动装配，应用启动完成后向 MeterRegistry 注册内置监控指标。

jvm：堆、非堆、GC 暂停、线程数、类加载、虚拟线程；
system：操作系统 CPU、fd 句柄；磁盘空间 Binder 在包根下；
logging：日志事件计数（error/warn/info日志条数）；
ssl：SSL证书有效期、握手统计；
task：线程池队列、活跃线程、拒绝任务；
startup：基于 ApplicationStartup 事件，采集各个阶段启动耗时。

2.4 OTLP 开发测试辅助

仅开发/集成测试使用，生产不会加载：

docker compose：检测 compose 环境，自动注入 OTLP Collector 地址；
testcontainers：单元集成测试，拉起 OTLP Collector 容器，自动配置导出地址。

2.5 prometheus 独立导出端点

export/prometheus/endpoint：Actuator 原生端点，输出原始 Prometheus 文本格式 /actuator/prometheus。
PrometheusPushGatewayManager：定时把指标推送到 PushGateway。

2.6 顶层独立组件

StartupTimeMetricsListener：监听 Spring 启动事件，生成启动时间指标；和 autoconfigure/startup 配合。

DiskSpaceMetricsBinder：采集磁盘分区可用、总空间指标。

3. 核心类

3.1 MetricsAutoConfiguration：主配置入口

java 复制代码

@AutoConfiguration(before = CompositeMeterRegistryAutoConfiguration.class)
@ConditionalOnClass(Timed.class)
@EnableConfigurationProperties(MetricsProperties.class)
public final class MetricsAutoConfiguration {
    // ...
}

职责：初始化度量体系的基础设施。

关键设计决策：

Bean 都是静态内部类 的无副作用的工厂方法，便于 AOT 编译
MeterRegistryPostProcessor 是 static Bean，在常规 Bean 初始化之前运行
通过 ObservationHandlerGroup 将所有 MeterObservationHandler 分组，支持 Observation 体系

自动注册的组件 Bean ：

Bean	类型	说明
`micrometerClock`	`Clock`	默认 `Clock.SYSTEM`（自动配置未覆盖时）
`meterRegistryPostProcessor`	`MeterRegistryPostProcessor`	核心后处理器：收集所有 `MeterFilter` / `MeterBinder` / `MeterRegistryCustomizer`，注入到每个 `MeterRegistry`
`propertiesMeterFilter`	`PropertiesMeterFilter`	从 `management.metrics.enable` / `tags` 等属性生成 `MeterFilter`，权重最低（`@Order(0)`）
`meterRegistryCloser`	`MeterRegistryCloser`	监听 `ContextClosedEvent`，确保 MeterRegistry 优雅关闭
`metricsObservationHandlerGroup`	`ObservationHandlerGroup`	注册 Micrometer 为 Observation Handler
`defaultMeterObservationHandler`	`DefaultMeterObservationHandler`	将 Observation API 的度量桥接到 MeterRegistry

3.2 MetricsProperties：外部化配置模型

前缀：management.metrics

java 复制代码

@ConfigurationProperties("management.metrics")
public class MetricsProperties {
    boolean useGlobalRegistry = true;           // 是否绑定全球注册表
    Map<String, Boolean> enable = ...;          // 按名称启用/禁用指标
    Map<String, String> tags = ...;             // 公共标签
    Web web;                                    // web.client.maxUriTags / web.server.maxUriTags
    System system;                              // system.diskspace.*
    Distribution distribution;                  // 分布统计（百分位、SLA、最小期望值等）
    Observations observations;                  // observation.ignoredMeters
}

配置示例：

yaml 复制代码

management:
  metrics:
    use-global-registry: false
    enable:
      jvm: true
      logback: false
    tags:
      region: cn-shanghai
      app: ${spring.application.name}
    web:
      server:
        max-uri-tags: 200
    distribution:
      slo:
        http.server.requests: 10ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s
      percentiles:
        http.server.requests: 0.5, 0.75, 0.95, 0.99

3.3 SimpleMetricsExportAutoConfiguration：简易注册表

默认启用的 内存 MeterRegistry（当没有其他注册表时）
配置前缀：management.simple.metrics.export.*
SimplePropertiesConfigAdapter 将 Spring 属性桥接到 Micrometer 的 SimpleConfig
适合开发环境；生产环境通常替换为 Prometheus/OTLP 等

java 复制代码

@Bean
SimpleMeterRegistry simpleMeterRegistry(SimpleConfig config, Clock clock) {
    return new SimpleMeterRegistry(config, clock);
}

@Bean
@ConditionalOnMissingBean
SimpleConfig simpleConfig(SimpleProperties simpleProperties) {
    return new SimplePropertiesConfigAdapter(simpleProperties);
}

3.4 导出后端统一模式

每个后端都遵循相同的三件套模式：

复制代码

export/<backend>/
├── <Backend>MetricsExportAutoConfiguration   ← @AutoConfiguration
├── <Backend>Properties                         ← @ConfigurationProperties
└── <Backend>PropertiesConfigAdapter            ← Properties → Micrometer Config 适配器

条件启用 ：@ConditionalOnEnabledMetricsExport("<backend>") → 检查 management.<backend>.metrics.export.enabled

3.5 MeterRegistryPostProcessor：度量体系组装中枢

这是整个模块最关键的 Bean，流程如下：

遍历 ApplicationContext 中所有 MeterRegistry Bean
按 @Order 排序所有 MeterFilter，通过 registry.config().meterFilter(f) 注册
遍历所有 MeterBinder，执行 binder.bindTo(registry)
遍历所有 MeterRegistryCustomizer，执行 customizer.customize(registry)
如果是 CompositeMeterRegistry，将子 registry 逐个添加

如果没有任何 MeterRegistry ：会自动创建一个 CompositeMeterRegistry。

3.6 JvmMetricsAutoConfiguration：JVM 指标

自动绑定（@ConditionalOnClass + @ConditionalOnEnabledMetricsExport("jvm")）：

指标	MeterBinder
JVM 内存 (堆/非堆/直接缓冲)	`JvmMemoryMetrics`
JVM GC (次数/时间)	`JvmGcMetrics`
线程 (live/daemon/peak)	`JvmThreadMetrics`
类加载 (loaded/unloaded)	`ClassLoaderMetrics`
虚拟线程 (Java 21+)	`JvmVirtualThreadMetrics` (4.1 新增)

3.7 SystemMetricsAutoConfiguration：系统指标

指标	说明
`system.cpu.count` / `system.cpu.usage`	CPU 核心数和使用率
`system.load.average.1m`	系统 1 分钟平均负载
`disk.free` / `disk.total`	磁盘空间 (`DiskSpaceMetricsBinder`)
`process.uptime` / `process.cpu.usage`	进程级指标

3.8 其他指标自动配置

AutoConfiguration	绑定内容
`LogbackMetricsAutoConfiguration`	Logback 日志事件计数器 (按级别)
`Log4J2MetricsAutoConfiguration`	Log4j2 日志事件计数器
`SslMetricsAutoConfiguration`	SSL 会话 + 握手时间 (JSSE)
`TaskExecutorMetricsAutoConfiguration`	线程池：活跃/队列/完成数
`StartupTimeMetricsListenerAutoConfiguration`	应用启动步骤耗时（依赖 `ApplicationStartup`）
`MetricsAspectsAutoConfiguration`	`@Timed` / `@Counted` AOP 拦截

4. AOT 编译支持

模块包含 ServiceLevelObjectiveBoundaryHints RuntimeHints 注册器，确保 SLO 阈值计算在 GraalVM native-image 下正常工作。

spring-boot-micrometer-metrics 的 AutoConfiguration 类均为 final + 静态工厂方法，符合 Spring Boot 4.x 的 AOT-first 设计。

5. 导出后端总览

后端	Registry 类型	协议	配置前缀
Simple	`SimpleMeterRegistry`	内存	`management.simple.metrics.export`
JMX	`JmxMeterRegistry`	JMX MBean	`management.jmx.metrics.export`
Prometheus	`PrometheusMeterRegistry`	HTTP scrape / Pushgateway	`management.prometheus.metrics.export`
OTLP	`OtlpMeterRegistry`	gRPC/HTTP (OTLP)	`management.otlp.metrics.export`
Graphite	`GraphiteMeterRegistry`	Carbon TCP/UDP	`management.graphite.metrics.export`
Datadog	`DatadogMeterRegistry`	HTTP API	`management.datadog.metrics.export`
Influx	`InfluxMeterRegistry`	HTTP	`management.influx.metrics.export`
Dynatrace	`DynatraceMeterRegistry`	HTTP API	`management.dynatrace.metrics.export`
Elastic	`ElasticMeterRegistry`	HTTP	`management.elastic.metrics.export`
StatsD	`StatsdMeterRegistry`	UDP/TCP	`management.statsd.metrics.export`
New Relic	`NewRelicMeterRegistry`	HTTP API	`management.newrelic.metrics.export`
Atlas	`AtlasMeterRegistry`	HTTP	`management.atlas.metrics.export`
Ganglia	`GangliaMeterRegistry`	UDP Multicast	`management.ganglia.metrics.export`
AppOptics	`AppOpticsMeterRegistry`	HTTP API	`management.appoptics.metrics.export`
Humio	`HumioMeterRegistry`	HTTP	`management.humio.metrics.export`
Kairos	`KairosMeterRegistry`	HTTP	`management.kairos.metrics.export`
Stackdriver	`StackdriverMeterRegistry`	gRPC	`management.stackdriver.metrics.export`

6. 总结

spring-boot-micrometer-metrics 是 Spring Boot 4.x 度量体系统一入口模块，涵盖：

1 个核心 AutoConfiguration ：MetricsAutoConfiguration（Clock、Filter、Binder、Customizer、Observation 桥接）
28 个 AutoConfiguration （含 17 个导出后端 + 7 个指标绑定 + 4 个辅助配置）
20+ 种可观测后端 ，每种遵循相同的 Properties → ConfigAdapter → AutoConfiguration 模式
Docker Compose / Testcontainers 自动发现 ：OTLP Collector 连接信息零配置注入
AOT / GraalVM Native Image 就绪 ：final 类 + 静态工厂 + RuntimeHints 注册