【Spring Boot 集成应用】Actuator监控功能使用

1. Spring Boot Actuator说明

Spring Boot Actuator 是Spring Boot官方提供的应用系统的监控组件，可以查看应用的详细配置信息，例如自动化配置信息、Spring beans 容器、jvm信息以及环境属性等。

在生产环境中使用， 要保证 actuator 暴露的监控接口的安全性， 需要添加安全控制的依赖spring-boot-start-security依赖， 访问监控信息时， 都需输入验证信息，在开发测试过程中， 可以选择不加。

2. Spring Boot Actuator监控功能

Actuator监控分为两类， 原生预置接口与自定义接口。

1. 原生预置接口

   原生接口提供了较多的REST接口， 主要分为三类：

   • 配置类： 可以查看应用程序运行期间的配置信息， 例如自动化配置， 加载的 springbean 信息、yml 文件配置信息等。
   • 度量类： 查看应用程序运行期间的动态信息，比如堆栈使用变化情况， 请求连接情况，metrics 信息等
   • 操控类： 控制应用程序的操作接口， 比如shutdown， 能够主动将Spring Boot应用程序关闭， 这是正确的关闭方式， 能够避免强制终止导致的缓存与数据问题。

2. 自定义接口

   • 可以将原生内置接口进行修改， 比如将原接口的health 改成 apphealth

     endpoints.health.id=apphealth
     

   • 可以扩展新的监控接口， 比如自定义的Metrics采集信息， 自定义健康指示器， 自定义endpoints端点等。

3. 原生预置接口详细列表

   Method	路径	描述
   GET	/auditevents	显示应用暴露的审计事件 (比如认证进入、鉴权失败等)
   GET	/beans	描述应用程序上下文里全部的 Bean，以及它们的关系
   GET	/conditions	就是 1.X 的 /autoconfig ，提供一份自动配置生效的条件情况，记录哪些自动配置条件通过了，哪些没通过
   GET	/configprops	描述配置属性(包含默认值)如何注入Bean
   GET	/env	获取全部环境属性
   GET	/env/{name}	根据名称获取特定的环境属性值
   GET	/flyway	提供一份 Flyway 数据库迁移信息
   GET	/liquidbase	显示Liquibase 数据库迁移的纤细信息
   GET	/health	报告应用程序的健康指标，这些值由 HealthIndicator 的实现类提供
   GET	/heapdump	dump 一份应用的 JVM 堆信息
   GET	/httptrace	显示HTTP足迹，最近100个HTTP request/repsponse
   GET	/info	获取应用程序的定制信息，这些信息由info打头的属性提供
   GET	/logfile	返回log file中的内容(如果 logging.file 或者 logging.path 被设置)
   GET	/loggers	显示和修改配置的loggers
   GET	/metrics	报告各种应用程序度量信息，比如内存用量和HTTP请求计数
   GET	/metrics/{name}	报告指定名称的应用程序度量值
   GET	/scheduledtasks	展示应用中的定时任务信息
   GET	/sessions	如果我们使用了 Spring Session 展示应用中的 HTTP sessions 信息
   POST	/shutdown	关闭应用程序，要求endpoints.shutdown.enabled设置为true
   GET	/mappings	描述全部的 URI路径，以及它们和控制器(包含Actuator端点)的映射关系
   GET	/threaddump	获取线程活动的快照

3. Spring Boot Actuator常用监控节点分析

3.1. health

health 主要用来检查应用的运行状态，这是我们使用最高频的一个监控点。通常使用此接口提醒我们应用实例的运行状态，以及应用不”健康“的原因，比如磁盘空间不足等。

默认情况下，最终的 Spring Boot 应用的状态是由 HealthAggregator 汇总而成， 流程：

• 1 设置状态码顺序：setStatusOrder(Status.DOWN, Status.OUT_OF_SERVICE, Status.UP, Status.UNKNOWN);。

• 2 过滤掉不能识别的状态码。

• 3 如果无任何状态码，整个 Spring Boot 应用的状态是 UNKNOWN。

• 4 将所有收集到的状态码按照 1 中的顺序排序。

• 5 返回有序状态码序列中的第一个状态码，作为整个 Spring Boot 应用的状态。

health端点有很多自动配置的健康指示器：如redis、rabbitmq等组件等。

名称	描述
CassandraHealthIndicator	检查 Cassandra 数据库是否启动。
DiskSpaceHealthIndicator	检查磁盘空间不足。
DataSourceHealthIndicator	检查是否可以获得连接 DataSource。
ElasticsearchHealthIndicator	检查 Elasticsearch 集群是否启动。
InfluxDbHealthIndicator	检查 InfluxDB 服务器是否启动。
JmsHealthIndicator	检查 JMS 代理是否启动。
MailHealthIndicator	检查邮件服务器是否启动。
MongoHealthIndicator	检查 Mongo 数据库是否启动。
Neo4jHealthIndicator	检查 Neo4j 服务器是否启动。
RabbitHealthIndicator	检查 Rabbit 服务器是否启动。
RedisHealthIndicator	检查 Redis 服务器是否启动。
SolrHealthIndicator	检查 Solr 服务器是否已启动。

可以通过配置，禁用某个组件的健康监测：

management.health.redis.enabled: false

对于被动式应用程序， 比如Spring WebFlux， 也可通过ReactiveHealthIndicator响应式接口作为健康检查：

引入POM依赖

<dependency>
    <groupId>io.projectreactor</groupId>
    <artifactId>reactor-core</artifactId>
</dependency>

自定义reactive:

@Component
public class DownstreamServiceHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return checkDownstreamServiceHealth().onErrorResume(
                ex -> Mono.just(new Health.Builder().down(ex).build())
        );
    }

    private Mono<Health> checkDownstreamServiceHealth() {
        // we could use WebClient to check health reactively
        return Mono.just(new Health.Builder().up().build());
    }
}

Mongo的响应式健康检查， MongoReactiveHealthIndicator：

public class MongoReactiveHealthIndicator extends AbstractReactiveHealthIndicator {

	private final ReactiveMongoTemplate reactiveMongoTemplate;

	public MongoReactiveHealthIndicator(ReactiveMongoTemplate reactiveMongoTemplate) {
		Assert.notNull(reactiveMongoTemplate, "ReactiveMongoTemplate must not be null");
		this.reactiveMongoTemplate = reactiveMongoTemplate;
	}

	@Override
	protected Mono<Health> doHealthCheck(Health.Builder builder) {
		Mono<Document> buildInfo = this.reactiveMongoTemplate.executeCommand("{ buildInfo: 1 }");
		return buildInfo.map((document) -> up(builder, document));
	}

	private Health up(Health.Builder builder, Document document) {
		return builder.up().withDetail("version", document.getString("version")).build();
	}

}

3.2. beans

主要显示 bean 的别名、类型、是否单例、类的地址、依赖等信息。返回信息如下：

3.3. metrics

显示应用程序监控的度量指标信息， 比如系统信息、JVM内存信息、tomcat容器信息等。

根据度量名称， 可以访问具体值与描述信息，比如 /actuator/metrics/jvm.memory.max

3.4. conditions

​ 主要显示Spring Boot应用的自动化配置信息与生效条件， 能够帮助我们分析哪些自动化配置生效， 哪些是没有生效并列出具体原因。展示详情：

3.5. heapdump

​ 通过访问此节点， 能够下载返回Jvm的内存dump信息。通过MAT工具或者JDK自带的jvisualvm， 可以打开进行分析。

3.6. threaddump

​ 能够生成应用程序的线程活动快照， 主要显示线程ID、名称、状态、等待阻塞情况以及锁信息等。

3.7. mappings

​ 显示Spring Boot应用的全部URI路径，请求配置信息， 映射关系， 以及具体的类与方法。

3.8. shutdown

​ 能够优雅的关闭Spring Boot 应用， 不同于系统Kill的强杀方式， 通过此方式关闭， 内部程序能够接收关闭事件， 从而能够处理些销毁信息，比如对象销毁， 线程池回收， IO释放等， 保障程序的正常终止。

此接口必须谨慎操作， 使用前须先通过配置开启此功能：

management:
  endpoint:
    shutdown:
      enabled: true

模拟Post请求访问， 返回"Shutting down, bye…" ，程序正常结束。

4. 自定义Actuator

4.1 修改预置监控节点

1. 通过HealthIndicator接口实现

   @Component
   public class CustomHealthIndicator implements HealthIndicator {
   
       @Override
       public Health health() {
           Runtime.getRuntime().gc();
           long freeMemory =Runtime.getRuntime().freeMemory();
           return Health.up().withDetail("code", 200)
                   .withDetail("freeMemory", freeMemory).up().build();
       }
   }
   
   

   访问health, 可以看到我们新加入的空闲内存信息：
   

2. 通过AbstractHealthIndicator抽象类实现

   @Component
   public class CustomAbstractHealthIndicator extends AbstractHealthIndicator {
   
       @Override
       protected void doHealthCheck(Health.Builder builder) throws Exception {
           Runtime.getRuntime().gc();
           long freeMemory =Runtime.getRuntime().freeMemory();
           builder.withDetail("code", 201)
                   .withDetail("freeMemory", freeMemory).up().build();
       }
   
   }
   

   AbstractHealthIndicator功能更为丰富，内部作了一些封装， 内置的DataSourceHealthIndicator 、 RedisHealthIndicator都采用这种写法。
   

   访问health， 都能够正常显示自定义信息。

4.2 自定义监控节点

1. 自定义监控节点注解介绍

   要实现自定义监控节点， 需要用到Spring Boot 提供的相关注解：

   • @Endpoint 构建 rest api 的唯一路径
   • @ReadOperation GET请求，响应状态为 200 如果没有返回值响应 404（资源未找到）
   • @WriteOperation POST请求，响应状态为 200 如果没有返回值响应 204（无响应内容）
   • @DeleteOperation DELETE请求，响应状态为 200 如果没有返回值响应 204（无响应内容）

2. 代码实现

   • CustomSystemEndPoint类

     定义一个内存监控节点，显示内存信息， 支持Get请求：

     @Endpoint(id = "memory")
     public class CustomSystemEndPoint {
     
         @ReadOperation
         public Map<String, Long> memory() {
             Map<String, Long> result = new HashMap<>();
             result.put("totalMemory", Runtime.getRuntime().totalMemory());
             result.put("freeMemory", Runtime.getRuntime().freeMemory());
             result.put("maxMemory", Runtime.getRuntime().maxMemory());
             return result;
         }
     
     }
     
     

   • ActuatorApplication

     必须将节点声明为Bean， 纳入容器管理才能生效：

     @SpringBootApplication
     @Configuration
     public class ActuatorApplication {
     
         public static void main(String[] args) {
             SpringApplication.run(ActuatorApplication.class, args);
         }
     
         @Bean
         public CustomSystemEndPoint customSystemEndPoint() {
             return new CustomSystemEndPoint();
         }
     
     
     }
     

   • 访问自定义监控节点
     

     能够正常显示自定义的信息。

5. 小结

这里介绍了Spring Boot Actuator监控功能， 包含常用的内置监控节点，更多信息可参考官方源码及文档。通过实践案例， 全面掌握自定义Actuator的用法， 在实际项目中根据需要， 扩展自定义监控节点或改进内置监控节点。