BackendBench
Coffee

Unravel โ€บ Java concepts โ€บ Cloud and operations

Spring

Spring Boot Actuator and health checks

Actuator adds operational endpoints to a running Spring Boot app (health, metrics, environment, thread dump).

๐Ÿ”Ž Unravel this examplePrerequisites (1)

Learn these first

Spring beans and dependency injection

At a glance

Mental model

The dashboard of a car.

What happens, in order
  1. 1Adding spring-boot-starter-actuator exposes /actuator/health, /info, /metrics and moreChoose what is public with management.endpoints.web.exposure.include.
  2. 2A HealthIndicator bean returns Health.up() or Health.down().withDetail("reason", ...)Boot already contributes indicators for the database, disk space, Redis, Kafka and more; the overall status is the worst of them.
  3. 3Liveness (/health/liveness) answers "should I restart this pod?", readiness (/health/readiness) answers "should traffic be sent here?"Probes in Kubernetes should use these two.
  4. 4Custom endpoints use @Endpoint(id = "feature-flags") with @ReadOperation / @WriteOperation methods
Remember
Watch out
Exposing all actuator endpoints to the internetLiveness probes that check dependenciesSlow or blocking health indicatorsNot distinguishing readiness from liveness
Example (highlighted lines explain it)
@Componentpublic class PaymentsHealth implements HealthIndicator {    private final PaymentClient client;    public PaymentsHealth(PaymentClient client) { this.client = client; }    @Override    public Health health() {        try {            client.ping();            return Health.up().build();        } catch (Exception e) {            return Health.down(e).withDetail("service", "payments").build();        }    }}
  1. line 2 uses Health, the core of Spring Boot Actuator and health checks
  2. line 4 uses Health, the core of Spring Boot Actuator and health checks
  3. line 7 uses Health, the core of Spring Boot Actuator and health checks
  4. line 10 uses Health, the core of Spring Boot Actuator and health checks
  5. line 12 uses Health, the core of Spring Boot Actuator and health checks
Read the full explanation (about 1 min)

Actuator adds operational endpoints to a running Spring Boot app (health, metrics, environment, thread dump). Health checks tell load balancers and Kubernetes whether the instance may receive traffic.

A mental model

The dashboard of a car. You do not need it to drive, but it tells you when the engine is overheating or the fuel is low, and the mechanic reads it too.

How it works

Adding spring-boot-starter-actuator exposes /actuator/health, /info, /metrics and more. Choose what is public with management.endpoints.web.exposure.include.

A HealthIndicator bean returns Health.up() or Health.down().withDetail("reason", ...). Boot already contributes indicators for the database, disk space, Redis, Kafka and more; the overall status is the worst of them.

Liveness (/health/liveness) answers "should I restart this pod?", readiness (/health/readiness) answers "should traffic be sent here?". Probes in Kubernetes should use these two.

Custom endpoints use @Endpoint(id = "feature-flags") with @ReadOperation / @WriteOperation methods.

Going deeper

Do not make liveness depend on external systems. If the database is down and liveness fails, Kubernetes restarts every healthy pod and turns a partial outage into a total one.

Secure the endpoints. env, heapdump and threaddump leak secrets and internals; expose only what monitoring needs, ideally on a separate management port.

A health check that does real work (long queries) becomes a load problem when the platform calls it every few seconds from many pods. Keep indicators cheap and cache expensive results.

Under the hood

Endpoints are exposed over HTTP and JMX through an abstraction, so one @Endpoint serves both. The health endpoint aggregates HealthContributor beans with a StatusAggregator, which orders statuses (DOWN beats OUT_OF_SERVICE beats UP) and a HttpCodeStatusMapper maps DOWN to HTTP 503.

Common mistakes

  • Exposing all actuator endpoints to the internet.
  • Liveness probes that check dependencies.
  • Slow or blocking health indicators.
  • Not distinguishing readiness from liveness.

How Unravel recognises it

When you paste code, Unravel looks for these signs of spring boot actuator and health checks. Spotting them yourself is a good habit when you read unfamiliar code:

Part of a learning path

Related concepts

Metrics with MicrometerErrors and loggingContainers and Kubernetes in Java codeI/O and data

Frequently asked questions

What is Spring Boot Actuator and health checks?

Actuator adds operational endpoints to a running Spring Boot app (health, metrics, environment, thread dump). Health checks tell load balancers and Kubernetes whether the instance may receive traffic.

What are the most common mistakes with Spring Boot Actuator and health checks?

Exposing all actuator endpoints to the internet. Liveness probes that check dependencies. Slow or blocking health indicators. Not distinguishing readiness from liveness.

How can I see Spring Boot Actuator and health checks in real code?

Paste your own Java into Unravel and it will point out where spring boot actuator and health checks appears, explain how it works at the detail level you choose, and draw the flow of the code around it.