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,prometheusmetrics: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;}@PostMappingpublic 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应用中高效地监控业务性能，实现故障预警与性能优化。