Spring Boot 监控模块 Actuator，让你实时了解项目的运行状态和性能瓶颈

「爱情、让人受尽委屈。」 2023-10-12 15:38 6阅读 0赞

Spring Boot Actuator 是 Spring Boot 自带的一个功能模块，提供了一组已经开箱即用的生产环境下常用的特性和服务，比如应用程序的健康检查、信息暴露、度量收集、日志记录等。在实际项目中，Actuator 可以帮助我们快速了解应用程序的运行状态和性能瓶颈。

### 1. Actuator 的入门及配置 ###

#### 1.1 安装和使用 Actuator ####

我们可以通过 Maven 或 Gradle 将 Actuator 添加到我们的 Spring Boot 应用程序中。Maven 的依赖如下：

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

Gradle 的依赖如下：

implementation 'org.springframework.boot:spring-boot-starter-actuator'

添加依赖后，我们只需要启动我们的应用程序即可开始使用 Actuator。默认情况下，Actuator 会向应用程序暴露以下 URI：

*  `/actuator/auditevents`：显示当前配置的审核事件信息
 *  `/actuator/beans`：显示应用程序中所有 Bean 的完整名称列表
 *  `/actuator/conditions`：显示自动配置类及其应用情况的信息
 *  `/actuator/configprops`：显示所有 Spring Boot 配置文件及其对应值的详细信息
 *  `/actuator/env`：显示应用程序当前环境变量和属性的详细信息
 *  `/actuator/flyway`：显示 Flyway 数据库迁移信息的详细信息
 *  `/actuator/health`：显示应用程序的健康状况
 *  `/actuator/info`：显示应用程序相关信息
 *  `/actuator/mappings`：显示 Spring MVC 控制器映射的详细信息
 *  `/actuator/metrics`：显示各种 JVM 指标、计数器和度量数据的详细信息
 *  `/actuator/prometheus`：将指标暴露为 Prometheus 格式，以便在 Grafana 或其他监控系统中使用
 *  `/actuator/scheduledtasks`：显示应用程序中所有调度任务的详细信息
 *  `/actuator/sessions`：允许查看和失效会话 ID
 *  `/actuator/shutdown`：关闭应用程序（需要加入 actuator/shutdown 配置）

#### 1.2 Actuator 的基本配置 ####

Actuator 默认是开启的，并暴露所有端点，我们甚至可以在浏览器中直接访问上面提到的 URI。但是，在生产环境中，我们通常不希望所有端点都对外暴露。这时，我们需要对 Actuator 进行一些配置。

在 `application.properties` 或 `application.yml` 文件中添加如下配置：

# 关闭具体某个端点，格式为management.endpoint.<id>.enabled=false
    management.endpoint.shutdown.enabled=true
    
    # 开启所有端点的基础功能，格式为management.endpoints.<id>.<option-name>
    management.endpoints.web.exposure.include=*

上述配置将关闭 shutdown 端点，并开放所有端点。除了以上参量，还可以通过 `management.server.port` 配置 Actuator 的 HTTP 端口和 `management.server.ssl` 配置 SSL。

### 2. Actuator 的端点 ###

Actuator 中各个端点描述如下：

#### 2.1 /actuator/health ####

该端点提供有关应用程序健康状况的详细信息。通过检查数据库、缓存、消息代理等检查资源的状态，Health Indicators 能够确定应用程序是否正常运行。默认情况下，该端点显示以下信息：

{
        
        "status": "UP"
    }

如果应用程序是正常运行的，它会返回 UP，否则将返回 DOWN，并向用户提供有关错误的详细信息。

#### 2.2 /actuator/info ####

该端点展示与应用程序相关的任何附加信息。如：版本，构建时间等。在应用程序访问时，返回一个自定义 JSON 格式的响应。可以通过在 `application.yml` 或 `application.properties` 文件中添加键值对来定制信息。

例如：

info.app.name=My Application
    info.app.description=A demo application
    info.app.version=1.0.0

访问该端点，将返回如下响应：

{
        
        "app": {
        
            "description": "A demo application",
            "name": "My Application",
            "version": "1.0.0"
        }
    }

#### 2.3 /actuator/metrics ####

该端点提供了可以收集和监控的度量指标的详细信息。Spring Boot 提供了一些默认的度量指标，如系统 CPU 使用率、内存使用情况、HTTP 请求延迟等。此外，Spring Boot 还支持使用 Micrometer 框架创建自定义的度量指标。

在 `/actuator/metrics` 端点下，有许多子路径，每个子路径中包含一些度量项。例如，我们可以查看 Tomcat 正在监听的连接数和活动线程数等：

{
        
        "connections": {
        
            "active": 13,
            "max": 1000,
            "total": 29
        },
        "threads": {
        
            "daemon": 7,
            "total": 22
        }
    }

#### 2.4 /actuator/beans ####

该端点提供了应用程序所有 Bean 的完整列表，包括它们的相关信息。需要注意的是，Actuator 只显示由 Spring IOC 容器管理的 Bean 信息。

#### 2.5 /actuator/env ####

该端点展示应用程序当前环境变量和属性的详细信息。可以使用 `/actuator/env/<key>` 端点获取指定 key 的值，也可以通过 POST 请求，修改或添加属性。

#### 2.6 /actuator/mappings ####

该端点提供了所有 Spring MVC 控制器映射的详细信息，包括请求 URL、处理器方法、HTTP 方法等等，并按照优先级递减的顺序进行排序。例如，如下代码：

@RestController
    @RequestMapping("/hello")
    public class HelloController {
        
    
        @GetMapping("/world")
        public String greeting() {
        
            return "Hello, world!";
        }
    }

访问 `/actuator/mappings` ，将返回：

{
        
        "contexts": {
        
            "application": {
        
                "mappings": {
        
                    "dispatcherServlets": {
        
                        "dispatcherServlet": {
        
                            "mvcHandlerMappings": {
        
                                "/hello": {
        
                                    "methods": [],
                                    "params": {
        },
                                    "headers": {
        },
                                    "consumes": [],
                                    "produces": [],
                                    "custom": {
        }
                                },
                                "/hello/world": {
        
                                    "bean": "helloController",
                                    "method": "greeting",
                                    "beanType": "com.example.demo.HelloController",
                                    "args": [],
                                    "responseDetails": {
        
                                        "status": 200,
                                        "headers": {
        },
                                        "content": {
        
                                            "id": "1",
                                            "name": "Tom"
                                        }
                                    },
                                    "methods": [
                                        "GET"
                                    ],
                                    "params": {
        },
                                    "headers": {
        },
                                    "consumes": [],
                                    "produces": [],
                                    "custom": {
        }
                                },
                                ...
                            }
                        }
                    }
                }
            }
        }
    }

#### 2.7 /actuator/auditevents ####

该端点提供了所有 Spring Boot 应用程序所执行的审核事件的详细信息，包括事件名称、类型、时间戳和调用者等。此外，还支持通过 Spring Security 的安全审核事件等。

#### 2.8 /actuator/flyway ####

该端点展示 Flyway 数据库迁移信息的详细信息，包括已应用迁移的版本和状态等。

#### 2.9 /actuator/scheduledtasks ####

该端点展示应用程序中所有调度任务的详细信息。

#### 2.10 /actuator/sessions ####

该端点允许查看和失效会话 ID。

### 3. 自定义 Actuator 端点 ###

除了使用 Actuator 默认端点之外，我们还可以根据自己的业务需求自定义 Actuator 端点。

#### 3.1 编写自定义 Endpoints ####

自定义 Actuator 端点需要实现 `Endpoint` 接口，并重写 `getId()` 和 `invoke()` 方法。例如，以下代码实现了一个名为 `MyEndpoint` 的自定义端点：

@Component
    public class MyEndpoint implements Endpoint<Map<String, Object>> {
        
    
        @Override
        public String getId() {
        
            return "my-endpoint";
        }
    
        @Override
        public Map<String, Object> invoke() {
        
            Map<String, Object> result = new HashMap<>();
            result.put("name", "My name is Actuator");
            return result;
        }
    }

#### 3.2 暴露自定义 Endpoints ####

实现自定义 Endpoints 后，我们需要通过设置来公开它们。在 `application.yml` 中添加以下内容：

management:
      endpoints:
        web:
          exposure:
            include: my-endpoint

这将允许我们通过访问 `/actuator/my-endpoint` 端点来查看自定义的端点信息。

### 4. Actuator 的监控和管理功能 ###

#### 4.1 配置度量指标 ####

Actuator 提供了很多度量指标，但默认只包含一些 JVM 层面的指标。如果我们需要检测自己应用程序的度量指标，那么可以使用 `Micrometer` 库来帮助我们完成。它是一个跨度量系统和时间序列数据库的工具库，支持多种后端存储如 Prometheus、Graphite 和 InfluxDB。使用 Micrometer，我们可以在 Actuator 中创建自定义度量指标：

import io.micrometer.core.instrument.Counter;
    import io.micrometer.core.instrument.MeterRegistry;
    import org.springframework.stereotype.Component;
    
    @Component
    public class CustomMetrics {
        
    
        private final MeterRegistry meterRegistry;
        private final Counter requestsCounter;
    
        public CustomMetrics(MeterRegistry meterRegistry) {
        
            this.meterRegistry = meterRegistry;
            this.requestsCounter = Counter.builder("custom_requests_counter")
                    .description("A counter for counting custom requests.")
                    .register(meterRegistry);
        }
    
        public void incrementRequests() {
        
            requestsCounter.increment();
        }
    }

在上述代码中，我们创建了一个名为 `CustomMetrics` 的类，它是一个 Spring bean，并使用 `MeterRegistry` 注册了一个名为 `custom_requests_counter` 的度量计数器。此外，还定义了一个 `incrementRequests()` 方法，以便我们可以在代码中增加请求计数器。我们还可以添加其他类型的指标，如 `Gauge`、`Timer` 和 `DistributionSummary`。

#### 4.2 监控和管理应用程序 ####

Actuator 还提供了一些有用的监控和管理功能，让我们可以更方便地跟踪和管理应用程序。

##### 4.2.1 健康检查 #####

Actuator 的 `/actuator/health` 端点提供了应用程序的健康状况，我们可以通过检查该端点来确定应用程序是否正常运行。如果应用程序出现故障，该端点将显示 DOWN 状态，并提供有关错误的详细信息。

##### 4.2.2 角色和权限 #####

Actuator 支持基于角色的访问控制，可以限制某些用户或组的访问。可以通过设置 `management.endpoint.<id>.roles` 属性配置端点的角色。例如，以下代码将 `/actuator/shutdown` 端点限制为 ADMIN 角色：

management.endpoint.shutdown.roles=ADMIN

##### 4.2.3 外部配置 #####

Actuator 可以通过外部配置文件进行配置。可以在外部配置文件中设置以下键来控制 Actuator 的行为：

*  `management.endpoints.enabled-by-default`：是否启用所有端点（默认为 true）
 *  `management.endpoints.jmx.exposure.exclude`：要排除的端点 JMX MBean 名称
 *  `management.endpoint.<id>.enabled`：指定是否启用特定端点
 *  `management.endpoint.<id>.sensitive`：指定特定端点是否包含敏感信息

##### 4.2.4 采样周期 #####

Actuator 还支持将某些端点的采样周期设置为非默认值，以在一定时间间隔内定期轮询信息。可以通过 `management.endpoint.<id>.time-to-live` 属性配置采样周期。例如，以下代码将 `/actuator/metrics` 端点的采样周期设置为 30 秒：

management.endpoint.metrics.time-to-live=30s

### 5. Actuator 的安全保护 ###

在生产环境中，Actuator 的安全保护非常重要。Actuator 支持基于 Spring Security 的安全保护，可以使用 Spring Security 配置来授权 Actuator 端点的访问。

#### 5.1 添加 Spring Security 依赖 ####

要使用 Spring Security，我们需要在项目中添加以下 Maven 依赖：

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

#### 5.2 配置 Spring Security ####

完成依赖添加后，我们需要配置 Spring Security，以保护 Actuator 端点。以下是一个简单的 Spring Security 配置示例：

@Configuration
    @EnableWebSecurity
    public class ActuatorSecurityConfig extends WebSecurityConfigurerAdapter {
        
     
        @Override
        protected void configure(HttpSecurity http) throws Exception {
        
            http.authorizeRequests()
                .requestMatchers(EndpointRequest.to("health", "info")).permitAll()
                .requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole("ACTUATOR")
                .and().httpBasic();
        }
    }

在上述代码中，我们创建了一个名为 `ActuatorSecurityConfig` 的 Spring Security 配置类，并配置了 `/actuator/health` 和 `/actuator/info` 端点的公开访问权限。对于其他端点，则需要用户具有 ACTUATOR 角色才能访问。此外，还启用了 HTTP 基本身份验证，以便在调用受保护的端点时要求用户进行身份验证。

#### 5.3 添加用户和角色 ####

完成 Spring Security 配置后，我们还需要为 Actuator 添加用户和角色。可以通过在 `application.properties` 或 `application.yml` 文件中设置以下键来配置用户名、密码和角色：

spring.security.user.name=actuator
    spring.security.user.password=actuator-password
    spring.security.user.roles=ACTUATOR

在上述配置中，我们创建了一个名为 actuator、密码为 actuator-password，且拥有 ACTUATOR 角色的用户。