
# Health

`/actuator/health` aggregates every `HealthIndicator` of the application into one status: `UP`, `DOWN`, `OUT_OF_SERVICE` or `UNKNOWN`. The answer is `200` for `UP`, `503` for `DOWN` and `OUT_OF_SERVICE`. Groups give parts of the report their own path, and the Kubernetes probes follow the application's availability.

## Why

A load balancer needs one yes or no; an operator needs to know which part failed. The health endpoint gives both: the status for everybody, the components and their details for whom you choose.

## Example

```dart
// Part of the report as "orders": the bean name without HealthIndicator.
@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"}
```

## Indicators

Every `HealthIndicator` bean is part of the report, under its bean name without `HealthIndicator` (`ordersHealthIndicator` is `orders`). An indicator may answer later (a `Future`); one that throws is `DOWN` with the error as detail. `AbstractHealthIndicator` does the same with a builder:

```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();
    }
  }
}
```

A `CompositeHealthContributor` groups several indicators under one name (`db/primary`, `db/reporting`).

The built-in indicators:

| Indicator | What | Switched by |
|---|---|---|
| `ping` | Always `UP` | `management.health.ping.enabled` |
| `diskSpace` | Free space of `management.health.diskspace.path` (`.`) above `.threshold` (10 MB); `UNKNOWN` where it cannot be measured (iOS, the web) | `management.health.diskspace.enabled` |
| `livenessState`, `readinessState` | The application's `LivenessState` and `ReadinessState` | the probes, or `management.health.livenessstate.enabled` / `readinessstate.enabled` |
| `db` | Each data source of `spring_boot_starter_data` (`isValid()`) | `management.health.db.enabled` |
| `securityContext` | Of `spring_boot_starter_security`: whether an authentication is set outside every request now, and how many times one was. Always `UP`. Not in Spring Boot | `management.health.securityContext.enabled=true` (off by default) |

`management.health.defaults.enabled=false` switches off every indicator whose own key is not set. A library switches its own indicator with `@ConditionalOnEnabledHealthIndicator('queue')` (`management.health.queue.enabled`).

## Who sees what

By default the report shows only the status.

| Key | Values | Default | Meaning |
|---|---|---|---|
| `management.endpoint.health.show-details` | `never`, `when-authorized`, `always` | `never` | Who sees each indicator's details (sizes, versions, errors) |
| `management.endpoint.health.show-components` | the same | as `show-details` | Who sees the components by name, without details |
| `management.endpoint.health.roles` | list | empty | The roles `when-authorized` asks for (any one); empty: any logged-in user |

`when-authorized` needs `spring_boot_starter_security`; it reads the roles of the request's `Authentication` (`ROLE_ADMIN` is the role `ADMIN`). See [Security](security.md).

## Status aggregation and HTTP codes

| Key | Default | Meaning |
|---|---|---|
| `management.endpoint.health.status.order` | `DOWN`, `OUT_OF_SERVICE`, `UP`, `UNKNOWN` | The statuses from the most to the least severe; the aggregate is the first status of the parts in this order |
| `management.endpoint.health.status.http-mapping.<status>` | `DOWN` and `OUT_OF_SERVICE` are `503`, the others `200` | The HTTP code of a status |

```properties
# A status of your own, more severe than DOWN, answered with 500.
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
management.endpoint.health.status.http-mapping.fatal=500
```

## Groups

A group is a part of the report at its own path, with its own settings:

| Key (under `management.endpoint.health.group.<name>.`) | Default | Meaning |
|---|---|---|
| `include` | all | The contributors of the group: names, `*`, or `db/primary` for one inside a composite |
| `exclude` | none | The contributors left out |
| `show-details` | the endpoint's | Who sees the details |
| `show-components` | the group's `show-details` | Who sees the components |
| `roles` | the endpoint's | The roles of `when-authorized` |
| `status.order`, `status.http-mapping.<status>` | the endpoint's | Aggregation and HTTP codes of the group |
| `additional-path` | none | An extra path on the main server: `server:/healthz` |

Paths: `/actuator/health/core` answers the group, `/actuator/health/db` one component, `/actuator/health/db/reporting` a part of it. A part of a group is found through the group only when it is a member (`/actuator/health/core/ping`).

A group that includes or excludes a contributor that does not exist stops the start (`Included health contributor 'x' in group 'core' does not exist`); `management.endpoint.health.validate-group-membership=false` allows it.

## Kubernetes probes

| Key | Default | Meaning |
|---|---|---|
| `management.endpoint.health.probes.enabled` | `false`; `true` on Kubernetes and Cloud Foundry | Adds the `liveness` and `readiness` groups, with the `livenessState` and `readinessState` indicators |
| `management.endpoint.health.probes.add-additional-paths` | `false` | Also answers them at `/livez` and `/readyz` on the main server |

```yaml
# deployment.yaml (Kubernetes)
livenessProbe:
  httpGet: { path: /actuator/health/liveness, port: 8080 }
readinessProbe:
  httpGet: { path: /actuator/health/readiness, port: 8080 }
```

The states come from the application's `ApplicationAvailability`: `SpringApplication` publishes `LivenessState.correct` after the start and `ReadinessState.acceptingTraffic` once the runners are done; code publishes an `AvailabilityChangeEvent` to change them:

```dart
// Take the instance out of the load balancer while the cache rebuilds.
AvailabilityChangeEvent.publish(context, ReadinessState.refusingTraffic);
```

An application group named `liveness` or `readiness` replaces the probe's. See [Events and availability](../spring-boot-dart/events.md).

## Slow indicators

An indicator slower than `management.endpoint.health.logging.slow-indicator-threshold` (10 s by default) is logged as a warning.

## Without a server

The endpoints are plain objects, so code can ask them directly:

```dart
final health = HealthEndpoint(registry, groups);
final report = await health.health();
print(jsonEncode(report?.toJson())); // {"status":"UP","components":{...}}
```

## In Spring (Java)

The same indicators, properties, groups and probes. Differences: one `HealthIndicator` for both `HealthIndicator` and `ReactiveHealthIndicator` (its `health()` may return a `Future`); an indicator that throws is `DOWN` with the error, where Spring Boot fails the request; disk space is measured with `df` or .NET's `DriveInfo`; the names are Spring Boot 4's (`HealthDescriptor`, `CompositeHealthDescriptor`).

## See also

- [Endpoints](endpoints.md)
- [Security](security.md)
- [Events and availability](../spring-boot-dart/events.md)
- [All properties](properties.md)
