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中添加：

<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

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

3.3 自定义指标实现

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

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中使用：

@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集成

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

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

2. 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

四、踩过的坑与解决方案

1. 自定义指标未暴露：

   • 原因：未在application.yml中启用prometheus端点
   • 解决：management.endpoints.web.exposure.include: prometheus

2. Label标签过多导致高基数问题：

   • 避免使用用户ID、动态路径作为标签
   • 建议只使用固定维度，如region、status等

3. Prometheus拉取失败：

   • 检查网络与防火墙
   • 确认拉取路径/actuator/prometheus正确

4. Grafana图表无数据：

   • 检查Prometheus中是否已有历史数据
   • 调整Dashboard查询语句和时间范围

五、总结与最佳实践

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

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