Prometheus 监控 SpringBoot 应用完整教程

一、前言

SpringBoot 作为微服务架构的主流开发框架，其应用的稳定性直接决定了整个服务链路的可用性。Prometheus 作为开源监控领域的标杆工具，凭借灵活的指标采集、强大的查询能力和丰富的集成生态，成为监控 SpringBoot 应用的首选方案。

本文将从 环境准备、SpringBoot 应用改造、Prometheus 配置、指标可视化、告警配置 五个维度，手把手教你搭建可落地的 SpringBoot 应用监控体系，覆盖应用健康状态、JVM 运行指标、业务自定义指标等核心场景，适配容器化部署（Docker/Docker Compose）场景，兼顾新手入门与实操落地。

二、环境准备

2.1 基础环境清单

本次教程使用的环境版本如下（版本兼容可灵活调整，核心配置通用）：

• JDK：17 及以上

• SpringBoot：3.1.x

• Prometheus：v3.9.x

• Grafana：12.3.x

• Docker：20.10.x（可选，用于容器化部署 Prometheus/Grafana）

2.2 环境部署方式

推荐两种部署方式，可根据自身需求选择：

方式1：本地直接部署（适合测试）

• Prometheus：从 官方下载 对应系统版本，解压后即可启动。

• Grafana：从 官方下载，按系统指引安装并启动。

方式2：Docker Compose 部署（适合生产/快速验证）

创建 docker-compose.yml 文件，一键启动 Prometheus 和 Grafana，后续可直接对接 SpringBoot 应用：

services:
  prometheus:
    image: prom/prometheus:v3.9.1
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml  # 挂载配置文件
      - prometheus-data:/prometheus
    restart: always
    networks:
      - monitor-network

  grafana:
    image: grafana/grafana:12.3
    container_name: grafana
    ports:
      - "3000:3000"
	environment:
      - TZ=Asia/Shanghai
      - GF_SECURITY_ADMIN_USER=admin  # 初始账号
      - GF_SECURITY_ADMIN_PASSWORD=admin123  # 初始密码，建议登录后修改
      - GF_USERS_ALLOW_SIGN_UP=false  # 禁止注册
    volumes:
      - grafana-data:/var/lib/grafana
    restart: always
	user: '0'
    networks:
      - monitor-network
    depends_on:
      - prometheus

networks:
  monitor-network:
    driver: bridge

volumes:
  prometheus-data: 
  grafana-data:

执行 docker-compose up -d 启动服务，访问 http://localhost:9090 验证 Prometheus 启动成功，访问 http://localhost:3000 验证 Grafana（默认账号密码 admin/admin123）。

三、SpringBoot 应用改造（核心步骤）

SpringBoot 应用需集成 Prometheus 对应的指标暴露依赖，将应用运行指标、JVM 指标等转化为 Prometheus 可识别的格式（默认 OpenMetrics 格式），核心依赖为 spring-boot-starter-actuator 和 micrometer-registry-prometheus。

3.1 引入依赖（Maven/Gradle）

3.1.1 Maven 配置

<!-- 核心监控依赖：暴露应用指标 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- Prometheus 注册器：将指标转化为 Prometheus 格式 -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
<!-- 可选：JVM 详细监控（如需更细致的 JVM 指标） -->
<dependency>
    <groupId>io.micrometer</groupId>
<artifactId>micrometer-core</artifactId>
</dependency>

3.1.2 Gradle 配置

implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'io.micrometer:micrometer-registry-prometheus'
implementation 'io.micrometer:micrometer-core' // 可选

3.2 配置 application.yml（核心配置）

在 src/main/resources/application.yml 中添加监控配置，暴露指标端点供 Prometheus 采集：

spring:
  application:
    name: springboot-monitor-demo  # 应用名称，将作为 Prometheus 指标的标签

# Actuator 配置：暴露监控端点
management:
  endpoints:
    web:
      exposure:
        include: prometheus,health,info,metrics  # 暴露的端点，prometheus 是核心
      base-path: /actuator  # 接口前缀，默认/actuator
  endpoint:
    health:
      show-details: always  # 健康检查端点显示详细信息
      probes:
        enabled: true  # 开启健康探测（适合 Kubernetes 环境）
  metrics:
    tags:
      application: ${spring.application.name}  # 给所有指标添加 application 标签，便于筛选
    export:
      prometheus:
        enabled: true  # 开启 Prometheus 指标导出
  # 适配 SpringBoot 3.x 新增配置（2.x 无需添加）
  health:
    livenessState:
      enabled: true
    readinessState:
      enabled: true
    # 启用数据库健康检查（适配3.x）
    db:
      enabled: true

关键说明：

• prometheus 端点：默认地址 http://localhost:8080/actuator/prometheus，Prometheus 将从该地址采集指标。

• 标签配置：application 标签用于多应用监控时，快速筛选指定应用的指标。

3.3 启动应用并验证

1. 启动 SpringBoot 应用，确保无报错。

2. 访问 http://localhost:8080/actuator/prometheus，若能看到大量以 # HELP、# TYPE 开头的指标数据，说明应用改造成功。
   

3. 访问 http://localhost:8080/actuator/health
   

常见问题：若访问端点报 404，检查是否遗漏依赖、配置是否正确，或应用端口是否被修改（需替换为实际端口）。

3.4 自定义业务指标（可选）

除了默认的应用指标、JVM 指标，还可通过 Micrometer 自定义业务指标（如接口调用量、订单成交量等），示例如下：

3.4.1 定义计数器（统计接口调用次数）

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;

@RestController
public class DemoController {

    // 注入 MeterRegistry
    @Resource
    private MeterRegistry meterRegistry;

    // 定义计数器：统计 /test 接口调用次数
    private final Counter testApiCounter;

    // 构造方法初始化计数器
    public DemoController(MeterRegistry meterRegistry) {
        this.testApiCounter = meterRegistry.counter(
                "test_api_call_count",  // 指标名称
                "method", "GET",        // 自定义标签1
                "api", "/test"          // 自定义标签2
        );
    }

    @GetMapping("/test")
    public String test() {
        testApiCounter.increment();  // 每次调用接口，计数器+1
        return "success";
    }
}

3.4.2 其他指标类型

• 计时器（Timer）：统计接口响应时间，适合监控接口性能。

• gauge（仪表盘）：统计动态变化的值（如在线用户数）。

• Summary/Histogram：统计指标的分布情况（如响应时间分位数）。

自定义指标后，重启应用，访问 Prometheus 端点即可看到对应的指标数据。

四、Prometheus 配置（采集 SpringBoot 指标）

Prometheus 通过配置文件定义采集目标，需修改 prometheus.yml，添加 SpringBoot 应用的采集规则，确保 Prometheus 能定期拉取应用指标。

4.1 修改 prometheus.yml 配置

若使用 Docker Compose 部署，修改挂载的 prometheus.yml 文件；若本地部署，修改 Prometheus 解压目录下的 prometheus.yml：

global:
  scrape_interval: 15s  # 全局采集间隔，默认15秒，可根据需求调整
  evaluation_interval: 15s  # 规则评估间隔，用于告警规则、聚合规则

# 采集配置
scrape_configs:
  # 采集 Prometheus 自身指标（默认配置，可保留）
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  # 采集 SpringBoot 应用指标（核心配置）
  - job_name: 'springboot-monitor'  # 任务名称，自定义，便于识别
    metrics_path: '/actuator/prometheus'  # 指标采集路径（SpringBoot 暴露的端点）
    scrape_interval: 10s  # 单独设置该任务的采集间隔，优先级高于全局
    static_configs:
      # 配置 SpringBoot 应用的地址和端口，多个应用可添加多个 target
      - targets: ['192.168.1.100:8080']  # 本地应用：localhost:8080；容器化需用容器IP或宿主机映射IP
        labels:
          env: 'dev'  # 自定义标签：环境（开发/测试/生产）
          group: 'springboot-app'  # 自定义标签：应用组

关键配置说明

• job_name：采集任务的名称，将作为指标的 job 标签，用于区分不同采集目标。

• metrics_path：SpringBoot 暴露 Prometheus 指标的路径，固定为 /actuator/prometheus。

• targets：SpringBoot 应用的地址，格式为 IP:端口。若应用和 Prometheus 部署在同一 Docker 容器网络，需使用容器名称（如 springboot-demo:8080）；若跨网络，需使用宿主机 IP + 映射端口。

• 自定义标签：env、group 等标签可根据实际场景添加，便于后续筛选和聚合指标。

4.2 重启 Prometheus 并验证采集

1. 重启 Prometheus 服务：

   • 本地部署：执行 Prometheus 解压目录下的重启脚本，或重新启动进程。

   • Docker Compose 部署：执行 docker-compose restart prometheus。

2. 验证采集是否成功：

   • 访问 Prometheus 控制台 http://localhost:9090，点击顶部「Status」→「Targets」。

   • 找到 springboot-monitor 任务，若「State」为 UP，说明采集成功；若为 DOWN，检查应用是否正常运行、地址是否正确、网络是否互通。
     

4.3 容器化 SpringBoot 应用的采集适配

若 SpringBoot 应用也通过 Docker 部署，需注意网络配置，确保 Prometheus 能访问到应用：

1. 将 SpringBoot 应用加入 Prometheus 所在的 Docker 网络（即 monitor-network），修改应用的 docker-compose.yml，添加网络配置。

2. 修改 Prometheus 采集配置中的 targets，使用 SpringBoot 应用的容器名称作为地址，示例：`static_configs:

• targets: 'springboot-demo:8080' # springboot-demo 是应用的容器名称`

五、Grafana 可视化指标（可选但推荐）

Prometheus 自带的控制台仅支持简单的指标查询，Grafana 提供了丰富的仪表盘模板，可快速实现 SpringBoot 指标（应用、JVM）的可视化，步骤如下：

5.1 配置 Prometheus 数据源

1. 登录 Grafana（默认账号密码 admin/admin，首次登录需修改密码）。

2. 点击左侧「Configuration」→「Data sources」，点击「Add data source」，选择「Prometheus」。

3. 在「HTTP」→「URL」中输入 Prometheus 的地址（如http://prometheus:9090，Docker 网络下使用容器名称；本地部署为 http://localhost:9090）。

4. 点击「Save & test」，提示「Data source is working」即配置成功。

5.2 导入 SpringBoot/JVM 仪表盘模板

Grafana 官方社区提供了成熟的 SpringBoot、JVM 仪表盘模板，无需手动配置图表，直接导入即可：

1. 点击左侧「Dashboards」→「Import」，输入模板 ID，点击「Load」。

2. 推荐模板 ID（适配本次配置）：

   • SpringBoot 应用监控：12856（官方推荐，覆盖应用指标、接口指标）。

   • JVM 监控：4701（详细展示 JVM 内存、GC、线程等指标）。

3. 选择已配置的 Prometheus 数据源，点击「Import」，即可生成完整的仪表盘。
   

自定义仪表盘：若模板不符合需求，可手动添加图表，选择对应的 Prometheus 指标（如 http_server_requests_seconds_sum 接口响应时间、jvm_memory_used_bytes JVM 内存使用量），设置图表类型和筛选条件。

六、配置告警规则（可选）

基于 Prometheus 配置告警规则，当 SpringBoot 应用出现异常（如服务宕机、接口响应时间过长、JVM 内存溢出）时，触发告警，结合 Alertmanager 可实现钉钉、邮件等告警通知（适配此前用户钉钉告警需求）。

6.1 配置 Prometheus 告警规则

修改 prometheus.yml，添加告警规则配置，指定告警规则文件路径：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

# 告警规则配置
rule_files:
  - "alert_rules.yml"  # 告警规则文件，需与 prometheus.yml 同级

# 采集配置（省略，同前文）
scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
  - job_name: 'springboot-monitor'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['192.168.1.100:8080']

在 Prometheus 配置目录下创建 alert_rules.yml，添加 SpringBoot 应用相关的告警规则：

groups:
  - name: springboot-alert-rules  # 告警规则组名称
    rules:
      # 规则1：应用宕机告警（采集目标 DOWN 超过 1 分钟）
      - alert: SpringBootServiceDown
        expr: up{job="springboot-monitor"} == 0
        for: 1m  # 持续 1 分钟触发告警
        labels:
          severity: critical  # 告警级别（critical/warning/info）
          alert_type: service  # 告警类型
        annotations:
          summary: "SpringBoot 应用宕机"
          description: "应用 {{ $labels.application }}（{{ $labels.instance }}）已宕机，持续时间超过 1 分钟，请及时排查。"

      # 规则2：JVM 堆内存使用率过高（超过 90% 持续 5 分钟）
      - alert: JvmHeapMemoryHighUsage
        expr: jvm_memory_used_bytes{area="heap", application=~".+"} / jvm_memory_max_bytes{area="heap", application=~".+"} > 0.9
        for: 5m
        labels:
          severity: warning
          alert_type: jvm
        annotations:
          summary: "JVM 堆内存使用率过高"
          description: "应用 {{ $labels.application }}（{{ $labels.instance }}）JVM 堆内存使用率已超过 90%，当前使用率：{{ $value | humanizePercentage }}，请检查内存泄漏或扩容。"

      # 规则3：接口响应时间过长（P95 响应时间超过 500ms 持续 3 分钟）
      - alert: ApiResponseTimeTooLong
        expr: histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket[5m])) by (le, application, instance, uri)) > 0.5
        for: 3m
        labels:
          severity: warning
          alert_type: api
        annotations:
          summary: "接口响应时间过长"
          description: "应用 {{ $labels.application }}（{{ $labels.instance }}）接口 {{ $labels.uri }} P95 响应时间超过 500ms，当前值：{{ $value | humanizeDuration }}，请优化接口性能。"

6.2 集成 Alertmanager 实现钉钉告警

Prometheus 本身不支持发送告警通知，需集成 Alertmanager，结合钉钉机器人实现告警推送，步骤如下：

1. 部署 Alertmanager：参考 Docker Compose 配置，添加 Alertmanager 服务（需修改 docker-compose.yml，新增 Alertmanager 容器，挂载配置文件）。

2. 配置 Alertmanager：修改 alertmanager.yml，添加钉钉机器人 WebHook 地址，定义告警路由和接收规则。

3. 关联 Prometheus 与 Alertmanager：在 prometheus.yml 中添加 Alertmanager 地址配置，让 Prometheus 将告警信息推送至 Alertmanager。

详细的 Alertmanager 与钉钉集成配置，可参考此前的监控体系搭建教程，核心是配置钉钉机器人 WebHook，确保告警信息能准确推送至指定钉钉群。

七、常见问题排查

7.1 Prometheus 采集目标显示 DOWN

• 网络问题：检查 Prometheus 与 SpringBoot 应用是否互通，防火墙是否开放端口。

• 地址错误：确认 targets 中的 IP 和端口正确，容器化应用需使用容器网络可访问的地址。

• 应用未启动：检查 SpringBoot 应用是否正常运行，访问 /actuator/prometheus 端点是否可用。

7.2 Grafana 无法查询到指标

• 数据源配置错误：检查 Grafana 中 Prometheus 数据源的 URL 是否正确，是否能连通。

• 指标标签筛选错误：确认查询的指标是否包含 application、job 等标签，筛选条件是否正确。

• 采集间隔未到：等待 1-2 个采集间隔（如 10-15 秒），Prometheus 需时间拉取指标。

7.3 自定义指标未显示

• 依赖缺失：确认已引入 micrometer-registry-prometheus 依赖。

• 指标未触发：自定义计数器、计时器需触发对应的业务操作（如调用接口），指标才会生成。

• 配置错误：检查 management.metrics.export.prometheus.enabled 是否设置为 true。

八、总结

本文完成了从 SpringBoot 应用改造、Prometheus 指标采集、Grafana 可视化到告警配置的全流程搭建，核心要点如下：

1. SpringBoot 应用：通过 actuator 和 micrometer 依赖暴露指标，核心端点为 /actuator/prometheus。

2. Prometheus：配置采集规则，定期拉取应用指标，支持自定义标签和采集间隔。

3. Grafana：导入现成模板快速实现可视化，适配应用和 JVM 监控场景。

4. 告警配置：通过 Prometheus 告警规则定义异常场景，结合 Alertmanager 实现钉钉等渠道告警。

该方案可直接适配容器化部署场景，后续可扩展至多应用、多环境监控，结合 Prometheus 聚合规则实现指标汇总，为微服务架构的稳定性提供保障。若需适配 SpringBoot 3.x 或更复杂的业务监控场景，可调整依赖和配置细节，核心逻辑保持一致。