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