Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/spring-projects/spring-boot/llms.txt

Use this file to discover all available pages before exploring further.

The /actuator/health endpoint gives you a real-time view of your application’s operational state. Spring Boot aggregates health information from all registered HealthIndicator beans — covering databases, caches, messaging systems, and disk space — into a single status. Monitoring tools poll this endpoint to detect outages; Kubernetes uses it to make pod scheduling and traffic routing decisions.

​
Health status values

Every health indicator returns one of the following statuses:
StatusMeaningDefault HTTP code
UPThe component is functioning normally.200
DOWNThe component has failed.503
OUT_OF_SERVICEThe component has been deliberately taken offline.503
UNKNOWNThe component state cannot be determined.200
The final system health is determined by a StatusAggregator that orders all individual statuses and takes the highest-severity one.

​
Showing health details

By default, the response contains only the top-level status. Control what is shown with management.endpoint.health.show-details: 
management:
  endpoint:
    health:
      show-details: when-authorized
      roles: "admin"
ValueBehavior
never (default)Only the top-level status is returned.
when-authorizedFull details are shown to authenticated users in the configured roles.
alwaysFull details are shown to all users.
The show-components property accepts the same values and controls whether the names of individual indicators appear in the response without their full details.

​
Auto-configured health indicators

Spring Boot automatically configures indicators for common infrastructure components. Enable or disable each with management.health.<key>.enabled:
KeyIndicatorChecks
dbDataSourceHealthIndicatorObtains a connection from the DataSource.
cassandraCassandraDriverHealthIndicatorCassandra database is up.
couchbaseCouchbaseHealthIndicatorCouchbase cluster is up.
elasticsearchElasticsearchRestClientHealthIndicatorElasticsearch cluster is up.
mongoMongoHealthIndicatorMongoDB database is up.
neo4jNeo4jHealthIndicatorNeo4j database is up.
redisDataRedisHealthIndicatorRedis server is up.
ldapLdapHealthIndicatorLDAP server is up.
For routing data sources, the health of each target data source is included. To exclude routing data sources, set management.health.db.ignore-routing-data-sources=true.
KeyIndicatorChecks
rabbitRabbitHealthIndicatorRabbitMQ server is up.
jmsJmsHealthIndicatorJMS broker is up.
mailMailHealthIndicatorMail server is up.
hazelcastHazelcastHealthIndicatorHazelcast server is up.
diskspaceDiskSpaceHealthIndicatorChecks for low disk space.
sslSslHealthIndicatorSSL certificates are valid and not expiring soon.
pingPingHealthIndicatorAlways returns UP.
The ssl indicator has a management.health.ssl.certificate-validity-warning-threshold property. When a certificate will expire within this period, the indicator reports WILL_EXPIRE_SOON in its details, giving you lead time to rotate the certificate.
Disable all default indicators at once:
management:
  health:
    defaults:
      enabled: false
KeyIndicatorExposes
livenessstateLivenessStateHealthIndicatorThe Liveness application availability state.
readinessstateReadinessStateHealthIndicatorThe Readiness application availability state.
These are enabled by default. Disable them with management.endpoint.health.probes.enabled=false.

​
Writing a custom HealthIndicator

Implement HealthIndicator and register the implementation as a Spring bean. The bean name minus the HealthIndicator suffix becomes the component key in the health response. 
import org.springframework.boot.health.contributor.Health;
import org.springframework.boot.health.contributor.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check();
        if (errorCode != 0) {
            return Health.down()
                .withDetail("Error Code", errorCode)
                .build();
        }
        return Health.up().build();
    }

    private int check() {
        // perform the actual health check
        return 0;
    }

}
This bean is exposed under the key my (the HealthIndicator suffix is stripped).
Health indicators are called over HTTP and must respond before connection timeouts. Spring Boot logs a warning for any indicator that takes longer than 10 seconds. Adjust the threshold with management.endpoint.health.logging.slow-indicator-threshold.
For reactive applications using Spring WebFlux, implement ReactiveHealthIndicator instead to provide a non-blocking health check: 
import org.springframework.boot.health.contributor.Health;
import org.springframework.boot.health.contributor.ReactiveHealthIndicator;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return doHealthCheck()
            .onErrorResume((exception) ->
                Mono.just(new Health.Builder().down(exception).build()));
    }

    private Mono<Health> doHealthCheck() {
        // perform reactive health check
        return Mono.just(Health.up().build());
    }

}

​
Custom status ordering and HTTP mappings

To add a custom Status (such as FATAL) and define how it sorts relative to built-in statuses: 
management:
  endpoint:
    health:
      status:
        order: "fatal,down,out-of-service,unknown,up"
        http-mapping:
          down: 503
          fatal: 503
          out-of-service: 503

​
Health groups

Group indicators to serve different audiences or purposes, such as separating infrastructure checks from application checks: 
management:
  endpoint:
    health:
      group:
        custom:
          include: "db"
          show-details: "when-authorized"
          roles: "admin"
          status:
            order: "fatal,up"
Access the group at /actuator/health/custom. Groups can also be made available on the main server port via additional-path: 
management.endpoint.health.group.live.additional-path=server:/healthz

​
Kubernetes liveness and readiness probes

Spring Boot automatically exposes liveness and readiness as health groups at /actuator/health/liveness and /actuator/health/readiness when running in a Kubernetes environment.
1

Configure Kubernetes pod spec

livenessProbe:
  httpGet:
    path: "/actuator/health/liveness"
    port: 8080
  failureThreshold: 3
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: "/actuator/health/readiness"
    port: 8080
  failureThreshold: 3
  periodSeconds: 10
2

Optionally expose probes on the main server port

If actuator runs on a separate management port, the probe may succeed even when the main application is broken. Expose probes on the main port to avoid this:
management.endpoint.health.probes.add-additional-paths=true
This makes the liveness group available at /livez and readiness at /readyz on the main server port.
3

Add custom checks to the readiness probe

management:
  endpoint:
    health:
      group:
        readiness:
          include: "readinessState,customCheck"
The liveness probe should not depend on external systems such as databases. If an external system fails, Kubernetes will restart all application instances and may cause cascading failures. Reserve external checks for the readiness probe, and even then choose carefully.

​
Application lifecycle and probe states

Startup phaseLivenessStateReadinessStateHTTP server
StartingBROKENREFUSING_TRAFFICNot started
StartedCORRECTREFUSING_TRAFFICRefuses requests
ReadyCORRECTACCEPTING_TRAFFICAccepts requests
Shutdown phaseLiveness StateReadiness StateHTTP server
RunningCORRECTACCEPTING_TRAFFICAccepts requests
Graceful shutdownCORRECTREFUSING_TRAFFICNew requests rejected
Shutdown completeN/AN/AServer shut down

Build docs developers (and LLMs) love

Get started for freeTalk to us