「SpringBoot」定制⾃⼰的 Health Indicator

Spring Boot ⾃带的 Health Indicator

⽬的

• 检查应⽤程序的运⾏状态

状态

• DOWN - 503
• OUT_OF_SERVICE - 503
• UP - 200
• UNKNOWN - 200

机制

• 通过 HealthIndicatorRegistry 收集信息
• HealthIndicator 实现具体检查逻辑

配置项

• management.health.defaults.enabled=true|false
• management.health..enabled=true
• management.endpoint.health.show-details=never | whenauthorized | alway

⾃定义 Health Indicator

⽅法

• 实现 HealthIndicator 接⼝
• 根据⾃定义检查逻辑返回对应 Health 状态

• Health 中包含状态和详细描述信息

Health Information

官网地址：https://docs.spring.io/spring-boot/docs/2.5.6/reference/html/actuator.html#actuator.endpoints.health

可以使用运行状况信息(health information)检查正在运行的应用程序的状态。它经常被监控软件用于在生产系统崩溃时发出警报。health endpoint公开的信息取决于management.endpoint.health.show-details和management.endpoint.health.show-components属性，可配置为以下值之一:

Name	Description
never	从不显示详细信息。
when-authorized	详细信息只显示给授权用户。可使用management.endpoint.health.roles配置授权角色。
always	详细信息将显示给所有用户。

缺省值为never。当用户处于一个或多个endpoints的角色中时，就认为用户已获得授权。如果端点没有配置角色(默认)，则所有经过身份验证的用户都被认为是经过授权的。可以使用management.endpoint.health.roles属性配置角色。

如果已保护了应用程序并希望使用always，则安全配置必须允许已验证和未验证的用户访问运行状况端点。

运行状况信息从HealthContributorRegistry(默认情况下，ApplicationContext中定义的所有HealthContributor实例)的内容中收集。Spring Boot包括许多自动配置的HealthContributors，您也可以编写自己的HealthContributors。

HealthContributor可以是HealthIndicator或CompositeHealthContributor。HealthIndicator提供实际的运行状况信息，包括状态。CompositeHealthContributor提供其他HealthContributors的组合。总的来说，contributors形成了一个树形结构来表示整个系统的健康状况。

默认情况下，最终的系统运行状况由StatusAggregator派生，它根据有序的状态列表对每个HealthIndicator中的状态进行排序。排序列表中的第一个状态用作总体运行状况状态。如果没有HealthIndicator返回StatusAggregator已知的状态，则使用UNKNOWN状态。

HealthContributorRegistry可用于在运行时注册和取消注册health indicators。

Auto-configured HealthIndicators

下面的HealthIndicators在适当的时候由Spring Boot自动配置。您也可以通过配置management.health.key.enabled来启用/禁用所选指标。通过使用下表中列出的key：

Key	Name	Description
cassandra	CassandraDriverHealthIndicator	检查Cassandra数据库是否已启动。
couchbase	CouchbaseHealthIndicator	检查Couchbase集群是否已启动。
db	DataSourceHealthIndicator	检查是否可以获得到数据源的连接。
diskspace	DiskSpaceHealthIndicator	检查磁盘空间不足。
elasticsearch	ElasticsearchRestHealthIndicator	检查Elasticsearch集群是否已启动。
hazelcast	HazelcastHealthIndicator	检查Hazelcast服务器是否已启动。
influxdb	InfluxDbHealthIndicator	检查InfluxDB服务器是否已启动。
jms	JmsHealthIndicator	检查JMS代理是否已启动。
ldap	LdapHealthIndicator	检查LDAP服务器是否已启动。
mail	MailHealthIndicator	检查邮件服务器是否启动。
mongo	MongoHealthIndicator	检查Mongo数据库是否已启动。
neo4j	Neo4jHealthIndicator	检查Neo4j数据库是否已启动。
ping	PingHealthIndicator	总是用UP响应。
rabbit	RabbitHealthIndicator	检查Rabbit服务器是否启动。
redis	RedisHealthIndicator	检查Redis服务器是否启动。
solr	SolrHealthIndicator	检查Solr服务器是否启动。

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

有其他HealthIndicators可用，但默认情况下不启用:

Key	Name	Description
livenessstate	LivenessStateHealthIndicator	暴露“Liveness”应用程序可用性状态。
readinessstate	ReadinessStateHealthIndicator	暴露“Readiness”应用程序可用性状态。

自定义 HealthIndicators

要提供定制的运行状况信息，可以注册实现HealthIndicator接口的Spring bean。您需要提供health()方法的实现并返回一个 Health 响应。Health 响应应包括一个状态，并可选地包括要显示的其他详细信息。下面的代码显示了一个HealthIndicator实现的示例:

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check();
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        // perform some specific health check
        return ...
    }

}           

给定HealthIndicator的标识符是不带HealthIndicator后缀的bean的名称(如果它存在的话)。在前面的示例中，health information在entry时my中可用。

除了Spring Boot的预定义Status类型外，Health还可以返回一个表示新系统状态的自定义状态。在这种情况下，还需要提供StatusAggregator接口的自定义实现，或者必须使用management.endpoint.health.status.order配置属性来配置默认实现。

例如，假设在您的一个HealthIndicator实现中使用了一个code为FATAL的新Status。要配置严重性顺序，请将以下属性添加到应用程序属性中:

management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up

响应中的HTTP状态码反映总体运行状况状态。缺省情况下，OUT_OF_SERVICE和DOWN对应为503。任何未映射的运行状况状态(包括UP)都映射到200。如果通过HTTP访问health endpoint，还可能需要注册自定义状态映射。配置自定义映射将禁用DOWN和OUT_OF_SERVICE的默认映射。如果您希望保留默认映射，则必须在任何自定义映射旁边显式地配置它们。例如，以下属性将FATAL映射到503(服务不可用)，并保留DOWN和OUT的默认映射：

management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503           

如果需要更多的控制，可以定义自己的HttpCodeStatusMapper bean。

下表显示了内置statuses的默认状态映射:

Status	Mapping
DOWN	SERVICE_UNAVAILABLE (503)
OUT_OF_SERVICE	SERVICE_UNAVAILABLE (503)
UP	No mapping by default, so HTTP status is 200
UNKNOWN	No mapping by default, so HTTP status is 200