1. 概念

Spring Boot Actuator 是 Spring Boot 提供的一个强大功能模块，用于监控和管理 Spring Boot 应用程序的状态。Actuator 提供了丰富的内置端点，开发者可以通过这些端点实时查看应用的健康状态、指标数据、环境配置、内存使用等信息，帮助开发者轻松进行应用的监控和管理。

Actuator 是通过 spring-boot-starter-actuator 这个起步依赖引入到 Spring Boot 项目中的，它可以与常见的监控工具（如 Prometheus、Grafana）集成，实现应用的可视化监控和管理。

2. 设计

Actuator 的设计基于几个核心概念：

• 端点（Endpoint）：Actuator 通过端点提供应用的各种运行时信息。每个端点都代表着一种操作或信息暴露，比如 /actuator/health 显示应用健康状况，/actuator/metrics 提供应用的性能指标。
• 暴露方式：Actuator 端点可以通过 HTTP 或 JMX 暴露，默认通过 HTTP 暴露。
• 安全性：为了防止未授权访问敏感信息，Spring Boot 提供了对 Actuator 端点的安全控制，开发者可以通过 Spring Security 控制访问权限。

3. 使用

3.1 引入依赖

要在 Spring Boot 项目中使用 Actuator，首先需要在项目的 pom.xml 中添加 spring-boot-starter-actuator 依赖：

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

3.2 端点访问

引入依赖后，Actuator 提供了一些默认的端点用于监控和管理。常见的端点包括：

• /actuator/health：查看应用程序的健康状态。
• /actuator/metrics：查看应用程序的性能指标。
• /actuator/info：展示应用程序的基本信息（可以通过配置提供）。
• /actuator/env：查看应用程序的环境属性和配置信息。
• /actuator/beans：显示 Spring 容器中的 Bean 列表。

示例：访问健康检查端点 /actuator/health，可以获取类似以下的信息：

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 123456789012,
        "threshold": 10485760
      }
    },
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "result": 1
      }
    }
  }
}

3.3 激活端点

默认情况下，只有少数端点（如 /actuator/health 和 /actuator/info）是激活且暴露的。如果要启用其他端点，需要在 application.properties 或 application.yml 中进行配置。

management:
  endpoints:
    web:
      exposure:
        include: "*"

上述配置将暴露所有的端点。如果只想暴露特定的端点，例如 health 和 metrics，可以使用如下配置：

management:
  endpoints:
    web:
      exposure:
        include: health,metrics

4. 常用配置

Actuator 提供了很多可以自定义的配置选项，以下是一些常见的配置：

4.1 更改端点的基础路径

默认情况下，所有的 Actuator 端点都暴露在 /actuator 路径下。你可以通过配置自定义路径：

management:
  endpoints:
    web:
      base-path: /manage

这样所有的 Actuator 端点将暴露在 /manage 下，比如健康检查端点将变为 /manage/health。

4.2 安全性配置

如果你不希望所有用户都能访问 Actuator 端点，可以通过 Spring Security 对其进行保护。例如，以下配置要求访问 Actuator 端点时必须经过身份验证：

management:
  endpoint:
    health:
      show-details: when_authorized
  security:
    roles: ACTUATOR

你可以结合 Spring Security 实现基于角色的访问控制。

4.3 自定义健康检查

Actuator 允许你通过实现 HealthIndicator 接口来自定义健康检查逻辑：

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class CustomHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check(); // 执行一些自定义检查
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        // 你的健康检查逻辑
        return 0;
    }
}

这样，你的自定义健康检查逻辑将会被集成到 /actuator/health 端点中。

4.4 日志管理

Actuator 提供了日志管理功能，允许你动态调整日志级别：

• /actuator/loggers：查看应用程序中所有的日志记录器和它们的级别。
• /actuator/loggers/{logger.name}：查看或修改某个特定日志记录器的日志级别。

通过 POST 请求可以动态修改日志级别。例如，以下请求将某个日志记录器的日志级别设为 DEBUG：

curl -X POST -d '{"configuredLevel":"DEBUG"}' \
     -H "Content-Type: application/json" \
     http://localhost:8080/actuator/loggers/com.example.MyClass

5. 示例代码

5.1 完整示例

接下来是一个集成 Actuator 的简单 Spring Boot 项目：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class ActuatorDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(ActuatorDemoApplication.class, args);
    }
}

@RestController
class MyController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

application.yml 文件：

spring:
  application:
    name: actuator-demo

management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: always
  metrics:
    export:
      simple:
        enabled: true
  health:
    diskspace:
      enabled: true
      path: /
      threshold: 10MB

运行应用程序后，你可以访问以下 Actuator 端点：

• /actuator/health：查看应用的健康状态。
• /actuator/metrics：查看应用的性能指标。
• /actuator/env：查看应用的环境配置。

性能指标

访问 /actuator/metrics，你将看到类似以下输出，其中列出了所有可用的指标名称：

{
  "names": [
    "jvm.memory.used",
    "jvm.memory.max",
    "jvm.threads.live",
    "system.cpu.usage",
    "http.server.requests",
    ...
  ]
}

选择你想要查看的某个指标名称，例如 jvm.memory.used，然后在浏览器中或通过命令行请求具体的指标：

• 浏览器中访问：/actuator/metrics/jvm.memory.used
• 或使用 curl 命令：

curl http://localhost:8080/actuator/metrics/jvm.memory.used

你将看到具体的值，例如：

{
  "name": "jvm.memory.used",
  "description": "The amount of used memory",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 123456789
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": ["heap", "nonheap"]
    },
    {
      "tag": "id",
      "values": ["PS Eden Space", "PS Old Gen", "PS Survivor Space"]
    }
  ]
}

在这个例子中：

• "value": 123456789 表示当前 JVM 已用内存为 123456789 字节。
• "availableTags" 表示可以进一步按内存区域（堆或非堆）或内存池细分数据。

如果你想要过滤或获取特定区域的数据，可以通过指定标签来获取。例如，查询堆内存的使用情况：

curl http://localhost:8080/actuator/metrics/jvm.memory.used?tag=area:heap

这样，你就可以查看指标的具体值，而不仅仅是名称了。

常见指标：

• jvm.memory.used：JVM 使用的内存。
• system.cpu.usage：系统的 CPU 使用率。
• http.server.requests：HTTP 请求的统计信息。

你可以根据你的应用需要获取不同的性能指标，并结合 Prometheus 或 Grafana 进行监控与展示。

6. Actuator 常用端点列表

7. 结论

Spring Boot Actuator 是一个功能强大的监控和管理工具，它为开发者提供了丰富的监控端点，可以帮助你快速掌握应用程序的运行状态和性能指标。通过 Actuator，你可以轻松地对应用程序进行监控、调试，并在必要时执行管理任务。结合自定义健康检查、日志管理和安全控制，Actuator 提供了极大的灵活性和可扩展性，是企业级 Spring Boot 应用中不可或缺的部分。