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

// 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();
}
# 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"}

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:

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.

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
# 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
# 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:

// 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.

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:

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