
# ヘルス

`/actuator/health` は、アプリケーションのすべての `HealthIndicator` を一つのステータスに集約します: `UP`、`DOWN`、`OUT_OF_SERVICE`、`UNKNOWN`。応答は `UP` なら `200`、`DOWN` と `OUT_OF_SERVICE` なら `503` です。グループはレポートの一部に独自のパスを与え、Kubernetes のプローブはアプリケーションの可用性に従います。

## 使う理由

ロードバランサーには一つのイエスかノーが必要で、運用担当者にはどの部分が失敗したかを知る必要があります。health エンドポイントはその両方を提供します。ステータスは全員に、コンポーネントとその詳細は自分で選んだ相手に、です。

## 例

```dart
// レポートの "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();
}
```

```yaml
# 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
```

```console
$ 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` は同じことをビルダーで行います。

```dart
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`)。[セキュリティ](security.md) を参照してください。

## ステータスの集約と 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 コード |

```properties
# 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` でも応答する |

```yaml
# 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` を発行します。

```dart
// キャッシュの再構築中は、インスタンスをロードバランサーから外す。
AvailabilityChangeEvent.publish(context, ReadinessState.refusingTraffic);
```

`liveness` または `readiness` という名前のアプリケーションのグループは、プローブのものを置き換えます。[イベントと可用性](../spring-boot-dart/events.md) を参照してください。

## 遅いインジケーター

`management.endpoint.health.logging.slow-indicator-threshold` (デフォルトは 10 秒) より遅いインジケーターは、警告としてログに出されます。

## サーバーなしで

エンドポイントは普通のオブジェクトなので、コードから直接問い合わせられます。

```dart
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`)。

## 関連項目

- [エンドポイント](endpoints.md)
- [セキュリティ](security.md)
- [イベントと可用性](../spring-boot-dart/events.md)
- [すべてのプロパティ](properties.md)
