Spring Boot Actuator自定义指标与监控实践指南

Spring Boot Actuator自定义指标与监控实践指南

本篇文章以生产环境实战经验为主线，结合某电商系统的业务场景，讲解如何在Spring Boot Actuator中添加并暴露自定义指标，并使用Prometheus和Grafana进行完整的监控与告警配置。

一、业务场景描述

在电商系统中，我们希望监控以下关键指标：

下单接口响应时间（Order API Latency）
库存锁定成功次数（Inventory Lock Success Count）
订单支付失败率（Payment Failure Rate）
用户访问量（Active Users）

传统的日志埋点无法满足实时监控需求，通过Spring Boot Actuator与Micrometer，可以快速采集并暴露应用指标。

二、技术选型过程

我们选用了以下技术栈：

Spring Boot Actuator：提供内置监控端点
Micrometer：度量指标采集框架，兼容常见监控系统
Prometheus：指标拉取与存储
Grafana：可视化展示与告警规则

该方案能够无缝集成Spring生态，具备开箱即用和自定义扩展能力。

三、实现方案详解

3.1 引入依赖

在pom.xml中添加：

xml 复制代码

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

3.2 配置application.yml

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  metrics:
    export:
      prometheus:
        enabled: true

3.3 自定义指标实现

创建一个MetricsService，在业务逻辑中注入MetricsRegistry：

java 复制代码

package com.example.monitor;

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.stereotype.Service;

@Service
public class MetricsService {
    private final Counter inventoryLockCounter;
    private final Timer orderLatencyTimer;

    public MetricsService(MeterRegistry registry) {
        this.inventoryLockCounter = Counter.builder("inventory.lock.success.count")
                .description("库存锁定成功次数")
                .register(registry);
        this.orderLatencyTimer = Timer.builder("order.api.latency")
                .description("下单接口响应时间")
                .publishPercentiles(0.5, 0.95)
                .register(registry);
    }

    public void recordInventoryLockSuccess() {
        inventoryLockCounter.increment();
    }

    public <T> T recordOrderLatency(Supplier<T> supplier) {
        return orderLatencyTimer.record(supplier);
    }
}

在OrderController中使用：

java 复制代码

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final MetricsService metricsService;
    private final OrderService orderService;

    public OrderController(MetricsService metricsService, OrderService orderService) {
        this.metricsService = metricsService;
        this.orderService = orderService;
    }

    @PostMapping
    public ResponseEntity<Order> createOrder(@RequestBody OrderRequest req) {
        // 记录订单处理时间
        Order order = metricsService.recordOrderLatency(() -> orderService.createOrder(req));
        // 记录库存锁定成功次数
        metricsService.recordInventoryLockSuccess();
        return ResponseEntity.ok(order);
    }
}

3.4 Prometheus与Grafana集成

在Prometheus配置中添加Spring Boot应用地址：

yaml 复制代码

scrape_configs:
  - job_name: 'spring-boot-app'
    static_configs:
      - targets: ['app-host:8080']

Grafana中导入Dashboard模板（可参考官方Micrometer模板），或自行创建：
- 使用order_api_latency查询响应时间分布
- 使用inventory_lock_success_count监控锁定次数

3.5 完整项目结构示例

复制代码

monitoring-sample/
├─ src/
│  ├─ main/
│  │  ├─ java/com/example/monitor/  # 业务代码与监控实现
│  │  └─ resources/
│  │     └─ application.yml        # Actuator和Prometheus配置
│  └─ test/
└─ pom.xml

四、踩过的坑与解决方案

自定义指标未暴露：
- 原因：未在application.yml中启用prometheus端点
- 解决：management.endpoints.web.exposure.include: prometheus
Label标签过多导致高基数问题：
- 避免使用用户ID、动态路径作为标签
- 建议只使用固定维度，如region、status等
Prometheus拉取失败：
- 检查网络与防火墙
- 确认拉取路径/actuator/prometheus正确
Grafana图表无数据：
- 检查Prometheus中是否已有历史数据
- 调整Dashboard查询语句和时间范围

五、总结与最佳实践

为关键业务埋点自定义指标，并使用合理的单位和命名规范
限制标签基数，避免高基数带来的存储和查询压力
合理设置Prometheus抓取频率和数据保留策略
在Grafana中通过告警规则及时通知异常状态
定期评审指标体系，保持指标与业务场景同步

通过以上实践，可在Spring Boot应用中高效地监控业务性能，实现故障预警与性能优化。