Spring Boot Actuator 详解：让你的应用可监控、可管理、更健壮

Spring Boot Actuator 详解：让你的应用可监控、可管理、更健壮

摘要： 作为 Spring Boot 的强大监控和管理模块，Actuator 为我们提供了应用运行时的各种关键信息，例如健康状态、指标数据、日志信息等。本文将深入浅出地介绍 Spring Boot Actuator，让你了解其核心功能、配置方式和使用场景，帮助你打造更易于监控、管理和维护的健壮 Spring Boot 应用！

1. 引言：应用监控与管理的重要性

在应用开发和运维过程中，监控和管理 是至关重要的环节。 我们需要时刻了解应用的运行状态，及时发现和解决问题，确保应用的稳定性和可靠性。

没有监控和管理的应用，就像在黑暗中驾驶，充满了未知的风险。

Spring Boot Actuator 正是为了解决这个问题而生的。 它为 Spring Boot 应用提供了 开箱即用的监控和管理功能，无需额外开发，只需简单配置即可使用。

Spring Boot Actuator 的核心价值：

• 提供丰富的运行时信息： 暴露应用的健康状态、指标数据、日志信息、Bean 信息、配置信息等。
• 易于集成和配置： 只需引入依赖，少量配置即可启用，与 Spring Boot 应用无缝集成。
• 支持多种数据格式和协议： 默认支持 JSON 格式，可以通过 HTTP 或 JMX 访问端点，方便集成各种监控系统。
• 可扩展性强： 允许自定义端点、指标、健康检查等，满足更复杂的需求。

2. 快速上手：引入 Actuator 依赖

要使用 Spring Boot Actuator，只需在 pom.xml 文件中添加以下依赖：

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

引入依赖后，重启应用，Actuator 默认会暴露一些 敏感信息端点 (例如 /shutdown, /heapdump)，默认情况下这些端点是禁用的。 我们可以通过配置来启用和访问这些端点。

3. 核心概念：端点 (Endpoints)

端点 (Endpoints) 是 Actuator 的核心概念。 Actuator 通过暴露一系列预定义的 HTTP 或 JMX 端点，来提供应用的运行时信息。 每个端点都对应着一种特定的监控或管理功能。

Actuator 常用端点概览 (默认 HTTP 端点，路径前缀为 /actuator):

访问端点：

默认情况下，Actuator 端点的 HTTP 访问路径前缀为 /actuator。 例如，访问健康状态端点的 URL 为： http://localhost:8080/actuator/health。

4. 常用端点详解与配置

4.1 /health 端点：监控应用健康状态

/health 端点用于检查应用的健康状态。 默认情况下，/health 端点会返回一个简单的 UP 或 DOWN 状态。

访问 /actuator/health 端点，默认响应：

{
  "status": "UP"
}

• status: UP: 表示应用健康状态正常。
• status: DOWN: 表示应用健康状态异常。

自定义健康检查信息 (Health Indicators):

我们可以自定义 Health Indicators，提供更详细的健康检查信息。 例如，创建一个自定义的数据库健康检查器：

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

@Component("databaseHealthIndicator") // Bean 名称，用于 health 端点显示
public class DatabaseHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        boolean isDatabaseHealthy = checkDatabaseConnection(); // 自定义数据库连接检查逻辑

        if (isDatabaseHealthy) {
            return Health.up().withDetail("message", "Database connection is OK").build(); // 健康状态 UP，并添加详细信息
        } else {
            return Health.down().withDetail("error", "Database connection failed").build(); // 健康状态 DOWN，并添加错误信息
        }
    }

    private boolean checkDatabaseConnection() {
        // TODO:  实现数据库连接检查逻辑，例如尝试连接数据库，执行简单的查询等
        // 这里只是一个示例，实际情况需要根据你的数据库连接方式和配置进行实现
        return true; // 示例：假设数据库连接总是健康的
    }
}

重启应用，再次访问 /actuator/health 端点，响应会包含更详细的健康信息：

{
  "status": "UP",
  "components": {
    "databaseHealthIndicator": { // 自定义 Health Indicator 的 Bean 名称
      "status": "UP",
      "details": {
        "message": "Database connection is OK"
      }
    },
    "diskSpace": { // 默认的磁盘空间 Health Indicator
      "status": "UP",
      "details": {
        "total": 499963170816,
        "free": 358222848000,
        "threshold": 10485760
      }
    }
  }
}

4.2 /info 端点：暴露应用自定义信息

/info 端点用于暴露应用的自定义信息，例如应用版本、构建时间、团队信息等。 这些信息可以通过 application.properties 或 application.yml 文件配置。

配置 application.properties 或 application.yml：

application.properties:

info.app.name=My Spring Boot Application
info.app.version=1.0.0
info.app.description=This is a sample Spring Boot application with Actuator.
info.developer.name=Your Name
info.developer.email=your.email@example.com

application.yml:

info:
  app:
    name: My Spring Boot Application
    version: 1.0.0
    description: This is a sample Spring Boot application with Actuator.
  developer:
    name: Your Name
    email: your.email@example.com

访问 /actuator/info 端点，响应会包含配置的自定义信息：

{
  "app": {
    "name": "My Spring Boot Application",
    "version": "1.0.0",
    "description": "This is a sample Spring Boot application with Actuator."
  },
  "developer": {
    "name": "Your Name",
    "email": "your.email@example.com"
  }
}

4.3 /metrics 端点：监控应用指标数据

/metrics 端点用于暴露应用的指标数据，例如 JVM 内存使用情况、CPU 使用率、HTTP 请求处理时间、数据库连接池状态等。 这些指标数据可以用于监控应用的性能和资源消耗情况。

访问 /actuator/metrics 端点，会列出所有可用的指标名称：

{
  "names": [
    "jvm.buffer.count",
    "jvm.buffer.memory.used",
    "jvm.buffer.total.capacity",
    "jvm.classes.loaded",
    "jvm.classes.unloaded",
    "jvm.gc.live.data.size",
    "jvm.gc.max.data.size",
    "jvm.gc.memory.allocated",
    "jvm.gc.memory.promoted",
    "jvm.gc.pause",
    "jvm.memory.committed",
    "jvm.memory.max",
    "jvm.memory.used",
    "jvm.threads.daemon",
    "jvm.threads.live",
    "jvm.threads.peak",
    "logback.events",
    "process.cpu.usage",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "tomcat.sessions.active.current",
    "tomcat.sessions.active.max",
    "tomcat.sessions.created",
    "tomcat.sessions.expired",
    "tomcat.sessions.rejected"
  ]
}

访问 /actuator/metrics/{指标名称} 端点，可以获取特定指标的详细数据：

例如，访问 /actuator/metrics/jvm.memory.used 端点，获取 JVM 内存使用情况：

{
  "name": "jvm.memory.used",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 123456789 // 内存使用量，单位为字节
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": [
        "heap",
        "nonheap"
      ]
    }
  ]
}

4.4 启用更多端点，配置端点访问权限

默认情况下，Actuator 只启用了 /health 和 /info 端点，并且很多敏感信息端点是禁用的。 我们可以通过配置来启用更多端点，并配置端点的访问权限。

配置 application.properties 或 application.yml：

启用所有端点 (生产环境慎用)：

management.endpoints.web.exposure.include=*

启用指定端点 (推荐)：

management.endpoints.web.exposure.include=health,info,metrics,loggers

禁用端点：

management.endpoints.web.exposure.exclude=beans,env,configprops

配置端点访问权限 (基于 Spring Security):

需要在 Spring Security 配置类 (WebSecurityConfig) 中配置 Actuator 端点的访问权限，例如只允许 ADMIN 角色访问敏感信息端点：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            .antMatchers("/actuator/health", "/actuator/info").permitAll() // health 和 info 端点permitAll
            .antMatchers("/actuator/**").hasRole("ADMIN") // /actuator/** 开头的其他端点需要 ADMIN 角色
            .anyRequest().authenticated()
            .and()
        // ... 其他配置 ...
}

5. 集成监控系统：Prometheus, Grafana

Actuator 暴露的指标数据可以方便地集成各种监控系统，例如 Prometheus 和 Grafana。

集成 Prometheus：

1. 添加 Prometheus 客户端依赖：

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

2. 启用 /prometheus 端点：

   management.endpoints.web.exposure.include=health,info,metrics,prometheus
   

3. 配置 Prometheus 抓取 Actuator 端点：

   在 prometheus.yml 配置文件中添加如下配置：

   scrape_configs:
     - job_name: 'spring-boot-actuator'
       metrics_path: '/actuator/prometheus'
       scrape_interval: 15s
       static_configs:
         - targets: ['localhost:8080'] # 应用的地址和端口
   

启动 Prometheus，即可开始抓取 Actuator 暴露的指标数据。

集成 Grafana：

在 Grafana 中添加 Prometheus 数据源，并创建 Dashboard，即可可视化 Actuator 暴露的指标数据。 Grafana 社区有很多现成的 Spring Boot Actuator Dashboard 模板可以直接使用。

6. 自定义 Actuator 功能：扩展端点、指标、健康检查

Actuator 提供了强大的扩展机制，允许我们自定义端点、指标、健康检查，满足更复杂的需求。

自定义端点 (Endpoint Extension):

可以创建自定义的 Endpoint 类，并使用 @Endpoint, @ReadOperation, @WriteOperation, @DeleteOperation 等注解定义端点的操作方法。

自定义指标 (MeterRegistry Customization):

可以通过 MeterRegistryCustomizer 自定义指标注册器，添加额外的指标标签、全局标签等。

自定义健康检查 (HealthContributor):

除了 HealthIndicator 之外，Actuator 还提供了 HealthContributor 接口，用于更灵活地组织和扩展健康检查信息。

具体扩展细节可以参考 Spring Boot Actuator 官方文档。

7. 总结：Spring Boot Actuator，应用监控管理的利器

Spring Boot Actuator 提供了强大的应用监控和管理功能，帮助我们轻松获取应用的运行时信息，及时发现和解决问题，保障应用的稳定性和可靠性。 掌握 Actuator 的使用，是打造健壮 Spring Boot 应用的关键一步。

下一步学习建议：

• 深入学习 Spring Boot Actuator 官方文档： 官方文档是学习 Actuator 最权威的资料。
• 实践更多 Actuator 端点： 例如 /loggers, /threaddump, /beans 等。
• 探索 Actuator 的扩展机制： 自定义端点、指标、健康检查。
• 集成更多监控系统： 例如 Micrometer, JMX, 日志监控等。

希望这篇文章对您有所帮助！ 如果您在实践中遇到任何问题，欢迎在评论区交流。