ヘルス

/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)。

関連項目