Spring Boot Actuator - 应用监控与管理

一、 Spring Boot Actuator 概述

Spring Boot Actuator是Spring Boot 提供的生产级监控与管理工具集，用于实时监控和运维管理应用。Actuator 通过HTTP 端点（或 JMX 端点）暴露应用的健康状态、性能指标、日志信息、环境配置等关键数据，使开发者和运维人员能够高效地监测应用状态、优化性能、排查问题，尤其适用于生产环境。

核心功能：

1.健康检查（Health Checks）

• 提供应用的运行健康状态，可监控数据库、缓存、消息队列等依赖服务，通常用于服务可用性探测（如 Kubernetes 健康检查）。

• 通过/actuator/health端点访问，返回UP（正常）或 DOWN（异常），支持自定义健康检查。

2.度量指标（Metrics）

• 提供应用的性能指标，包括JVM 内存使用、GC 状态、线程数、数据库连接池状态等。

• 通过/actuator/metrics端点访问，可与Prometheus、Grafana、Micrometer结合，实现完整的应用监控方案。

3.日志管理（Logging）

• 通过/actuator/loggers端点，支持实时调整日志级别，避免生产环境修改配置后必须重启应用的麻烦。

• /actuator/logfile端点可直接查看应用日志文件（需额外配置logging.file.name或logging.file.path）。

4.环境信息（Environment Info）

• 通过/actuator/env端点，查看应用当前的环境变量、配置属性、系统参数等，方便排查配置问题。

• /actuator/configprops端点可查看所有@ConfigurationProperties 配置项，直观了解 Spring Boot 自动配置细节。

二、集成 Spring Boot Actuator

Spring Boot Actuator 提供了一套开箱即用的监控和管理工具，集成非常简单，只需添加依赖、启用端点并配置访问权限即可。

步骤1：Maven 依赖配置

在pom.xml文件中引入 Spring Boot Actuator 依赖。

<dependencies><!-- Spring Boot Actuator --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>
</dependencies>

添加依赖后，Actuator 的部分端点会默认启用，无需额外代码即可使用。

步骤2：启用 Actuator 端点

Actuator 端点分为默认启用端点和需手动启用端点。

默认启用的端点：

• /actuator/health：应用健康状况

• /actuator/info：应用基本信息

非默认启用端点：

以下端点默认可用但未暴露，需要手动启用：

• /actuator/metrics：应用性能指标（JVM 内存、GC、请求数等）

• /actuator/env：应用环境变量、系统属性

• /actuator/logfile：访问日志文件（需额外配置日志路径）

• /actuator/heapdump：下载 JVM 堆转储文件

• /actuator/threads：查看线程信息

• /actuator/configprops：查看@ConfigurationProperties配置项

• /actuator/caches：查看缓存状态

• /actuator/beans：列出 Spring Beans

• /actuator/auditevents：Spring Security 审计事件

启用非默认端点

在application.properties或application.yml中配置。

在 application.properties 中：

# 启用指定端点
management.endpoints.web.exposure.include=metrics,logfile
# 启用所有端点
management.endpoints.web.exposure.include=*
在 application.yml 中：management:endpoints:web:exposure:include: env,metrics

配置日志路径（适用于 /logfile 端点）

/logfile端点显示暴露后，还需在application.properties配置日志文件路径：

management.endpoint.logfile.external-file=/var/log/myapp.log

步骤3：访问Actuator端点

1.访问健康检查端点（Health Check）：

http://localhost:8080/actuator/health

响应示例：

{"status": "UP"
}

• UP表示应用正常运行。

• DOWN表示应用不健康。

• OUT_OF_SERVICE表示应用正在停止。

2.访问度量指标端点（Metrics）：

http://localhost:8080/actuator/metrics

响应示例：

{"names": ["jvm.memory.used","jvm.gc.pause","http.server.requests"]
}

访问特定指标，查看具体数值：

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

返回的内容：

{"name": "jvm.memory.used","measurements": [{"statistic": "VALUE","value": 12345678}],"availableTags": [{"tag": "area","values": ["heap", "non-heap"]}]
}

3.访问信息端点（Info）：

http://localhost:8080/actuator/info

响应示例：

{"app": {"name": "MyApp","version": "1.0.0"}
}

三、自定义 Actuator 端点

Spring Boot Actuator 提供了丰富的内置端点，但在某些情况下，需要自定义端点以满足特定的监控需求。Actuator 支持两种方式创建自定义端点：

• 实现 Endpoint 接口

• 继承 AbstractEndpoint（已在较早版本使用，现推荐 @Endpoint 注解方式）

步骤1：创建自定义端点类

简单示例：

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;@Component
@Endpoint(id = "custom")
public class CustomEndpoint {@ReadOperationpublic String customEndpoint() {return "这是自定义的 Actuator 端点";}
}

代码解析：

• @Endpoint(id = “custom”)：定义自定义端点/actuator/custom。

• @ReadOperation：指定该方法用于 GET 请求，返回端点的数据。

步骤2：配置暴露自定义端点

默认情况下，Spring Boot 仅暴露health和info端点。要使自定义端点可访问，需要在application.properties或application.yml配置：

management.endpoints.web.exposure.include=custom

或在application.yml中：

management:endpoints:web:exposure:include: custom

步骤3：访问自定义端点

应用启动后，可通过以下 URL 访问：

http://localhost:8080/actuator/custom

响应：

"这是自定义的 Actuator 端点"

四、端点扩展

在 Spring Boot Actuator 中，除了自定义端点，还可以对已有端点进行扩展，以增强其功能。在不重新创建端点的情况下，满足特定业务需求。

1. 扩展健康检查（HealthIndicator）

/actuator/health端点默认检查应用的基本健康状态。我们可以通过实现HealthIndicator接口，扩展健康检查逻辑，例如，检查应用的数据库连接、第三方服务的状态等。

代码示例：检查数据库是否正常

@Component
public class DatabaseHealthIndicator implements HealthIndicator {@Overridepublic Health health() {// 数据库连接检查boolean isDatabaseHealthy = checkDatabase();// 根据数据库健康状态返回健康状态if (isDatabaseHealthy) {return Health.up().withDetail("Database", "OK").build();} else {return Health.down().withDetail("Database", "Not reachable").build();}}// 模拟数据库连接检查的方法private boolean checkDatabase() {// 这里可以写实际的数据库连接检查逻辑// 如，通过 JDBC 或连接池检查数据库连接return true;  // 假设数据库连接正常}
}

代码解析：

• @Component: 标记DatabaseHealthIndicator为 Spring Bean，确保被 Spring 扫描并注册。

• HealthIndicator接口：自定义健康检查逻辑的基类。

• health()：检查数据库连接。正常返回UP，否则返回DOWN。

健康检查结果：

访问/actuator/health，如果数据库正常：

{"status": "UP","details": {"Database": "OK"}
}

如果数据库不可用：


{"status": "DOWN","details": {"Database": "Not reachable"}
}

2. 扩展日志管理（动态修改日志级别）

/actuator/logfile端点提供了日志内容的查看功能。Spring Boot 允许通过logback-spring.xml配置文件动态控制日志级别。

代码示例：

<configuration><!-- 控制根日志级别为INFO --><root level="INFO"><appender-ref ref="CONSOLE"/></root><!-- 定义日志级别为DEBUG --><logger name="com.example" level="DEBUG"/><!-- 控制日志输出格式 --><appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"><encoder><pattern>%d{yyyy-MM-dd HH:mm:ss} - %msg%n</pattern></encoder></appender>
</configuration>

代码解析：

•  <root level="INFO">： 设置根日志级别为INFO，即显示INFO及更高级别的日志（如WARN,ERROR）。•  <logger name="com.example" level="DEBUG"/>： 为特定包（com.example）设置DEBUG级别日志，使得它显示更多细节。•  <appender>： 定义日志输出方式（例如，输出到控制台）。

动态修改日志级别：

通过/actuator/loggers端点动态修改日志级别，例如：

1.查看当前日志级别：

GET /actuator/loggers/com.example

2.动态修改日志级别：

POST /actuator/loggers/com.example
Content-Type: application/json
{"configuredLevel": "DEBUG"
}

修改后，日志系统会立即生效，而无需重启应用。

3. 扩展度量指标（Metrics）

使用MeterRegistry注册自定义指标，例如，添加自定义计数器：

@Component
public class CustomMetrics {private final MeterRegistry meterRegistry;public CustomMetrics(MeterRegistry meterRegistry) {this.meterRegistry = meterRegistry;}@PostConstructpublic void init() {Counter counter = meterRegistry.counter("custom.counter");counter.increment();  // 每次调用时递增}
}

访问/actuator/metrics可查看custom.counter指标。

4. 其他常见端点扩展

除了健康检查、度量指标和日志管理，Spring Boot Actuator 还支持其他端点的扩展，以提供更丰富的监控和管理能力，例如：

• 环境配置（Environment）

通过扩展/actuator/env端点，可以暴露更多的环境变量或系统属性，以便在运行时查看和调试应用配置。

• 审计事件（Audit Events）

通过扩展/actuator/auditevents端点，可以自定义审计事件的记录和查询，例如用户登录、权限变更等关键事件的追踪。

• 配置属性（Config Props）

通过扩展/actuator/configprops端点，可以暴露更多的应用配置属性，以便分析 Spring Boot 自动配置的内容，帮助开发者更好地理解应用的运行状态。

总结

• 自定义端点：使用@Endpoint创建新端点，如/actuator/custom。

• 端点扩展：

• 健康检查：使用HealthIndicator扩展/actuator/health。

• 日志管理：通过/actuator/loggers端点动态调整日志级别。

• 度量指标：使用MeterRegistry添加自定义指标。

五、端点安全管理

为了确保 Spring Boot Actuator 端点的访问安全，推荐使用 Spring Security 配置权限控制。以防止未授权的访问，保护敏感数据。以下是配置端点安全的基本步骤：

步骤1：引入 Spring Security 依赖

在pom.xml文件中添加 Spring Security 依赖：

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

步骤2：配置安全策略

使用@EnableWebSecurity注解和WebSecurityConfigurerAdapter配置 Actuator 端点的访问权限，例如：

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/actuator/**").hasRole("ADMIN") // 仅允许 ADMIN 角色访问.anyRequest().authenticated() // 其他请求需认证.and().httpBasic(); // 启用基本认证}
}

步骤3：配置用户名和密码

Spring Boot 默认会生成随机用户名和密码。要使用自定义凭据，可在application.properties或application.yml配置：

spring.security.user.name=admin
spring.security.user.password=secret

步骤4：精细化保护 Actuator 端点

配置哪些端点对外开放。例如：

management.endpoints.web.exposure.include=health,info  // 开放 health 和 info 端点
management.endpoints.web.exposure.exclude=metrics,env  // 排除 metrics 和 env 端点