如何快速接入Prometheus监控?skrstop-components Metrics Starter十分钟完全指南
如何快速接入Prometheus监控?skrstop-components Metrics Starter十分钟完全指南
skrstop-components 是一套基于 Spring Boot 的常用功能封装(通用响应、通用异常、数据库、Redis、远程存储等),其中的 Metrics Starter(components-starter-metrics)专门解决"Prometheus 监控接入"问题:引入一个依赖、配置几行 YAML,就能把 JVM 进程指标、Druid 连接池指标、log4j2 日志指标暴露在 /actuator/prometheus 端点上,无需手写任何 Collector 代码。本文带你十分钟完成全部接入。
一、Metrics Starter 是什么?
模块位于 components-starter-metrics/,本质是一个监控自动配置层:Spring Boot Actuator + Micrometer + Prometheus 三件套的整合封装。
查看 pom.xml 可以看到它内置了这些关键依赖:
| 依赖 | 作用 |
|---|---|
micrometer-registry-prometheus |
指标注册表,提供 /actuator/prometheus 端点 |
micrometer-jvm-extras |
补充 JVM 进程级指标 |
spring-boot-starter-actuator |
健康检查与标准指标(已替换 logback 为 log4j2) |
druid(optional) |
仅在 classpath 存在 Druid 时启用连接池采集 |
一句话:它让你的 Spring Boot 项目"天生会汇报监控数据"。
二、Maven 依赖一步添加
在你的业务工程 pom.xml 中加入:
<dependency>
<groupId>com.skrstop.framework</groupId>
<artifactId>components-starter-metrics</artifactId>
<version>1.3.5.20260520-RELEASE</version> <!-- 建议以 CHANGELOG.md 中的最新版本为准 -->
</dependency>
⚠️ 版本与 JDK 要求:1.3.x 系列需要 JDK 17+;如果你的项目仍在 JDK 8~16,请改用 1.2.x 系列(模块名相同,仅版本号不同)。
需要研读源码的话,可以先克隆仓库浏览:
git clone https://gitcode.com/gh_mirrors/sk/skrstop-components
三、最快配置:只改 3 行 YAML 暴露指标端点
Spring Boot Actuator 默认只通过 Web 暴露 health 端点,要让 Prometheus 抓取成功,需要把 prometheus 端点"开门":
# application.yml
management:
endpoints:
web:
exposure:
include: prometheus,health
启动应用后访问 http://localhost:8080/actuator/prometheus,能看到大量 # HELP 开头的文本即代表接入成功 ✅。
此时零配置已经自动采集的指标包括:
| 指标类别 | 说明 | 来源 |
|---|---|---|
| JVM 内存 / GC / 线程 / CPU | Actuator 标准指标 | spring-boot-actuator |
process.memory.*、process.thread.* 等进程级补充指标 |
默认开启 | MetricsAutoConfiguration.java |
log4j2_events_total 日志级别计数 |
应用启动后自动绑定 | Log4j2CountExportAutoConfiguration.java |
四、Druid 连接池指标一键采集
如果项目使用 Druid 连接池(例如通过 components-starter-database 模块接入数据库),Metrics Starter 可以把连接池、SQL、URI 三大类统计直接汇报给 Prometheus,只需打开三个开关:
management:
metrics:
enable:
druid: true # 连接池指标
druid-sql: true # SQL 维度指标
druid-uri: true # URI 维度指标
tags:
app: my-service # 为所有指标附加标签,多服务部署时方便区分
采集逻辑在 DruidCollector.java 中实现,能力相当全面:
- 连接池:30 余项指标,如
druid_active(活跃连接数)、druid_pooling_count(空闲连接数)、druid_execute_error_count等; - SQL:
druid_sql_execute_count、druid_sql_total_time、druid_sql_error_count等,并可拿到最近一次 SQL 报错的类名与消息; - URI:
druid_uri_request_count、druid_uri_request_time_millis等 Web 请求维度统计; - 直方图:事务耗时、连接持有时间等统一按
1ms / 10ms / 100ms / 1s / 10s / 100s分桶,便于画 P99 分位线; - 所有指标自动带上
dbType、dbHost、dbName三个标签,Grafana 里按库拆分一目了然。
五、可选:log4j2 异步日志 RingBuffer 监控
如果你使用 log4j2 的 AsyncLogger,建议额外开启 RingBuffer 剩余容量监控,能提前发现日志队列打满的风险:
management:
metrics:
enable:
log4j2.ringBuffer: true
该功能默认关闭(需显式开启),实现在 Log4j2RingBufferExportAutoConfiguration.java,会为每个 Logger 暴露 xxx_logger_ring_buffer_remaining_capacity 指标。
六、Prometheus 抓取配置(scrape_configs)
在 Prometheus 的 prometheus.yml 中加入一个 job 即可:
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'skrstop-app'
metrics_path: /actuator/prometheus
static_configs:
- targets: ['localhost:8080']
重启 Prometheus 后,在 Targets 页面看到 up 即为绿色。随后在 Grafana 中:
- 用
process.memory.*、jvm_memory_*等标准指标搭 JVM 面板; - 用
druid_active、druid_pooling_count观察连接池水位; - 用
log4j2_events_total观察错误日志突增。
七、一键关闭:skrstop.metrics.enabled
所有"额外"指标(进程补充指标、Druid、log4j2)受统一开关控制,一行全部关闭:
skrstop:
metrics:
enabled: false
该开关定义在 MetricsProperties.java(前缀 skrstop.metrics,默认 true)。若只想关某一项,则用 management.metrics.enable.* 精细控制。
八、常见问题排查清单
Q1:加了依赖,但 /actuator/prometheus 打不开?
没有暴露端点。按第三节加上 management.endpoints.web.exposure.include: prometheus 后重启。
Q2:druid_* 指标一个都看不到?
三个条件缺一不可:① classpath 中存在 Druid;② Prometheus 注册表存在(即 micrometer prometheus registry 已启用);③ management.metrics.enable.druid: true。具体条件见 DruidPrometheusAutoConfiguration.java。
Q3:log4j2 日志指标没出现? log4j2 指标仅在 classpath 存在 log4j2 时绑定,使用 logback 的项目属正常现象。
九、相关源码索引
- 自动配置入口:configuration/
- Druid 采集器:prometheus/druid/
- log4j2 采集器:prometheus/log4j2/
- 版本发布记录:CHANGELOG.md
总结:一个 Maven 依赖 + 几行 YAML,skrstop-components 的 Metrics Starter 就能让服务"自带" Prometheus 指标端点,JVM、数据库连接池、日志三大维度的监控开箱即用,把接入成本压缩到十分钟以内。