如何快速接入Prometheus监控?skrstop-components Metrics Starter十分钟完全指南

原创2026-10-16 15:15:161,906 阅读

如何快速接入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 中:

  1. 用 process.memory.*、jvm_memory_* 等标准指标搭 JVM 面板;
  2. 用 druid_active、druid_pooling_count 观察连接池水位;
  3. 用 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 的项目属正常现象。

九、相关源码索引


总结:一个 Maven 依赖 + 几行 YAML,skrstop-components 的 Metrics Starter 就能让服务"自带" Prometheus 指标端点,JVM、数据库连接池、日志三大维度的监控开箱即用,把接入成本压缩到十分钟以内。

登录后查看全文
skrstop-components