Spring Boot Actuator：生产级监控与自定义健康检查

1. 概述

Spring Boot Actuator 提供了强大的生产级监控能力，帮助开发者更好地了解应用的健康状态和性能表现。然而，默认的健康检查和指标并不总是足够的。

主要内容

• Spring Boot Actuator 概览
• 创建自定义健康指标
• 暴露自定义指标（CPU、数据库查询、API 响应时间等）
• 使用 Prometheus 和 Grafana 可视化指标
• 在 Kubernetes 中部署 Actuator

2. 典型应用场景

设想一个高流量电商网站 🛒，其监控需求可能包括：

问题表现

• 用户反馈结账流程缓慢
• 频繁出现随机 500 错误
• 数据库性能下降

根本原因

标准 Actuator 仅报告：

• ✔ JVM 运行中
• ✔ 数据库已连接

但无法检测性能瓶颈，例如：

• 慢查询
• 内存泄漏
• CPU 峰值

解决方案

通过 自定义健康检查 和 自定义监控指标，实现对真实系统状态的追踪！

---

3. 启用 Spring Boot Actuator

添加依赖（pom.xml）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

配置端点（application.yml）

management:
  endpoints:
    web:
      exposure:
        include: "health,metrics,info"
  endpoint:
    health:
      show-details: always

访问默认健康检查端点

curl http://localhost:8080/actuator/health

响应示例

{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "diskSpace": { "status": "UP" }
  }
}

---

4. 创建自定义健康检查

架构示意图

自定义健康检查可用于检测数据库查询性能、Redis 可用性、外部 API 连接等。

示例：自定义数据库查询健康检查

@Component
public class DatabaseQueryHealthIndicator extends AbstractHealthIndicator {
    
    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        long startTime = System.currentTimeMillis();
        jdbcTemplate.queryForObject("SELECT 1", Integer.class);
        long elapsedTime = System.currentTimeMillis() - startTime;

        if (elapsedTime < 100) {
            builder.up().withDetail("queryTime", elapsedTime + "ms");
        } else {
            builder.down().withDetail("queryTime", elapsedTime + "ms");
        }
    }
}

增强后的 /health 端点响应

{
  "status": "UP",
  "components": {
    "dbQuery": {
      "status": "UP",
      "queryTime": "12ms"
    }
  }
}

---

5. 暴露自定义监控指标

添加 Micrometer 依赖（pom.xml）

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

示例：监控 API 响应时间

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

    @Autowired
    private MeterRegistry meterRegistry;

    @GetMapping("/orders")
    public List<String> getOrders() {
        Timer timer = Timer.builder("order_api_timer")
                .description("追踪/orders 接口响应时间")
                .register(meterRegistry);

        return timer.record(() -> {
            simulateProcessingDelay();
            return List.of("Order1", "Order2");
        });
    }

    private void simulateProcessingDelay() {
        try {
            Thread.sleep(new Random().nextInt(200)); // 模拟随机延迟
        } catch (InterruptedException ignored) {}
    }
}

查询指标

curl http://localhost:8080/actuator/metrics/order_api_timer

响应示例

{
  "name": "order_api_timer",
  "measurements": [
    { "statistic": "COUNT", "value": 150 },
    { "statistic": "TOTAL_TIME", "value": 30.3 }
  ]
}

---

6. 使用 Prometheus & Grafana 可视化

配置 Prometheus（prometheus.yml）

scrape_configs:
  - job_name: 'spring-boot'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['localhost:8080']

Docker 启动 Prometheus

docker run -d --name=prometheus -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus

访问 Prometheus UI

http://localhost:9090

示例查询

{order_api_timer}

配置 Grafana 监控面板

Docker 安装 Grafana

docker run -d -p 3000:3000 grafana/grafana

步骤

1. 添加 Prometheus 作为数据源
2. 创建新面板
3. 选择 order_api_timer 指标进行可视化

---

7. 在 Kubernetes 中部署 Actuator

配置健康探针（application.yml）

management:
  endpoint:
    health:
      probes:
        enabled: true
  health:
    livenessState:
      enabled: true
    readinessState:
      enabled: true

效果

• /actuator/health 返回 DOWN 时，Kubernetes 自动重启 Pod

---

8. 结论

为什么 Actuator 适用于生产环境？

✔ 实时系统健康监控
✔ 数据库性能追踪
✔ API 性能指标暴露
✔ 云原生集成（Prometheus/Kubernetes）

通过 自定义健康检查 和 指标监控，我们可以构建一个更健壮的 Spring Boot 生产环境！ 🚀