「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