【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
     1

   • 可以扩展新的监控接口， 比如自定义的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等组件等。

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

management.health.redis.enabled: false
1

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

引入POM依赖

<dependency>
    <groupId>io.projectreactorgroupId>
    <artifactId>reactor-coreartifactId>
dependency>
1
2
3
4

自定义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());
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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();
	}

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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
1
2
3
4

模拟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();
       }
   }
   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12

   访问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();
       }
   
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12

   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;
         }
     
     }
     
     1
     2
     3
     4
     5
     6
     7
     8
     9
     10
     11
     12
     13
     14

   • 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();
         }
     
     
     }
     1
     2
     3
     4
     5
     6
     7
     8
     9
     10
     11
     12
     13
     14
     15

   • 访问自定义监控节点
     

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

5. 小结

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