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

文章目录1. 概述2. 包结构与模块划分2.1 整体分层2.2 根包全局Filter 故障诊断2.3 actuate/endpoint 指标端点2.3 autoconfigure 核心自动配置包2.3.1 核心自动配置类2.3.2 autoconfigure/export 导出到监控系统2.3.3 内置指标 Binder 模块2.4 OTLP 开发测试辅助2.5 prometheus 独立导出端点2.6 顶层独立组件3. 核心类3.1 MetricsAutoConfiguration主配置入口3.2 MetricsProperties外部化配置模型3.3 SimpleMetricsExportAutoConfiguration简易注册表3.4 导出后端统一模式3.5 MeterRegistryPostProcessor度量体系组装中枢3.6 JvmMetricsAutoConfigurationJVM 指标3.7 SystemMetricsAutoConfiguration系统指标3.8 其他指标自动配置4. AOT 编译支持5. 导出后端总览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.0Actuator负责暴露端点本模块负责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/otlptestcontainers/otlp开发测试环境自动对接 OTLP Collector独立监听器根下 startup / system启动时间监听、磁盘指标Binder2.2 根包全局Filter 故障诊断MaximumAllowableTagsMeterFilter属于MeterFilter实现拦截Meter注册限制单个指标Tag最大数量防止Tag爆炸高基数维度引发内存暴涨。由management.metrics.maximum-allowable-tags属性控制。ValidationFailureAnalyzerSpring BootFailureAnalyzer捕获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加载全局MeterFilterMetricsProperties绑定management.metrics.*yml/properties全部配置项MetricsEndpointAutoConfiguration条件装配开启actuator metrics端点才创建MetricsEndpointMetricsAspectsAutoConfigurationAOP切面支持注解Timed、Counted自动对方法埋点CompositeMeterRegistryAutoConfiguration组装组合注册表把各个导出后端的MeterRegistry加到Composite一份指标多输出MeterRegistryPostProcessorBeanPostProcessor收集所有MeterFilter、MeterBinder、MeterRegistryCustomizer回调应用到MeterRegistryMeterRegistryCustomizerSPI接口业务可实现对MeterRegistry做自定义修改PropertiesMeterFilter将配置文件里management.metrics.tags、filter配置转成MicrometerMeterFilterMeterValue / 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日志条数sslSSL证书有效期、握手统计task线程池队列、活跃线程、拒绝任务startup基于ApplicationStartup事件采集各个阶段启动耗时。2.4 OTLP 开发测试辅助仅开发/集成测试使用生产不会加载docker compose检测compose环境自动注入OTLP Collector地址testcontainers单元集成测试拉起OTLP Collector容器自动配置导出地址。2.5 prometheus 独立导出端点export/prometheus/endpointActuator原生端点输出原始 Prometheus 文本格式/actuator/prometheus。PrometheusPushGatewayManager定时把指标推送到PushGateway。2.6 顶层独立组件StartupTimeMetricsListener监听Spring启动事件生成启动时间指标和autoconfigure/startup配合。DiskSpaceMetricsBinder采集磁盘分区可用、总空间指标。3. 核心类3.1 MetricsAutoConfiguration主配置入口AutoConfiguration(beforeCompositeMeterRegistryAutoConfiguration.class)ConditionalOnClass(Timed.class)EnableConfigurationProperties(MetricsProperties.class)publicfinalclassMetricsAutoConfiguration{// ...}职责初始化度量体系的基础设施。关键设计决策Bean都是静态内部类的无副作用的工厂方法便于AOT编译MeterRegistryPostProcessor是staticBean在常规Bean初始化之前运行通过ObservationHandlerGroup将所有MeterObservationHandler分组支持Observation体系自动注册的组件BeanBean类型说明micrometerClockClock默认Clock.SYSTEM自动配置未覆盖时meterRegistryPostProcessorMeterRegistryPostProcessor核心后处理器收集所有MeterFilter/MeterBinder/MeterRegistryCustomizer注入到每个MeterRegistrypropertiesMeterFilterPropertiesMeterFilter从management.metrics.enable/tags等属性生成MeterFilter权重最低Order(0)meterRegistryCloserMeterRegistryCloser监听ContextClosedEvent确保 MeterRegistry 优雅关闭metricsObservationHandlerGroupObservationHandlerGroup注册 Micrometer 为 Observation HandlerdefaultMeterObservationHandlerDefaultMeterObservationHandler将 Observation API 的度量桥接到 MeterRegistry3.2 MetricsProperties外部化配置模型前缀management.metricsConfigurationProperties(management.metrics)publicclassMetricsProperties{booleanuseGlobalRegistrytrue;// 是否绑定全球注册表MapString,Booleanenable...;// 按名称启用/禁用指标MapString,Stringtags...;// 公共标签Webweb;// web.client.maxUriTags / web.server.maxUriTagsSystemsystem;// system.diskspace.*Distributiondistribution;// 分布统计百分位、SLA、最小期望值等Observationsobservations;// observation.ignoredMeters}配置示例management:metrics:use-global-registry:falseenable:jvm:truelogback:falsetags:region:cn-shanghaiapp:${spring.application.name}web:server:max-uri-tags:200distribution:slo:http.server.requests:10ms,50ms,100ms,200ms,500ms,1s,2spercentiles:http.server.requests:0.5,0.75,0.95,0.993.3 SimpleMetricsExportAutoConfiguration简易注册表默认启用的内存MeterRegistry当没有其他注册表时配置前缀management.simple.metrics.export.*SimplePropertiesConfigAdapter将Spring属性桥接到Micrometer的SimpleConfig适合开发环境生产环境通常替换为Prometheus/OTLP等BeanSimpleMeterRegistrysimpleMeterRegistry(SimpleConfigconfig,Clockclock){returnnewSimpleMeterRegistry(config,clock);}BeanConditionalOnMissingBeanSimpleConfigsimpleConfig(SimplePropertiessimpleProperties){returnnewSimplePropertiesConfigAdapter(simpleProperties);}3.4 导出后端统一模式每个后端都遵循相同的三件套模式export/backend/ ├── BackendMetricsExportAutoConfiguration ← AutoConfiguration ├── BackendProperties ← ConfigurationProperties └── BackendPropertiesConfigAdapter ← Properties → Micrometer Config 适配器条件启用ConditionalOnEnabledMetricsExport(backend)→ 检查management.backend.metrics.export.enabled3.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 JvmMetricsAutoConfigurationJVM 指标自动绑定ConditionalOnClassConditionalOnEnabledMetricsExport(jvm)指标MeterBinderJVM 内存 (堆/非堆/直接缓冲)JvmMemoryMetricsJVM GC (次数/时间)JvmGcMetrics线程 (live/daemon/peak)JvmThreadMetrics类加载 (loaded/unloaded)ClassLoaderMetrics虚拟线程 (Java 21)JvmVirtualThreadMetrics(4.1 新增)3.7 SystemMetricsAutoConfiguration系统指标指标说明system.cpu.count/system.cpu.usageCPU 核心数和使用率system.load.average.1m系统 1 分钟平均负载disk.free/disk.total磁盘空间 (DiskSpaceMetricsBinder)process.uptime/process.cpu.usage进程级指标3.8 其他指标自动配置AutoConfiguration绑定内容LogbackMetricsAutoConfigurationLogback 日志事件计数器 (按级别)Log4J2MetricsAutoConfigurationLog4j2 日志事件计数器SslMetricsAutoConfigurationSSL 会话 握手时间 (JSSE)TaskExecutorMetricsAutoConfiguration线程池活跃/队列/完成数StartupTimeMetricsListenerAutoConfiguration应用启动步骤耗时依赖ApplicationStartupMetricsAspectsAutoConfigurationTimed/CountedAOP 拦截4. AOT 编译支持模块包含ServiceLevelObjectiveBoundaryHintsRuntimeHints注册器确保SLO阈值计算在GraalVM native-image下正常工作。spring-boot-micrometer-metrics的AutoConfiguration类均为final 静态工厂方法符合Spring Boot 4.x的AOT-first设计。5. 导出后端总览后端Registry 类型协议配置前缀SimpleSimpleMeterRegistry内存management.simple.metrics.exportJMXJmxMeterRegistryJMX MBeanmanagement.jmx.metrics.exportPrometheusPrometheusMeterRegistryHTTP scrape / Pushgatewaymanagement.prometheus.metrics.exportOTLPOtlpMeterRegistrygRPC/HTTP (OTLP)management.otlp.metrics.exportGraphiteGraphiteMeterRegistryCarbon TCP/UDPmanagement.graphite.metrics.exportDatadogDatadogMeterRegistryHTTP APImanagement.datadog.metrics.exportInfluxInfluxMeterRegistryHTTPmanagement.influx.metrics.exportDynatraceDynatraceMeterRegistryHTTP APImanagement.dynatrace.metrics.exportElasticElasticMeterRegistryHTTPmanagement.elastic.metrics.exportStatsDStatsdMeterRegistryUDP/TCPmanagement.statsd.metrics.exportNew RelicNewRelicMeterRegistryHTTP APImanagement.newrelic.metrics.exportAtlasAtlasMeterRegistryHTTPmanagement.atlas.metrics.exportGangliaGangliaMeterRegistryUDP Multicastmanagement.ganglia.metrics.exportAppOpticsAppOpticsMeterRegistryHTTP APImanagement.appoptics.metrics.exportHumioHumioMeterRegistryHTTPmanagement.humio.metrics.exportKairosKairosMeterRegistryHTTPmanagement.kairos.metrics.exportStackdriverStackdriverMeterRegistrygRPCmanagement.stackdriver.metrics.export6. 总结spring-boot-micrometer-metrics是Spring Boot 4.x度量体系统一入口模块涵盖1 个核心 AutoConfigurationMetricsAutoConfigurationClock、Filter、Binder、Customizer、Observation桥接28 个 AutoConfiguration含17个导出后端 7个指标绑定 4个辅助配置20 种可观测后端每种遵循相同的Properties→ConfigAdapter→AutoConfiguration模式Docker Compose / Testcontainers 自动发现OTLP Collector连接信息零配置注入AOT / GraalVM Native Image 就绪final类 静态工厂 RuntimeHints注册