ヘルス
/actuator/health は、アプリケーションのすべての HealthIndicator を一つのステータスに集約します: UP、DOWN、OUT_OF_SERVICE、UNKNOWN。応答は UP なら 200、DOWN と OUT_OF_SERVICE なら 503 です。グループはレポートの一部に独自のパスを与え、Kubernetes のプローブはアプリケーションの可用性に従います。
使う理由
ロードバランサーには一つのイエスかノーが必要で、運用担当者にはどの部分が失敗したかを知る必要があります。health エンドポイントはその両方を提供します。ステータスは全員に、コンポーネントとその詳細は自分で選んだ相手に、です。
例
// レポートの "orders" の部分: HealthIndicator を除いた Bean 名。
@Component()
class OrdersHealthIndicator extends HealthIndicator {
OrdersHealthIndicator(this.orders);
final Orders orders;
@override
Future<Health> health() async => await orders.reachable()
? Health.up().withDetail('pending', await orders.pending()).build()
: Health.down().build();
}
# lib/resources/application.yml
management:
endpoint:
health:
show-details: when-authorized
roles: ADMIN
show-components: always
group:
core:
include: ping,orders,db
show-details: always
additional-path: "server:/healthz"
probes:
enabled: true
add-additional-paths: true
health:
diskspace:
threshold: 100MB
$ curl localhost:8080/actuator/health/core
{"status":"UP","components":{"db":{"status":"UP","details":{"database":"PostgreSQL","validationQuery":"isValid()"}},"orders":{"status":"UP","details":{"pending":3}},"ping":{"status":"UP"}}}
$ curl localhost:8080/livez
{"status":"UP"}
インジケーター
すべての HealthIndicator の Bean は、HealthIndicator を除いた Bean 名 (ordersHealthIndicator は orders) のもとで、レポートの一部になります。インジケーターは後で応答してもかまいません (Future)。例外を投げたものは、エラーを詳細とする DOWN になります。AbstractHealthIndicator は同じことをビルダーで行います。
class QueueHealthIndicator extends AbstractHealthIndicator {
QueueHealthIndicator(this.client);
final QueueClient client;
@override
Future<void> doHealthCheck(HealthBuilder builder) async {
builder.up().withDetail('broker', client.broker);
if (!await client.ping()) {
builder.down();
}
}
}
CompositeHealthContributor は、複数のインジケーターを一つの名前のもとにまとめます (db/primary、db/reporting)。
組み込みのインジケーター:
| インジケーター | 内容 | 切り替えるもの |
|---|---|---|
ping |
常に UP |
management.health.ping.enabled |
diskSpace |
management.health.diskspace.path (.) の空き容量が .threshold (10 MB) を上回るか。測定できない場所 (iOS、Web) では UNKNOWN |
management.health.diskspace.enabled |
livenessState、readinessState |
アプリケーションの LivenessState と ReadinessState |
プローブ、または management.health.livenessstate.enabled / readinessstate.enabled |
db |
spring_boot_starter_data の各データソース (isValid()) |
management.health.db.enabled |
securityContext |
spring_boot_starter_security のもの: 今どのリクエストの外にも認証が設定されているかどうかと、設定された回数。常に UP。Spring Boot にはありません |
management.health.securityContext.enabled=true (デフォルトはオフ) |
management.health.defaults.enabled=false は、自分のキーが設定されていないすべてのインジケーターを無効にします。ライブラリは @ConditionalOnEnabledHealthIndicator('queue') (management.health.queue.enabled) で自分のインジケーターを切り替えます。
誰が何を見られるか
デフォルトでは、レポートはステータスだけを示します。
| キー | 値 | デフォルト | 意味 |
|---|---|---|---|
management.endpoint.health.show-details |
never、when-authorized、always |
never |
各インジケーターの詳細 (サイズ、バージョン、エラー) を誰が見られるか |
management.endpoint.health.show-components |
同上 | show-details と同じ |
コンポーネントを詳細なしで名前だけ誰が見られるか |
management.endpoint.health.roles |
リスト | 空 | when-authorized が求めるロール (いずれか一つ)。空: ログインした任意のユーザー |
when-authorized には spring_boot_starter_security が必要です。リクエストの Authentication のロールを読みます (ROLE_ADMIN はロール ADMIN)。セキュリティ を参照してください。
ステータスの集約と HTTP コード
| キー | デフォルト | 意味 |
|---|---|---|
management.endpoint.health.status.order |
DOWN、OUT_OF_SERVICE、UP、UNKNOWN |
最も深刻なものから最も軽いものへのステータス。集約結果は、この順序で各部分の最初のステータス |
management.endpoint.health.status.http-mapping.<status> |
DOWN と OUT_OF_SERVICE は 503、その他は 200 |
ステータスの HTTP コード |
# DOWN より深刻な独自のステータスを、500 で応答する。
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
management.endpoint.health.status.http-mapping.fatal=500
グループ
グループは、独自のパスと独自の設定を持つレポートの一部です。
キー (management.endpoint.health.group.<name>. の下) |
デフォルト | 意味 |
|---|---|---|
include |
すべて | グループのコントリビューター: 名前、*、またはコンポジットの中の一つを示す db/primary |
exclude |
なし | 除外するコントリビューター |
show-details |
エンドポイントのもの | 誰が詳細を見られるか |
show-components |
グループの show-details |
誰がコンポーネントを見られるか |
roles |
エンドポイントのもの | when-authorized のロール |
status.order、status.http-mapping.<status> |
エンドポイントのもの | グループの集約と HTTP コード |
additional-path |
なし | メインのサーバー上の追加のパス: server:/healthz |
パス: /actuator/health/core はグループに、/actuator/health/db は一つのコンポーネントに、/actuator/health/db/reporting はその一部に応答します。グループの一部がグループを通して見つかるのは、それがメンバーである場合だけです (/actuator/health/core/ping)。
存在しないコントリビューターを含めたり除外したりするグループは起動を止めます (Included health contributor 'x' in group 'core' does not exist)。management.endpoint.health.validate-group-membership=false はそれを許可します。
Kubernetes のプローブ
| キー | デフォルト | 意味 |
|---|---|---|
management.endpoint.health.probes.enabled |
false。Kubernetes と Cloud Foundry では true |
livenessState と readinessState インジケーターを持つ liveness と readiness のグループを追加する |
management.endpoint.health.probes.add-additional-paths |
false |
それらにメインのサーバーの /livez と /readyz でも応答する |
# deployment.yaml (Kubernetes)
livenessProbe:
httpGet: { path: /actuator/health/liveness, port: 8080 }
readinessProbe:
httpGet: { path: /actuator/health/readiness, port: 8080 }
状態はアプリケーションの ApplicationAvailability から来ます。SpringApplication は起動後に LivenessState.correct を、ランナーが終わったら ReadinessState.acceptingTraffic を発行します。コードはそれらを変えるために AvailabilityChangeEvent を発行します。
// キャッシュの再構築中は、インスタンスをロードバランサーから外す。
AvailabilityChangeEvent.publish(context, ReadinessState.refusingTraffic);
liveness または readiness という名前のアプリケーションのグループは、プローブのものを置き換えます。イベントと可用性 を参照してください。
遅いインジケーター
management.endpoint.health.logging.slow-indicator-threshold (デフォルトは 10 秒) より遅いインジケーターは、警告としてログに出されます。
サーバーなしで
エンドポイントは普通のオブジェクトなので、コードから直接問い合わせられます。
final health = HealthEndpoint(registry, groups);
final report = await health.health();
print(jsonEncode(report?.toJson())); // {"status":"UP","components":{...}}
Spring (Java) との対応
インジケーター、プロパティ、グループ、プローブは同じです。違い: HealthIndicator と ReactiveHealthIndicator の両方に一つの HealthIndicator を使います (その health() は Future を返せます)。例外を投げたインジケーターはエラー付きの DOWN になります。Spring Boot ではリクエストが失敗します。ディスク容量は df または .NET の DriveInfo で測定します。名前は Spring Boot 4 のものです (HealthDescriptor、CompositeHealthDescriptor)。