Spring Boot （九）： 微服务应用监控 Spring Boot Actuator 详解

1. 引言

在当前的微服务架构方式下，我们会有很多的服务部署在不同的机器上，相互是通过服务调用的方式进行交互，一个完整的业务流程中间会经过很多个微服务的处理和传递，那么，如何能知道每个服务的健康状况就显得尤为重要。

万幸的是 Spring Boot 为我们提供了监控模块 Spring Boot Actuator ，本篇文章将和大家一起探讨一些 Spring Boot Actuator 一些常见用法方便我们在日常的使用中对我们的微服务进行监控治理。

Spring Boot Actuator 帮我们实现了对程序内部运行情况监控，比如监控状况、Bean加载情况、环境变量、日志信息、线程信息等。

2. Actuator 的使用

2.1 工程依赖

使用 Spring Boot Actuator 需要加入如下依赖：

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

注意： 因 Spring Boot Actuator 会暴露我们服务的详细信息，为了保障安全性，建议添加安全控制的相关依赖 spring-boot-starter-security ，这样，在访问应用监控端点时，都需要输入验证信息。所需依赖如下：

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

2.2 工程配置

配置文件 application.yml 如下：

代码清单：spring-boot-actuator/src/main/resources/application.yml

---

server:
  port: 8080
info:
  app:
    name: spring-boot-actuator
    version: 1.0.0
spring:
  security:
    user:
      name: admin
      password: admin

现在先启动工程，打开浏览器访问：http://localhost:8080/actuator ，可以看到页面显示如下 json ：

{
  "_links":{
    "self":{
      "href":"http://localhost:8080/actuator",
      "templated":false
    },
    "health":{
      "href":"http://localhost:8080/actuator/health",
      "templated":false
    },
    "health-component-instance":{
      "href":"http://localhost:8080/actuator/health/{component}/{instance}",
      "templated":true
    },
    "health-component":{
      "href":"http://localhost:8080/actuator/health/{component}",
      "templated":true
    },
    "info":{
      "href":"http://localhost:8080/actuator/info",
      "templated":false
    }
  }
}

这些是默认支持的链接，只有：

/actuator
/actuator/health
/health/{component}/{instance}
/health/{component}
/actuator/info

我们可以在配置文件 application.yml 中增加配置来开启更多的监控信息：

management:
  endpoints:
    web:
      exposure:
        include: '*'
#      base-path: /monitor
  endpoint:
    health:
      show-details: always
    shutdown:
      enabled: true

• management.endpoints.web.exposure.include='*' 代表开启全部监控，当然也可以配置需要开启的监控，如： management.endpoints.web.exposure.include=beans,trace 。
• management.endpoint.health.show-details=always 含义是 health endpoint 是开启显示全部细节。默认情况下, /actuator/health 是公开的，并且不显示细节。
• management.endpoints.web.base-path=/monitor 代表启用单独的url地址来监控 Spring Boot 应用，默认的路径是 /actuator/* ，如果开启此配置，重启后再次访问路径就会变成 /manage/* 。
• management.endpoint.shutdown.enabled=true 启用接口关闭 Spring Boot 。

在某些业务场景下，我们的监控信息可能会需要跨越获取， Spring Boot Actuator 提供了 CORS 相关的配置，来支持跨域调用，默认情况下，CORS 支持处于禁用状态，只有在设置了 management.endpoints.web.cors.allowed-origins 属性后才能启用。以下配置允许来自 https://www.geekdigging.com 域的 GET 和 POST 调用：

management:
  endpoints:
    web:
      cors:
        allowed-origins: https://www.geekdigging.com
        allowed-methods: GET,POST

2.3 REST 接口

Spring Boot Actuator 为我们提供了非常丰富的监控接口，可以通过它们了解应用程序运行时的内部状况。同时 Actuator 支持用户自定义添加端点，用户可以根据自己的实际应用，定义一些比较关心的指标，在运行期进行监控。

HTTP 方法	路径	描述
GET	/auditevents	显示当前应用程序的审计事件信息
GET	/beans	显示一个应用中所有Spring Beans的完整列表
GET	/conditions	显示配置类和自动配置类(configuration and auto-configuration classes)的状态及它们被应用或未被应用的原因
GET	/configprops	显示一个所有@ConfigurationProperties的集合列表
GET	/env	显示来自Spring的 ConfigurableEnvironment的属性
GET	/flyway	显示数据库迁移路径，如果有的话
GET	/health	显示应用的健康信息（当使用一个未认证连接访问时显示一个简单的’status’，使用认证连接访问则显示全部信息详情）
GET	/info	显示任意的应用信息
GET	/liquibase	展示任何Liquibase数据库迁移路径，如果有的话
GET	/metrics	展示当前应用的metrics信息
GET	/mappings	显示一个所有@RequestMapping路径的集合列表
GET	/scheduledtasks	显示应用程序中的计划任务
GET	/sessions	允许从Spring会话支持的会话存储中检索和删除(retrieval and deletion)用户会话。使用Spring Session对反应性Web应用程序的支持时不可用。
POST	/shutdown	允许应用以优雅的方式关闭（默认情况下不启用）
GET	/threaddump	执行一个线程dump

如果使用web应用(Spring MVC, Spring WebFlux, 或者 Jersey)，还可以使用以下接口：

HTTP 方法	路径	描述
GET	/heapdump	返回一个GZip压缩的hprof堆dump文件
GET	/jolokia	通过HTTP暴露JMX beans（当Jolokia在类路径上时，WebFlux不可用）
GET	/logfile	返回日志文件内容（如果设置了logging.file或logging.path属性的话），支持使用HTTP Range头接收日志文件内容的部分信息
GET	/prometheus	以可以被Prometheus服务器抓取的格式显示metrics信息

3. 接口详解

3.1 /health

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

默认情况下 health 的状态是开放的，添加依赖后启动项目，访问：http://localhost:8080/actuator/health 即可看到应用的状态。

{
    "status" : "UP"
}

默认情况下，最终的 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 通过合并几个健康指数检查应用的健康情况。Spring Boot Actuator 会自动配置以下内容：

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

可以通过设置 management.health.defaults.enabled 属性来全部禁用它们。

3.2 /info

info 就是我们自己在配置文件中配置的以 info 开头的信息，如我们在示例工程中配置的：

info:
  app:
    name: spring-boot-actuator
    version: 1.0.0

启动工程，打开浏览器访问： http://localhost:8080/actuator/info ，结果如下：

{
  "app":{
    "name":"spring-boot-actuator",
    "version":"1.0.0"
  }
}

3.3 /beans

启动工程，打开浏览器访问： http://localhost:8080/actuator/beans ，部分结果如下：

{
	"contexts": {
		"application": {
			"beans": {
				"endpointCachingOperationInvokerAdvisor": {
					"aliases": [],
					"scope": "singleton",
					"type": "org.springframework.boot.actuate.endpoint.invoker.cache.CachingOperationInvokerAdvisor",
					"resource": "class path resource [org/springframework/boot/actuate/autoconfigure/endpoint/EndpointAutoConfiguration.class]",
					"dependencies": ["environment"]
				},
				"defaultServletHandlerMapping": {
					"aliases": [],
					"scope": "singleton",
					"type": "org.springframework.web.servlet.HandlerMapping",
					"resource": "class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]",
					"dependencies": []
				},
			},
			"parentId": null
		}
	}
}

从中可以看到，这个接口展现了 bean 的别名、类型、是否单例、类的地址、依赖等信息。

3.4 /conditions

启动工程，打开浏览器访问： http://localhost:8080/actuator/conditions ，部分结果如下：

{
	"contexts": {
		"application": {
			"positiveMatches": {
				"AuditAutoConfiguration#auditListener": [{
					"condition": "OnBeanCondition",
					"message": "@ConditionalOnMissingBean (types: org.springframework.boot.actuate.audit.listener.AbstractAuditListener; SearchStrategy: all) did not find any beans"
				}],
				"AuditAutoConfiguration#authenticationAuditListener": [{
					"condition": "OnClassCondition",
					"message": "@ConditionalOnClass found required class 'org.springframework.security.authentication.event.AbstractAuthenticationEvent'"
				}, {
					"condition": "OnBeanCondition",
					"message": "@ConditionalOnMissingBean (types: org.springframework.boot.actuate.security.AbstractAuthenticationAuditListener; SearchStrategy: all) did not find any beans"
				}],
			},
		}
	}
}

是用这个接口可以看出应用运行时查看代码了某个配置在什么条件下生效，或者某个自动配置为什么没有生效。

3.5 /shutdown

这个接口首先需要在配置文件中配置开启此功能：

management.endpoint.shutdown.enabled=true

配置完成后，可以使用 curl 模拟 post 请求此接口：

curl -X POST "http://localhost:8080/actuator/shutdown"

显示结果为：

{
    "message": "Shutting down, bye..."
}

注意：示例工程添加了 spring-boot-starter-security ，直接使用 post 访问此接口会响应 401 ，表示无权限访问，如需测试此接口，请暂时先关闭 spring-boot-starter-security 。

这时可以看到我们启动的示例工程已经关闭了。

3.6 /mappings

描述全部的 URI 路径，以及它们和控制器的映射关系

启动工程，打开浏览器访问： http://localhost:8080/actuator/mappings ，部分结果如下：

{
  "handler": "Actuator web endpoint 'beans'",
  "predicate": "{GET /actuator/beans, produces [application/vnd.spring-boot.actuator.v2+json || application/json]}",
  "details": {
    "handlerMethod": {
      "className": "org.springframework.boot.actuate.endpoint.web.servlet.AbstractWebMvcEndpointHandlerMapping.OperationHandler",
      "name": "handle",
      "descriptor": "(Ljavax/servlet/http/HttpServletRequest;Ljava/util/Map;)Ljava/lang/Object;"
    },
    "requestMappingConditions": {
      "consumes": [],
      "headers": [],
      "methods": ["GET"],
      "params": [],
      "patterns": ["/actuator/beans"],
      "produces": [{
        "mediaType": "application/vnd.spring-boot.actuator.v2+json",
        "negated": false
      }, {
        "mediaType": "application/json",
        "negated": false
      }]
    }
  }
}

3.7 /threaddump

/threaddump 接口会生成当前线程活动的快照。这个功能非常好，方便我们在日常定位问题的时候查看线程的情况。 主要展示了线程名、线程ID、线程的状态、是否等待锁资源等信息。

启动工程，打开浏览器访问： http://localhost:8080/actuator/threaddump ，部分结果如下：

{
	"threads": [{
		"threadName": "Reference Handler",
		"threadId": 2,
		"blockedTime": -1,
		"blockedCount": 2,
		"waitedTime": -1,
		"waitedCount": 0,
		"lockName": null,
		"lockOwnerId": -1,
		"lockOwnerName": null,
		"daemon": true,
		"inNative": false,
		"suspended": false,
		"threadState": "RUNNABLE",
		"priority": 10,
		"stackTrace": [{
			"classLoaderName": null,
			"moduleName": "java.base",
			"moduleVersion": "11.0.4",
			"methodName": "waitForReferencePendingList",
			"fileName": "Reference.java",
			"lineNumber": -2,
			"className": "java.lang.ref.Reference",
			"nativeMethod": true
		}
  ...
  "lockedMonitors": [],
		"lockedSynchronizers": [{
			"className": "java.util.concurrent.locks.ReentrantLock$NonfairSync",
			"identityHashCode": 2060076420
		}],
		"lockInfo": null
  ...
  {
		"threadName": "DestroyJavaVM",
		"threadId": 42,
		"blockedTime": -1,
		"blockedCount": 0,
		"waitedTime": -1,
		"waitedCount": 0,
		"lockName": null,
		"lockOwnerId": -1,
		"lockOwnerName": null,
		"daemon": false,
		"inNative": false,
		"suspended": false,
		"threadState": "RUNNABLE",
		"priority": 5,
		"stackTrace": [],
		"lockedMonitors": [],
		"lockedSynchronizers": [],
		"lockInfo": null
	}]
}

4. 示例代码

示例代码-Github

示例代码-Gitee

5. 参考：

使用 Spring Boot Actuator 监控应用

Spring Boot 官方文档之 Actuator