Health Information

You can use health information to check the status of your running application. It is often used by monitoring software to alert someone when a production system goes down. The information exposed by the health endpoint depends on the management.endpoint.health.show-details and management.endpoint.health.show-components properties, which can be configured with one of the following values:

Name Description

never

Details are never shown.

when-authorized

Details are shown only to authorized users. Authorized roles can be configured by using management.endpoint.health.roles.

always

Details are shown to all users.

The default value is never. A user is considered to be authorized when they are in one or more of the endpoint’s roles. If the endpoint has no configured roles (the default), all authenticated users are considered to be authorized. You can configure the roles by using the management.endpoint.health.roles property.

If you have secured your application and wish to use always, your security configuration must permit access to the health endpoint for both authenticated and unauthenticated users.

Health information is collected from the content of a HealthContributorRegistry (by default, all HealthContributor instances defined in your ApplicationContext). Spring Boot includes a number of auto-configured HealthContributors, and you can also write your own.

A HealthContributor can be either a HealthIndicator or a CompositeHealthContributor. A HealthIndicator provides actual health information, including a Status. A CompositeHealthContributor provides a composite of other HealthContributors. Taken together, contributors form a tree structure to represent the overall system health.

By default, the final system health is derived by a StatusAggregator, which sorts the statuses from each HealthIndicator based on an ordered list of statuses. The first status in the sorted list is used as the overall health status. If no HealthIndicator returns a status that is known to the StatusAggregator, an UNKNOWN status is used.

You can use the HealthContributorRegistry to register and unregister health indicators at runtime.

Auto-configured HealthIndicators

When appropriate, Spring Boot auto-configures the HealthIndicators listed in the following table. You can also enable or disable selected indicators by configuring management.health.key.enabled, with the key listed in the following table:

Key Name Description

cassandra

CassandraDriverHealthIndicator

Checks that a Cassandra database is up.

couchbase

CouchbaseHealthIndicator

Checks that a Couchbase cluster is up.

db

DataSourceHealthIndicator

Checks that a connection to DataSource can be obtained.

diskspace

DiskSpaceHealthIndicator

Checks for low disk space.

elasticsearch

ElasticsearchRestHealthIndicator

Checks that an Elasticsearch cluster is up.

hazelcast

HazelcastHealthIndicator

Checks that a Hazelcast server is up.

influxdb

InfluxDbHealthIndicator

Checks that an InfluxDB server is up.

jms

JmsHealthIndicator

Checks that a JMS broker is up.

ldap

LdapHealthIndicator

Checks that an LDAP server is up.

mail

MailHealthIndicator

Checks that a mail server is up.

mongo

MongoHealthIndicator

Checks that a Mongo database is up.

neo4j

Neo4jHealthIndicator

Checks that a Neo4j database is up.

ping

PingHealthIndicator

Always responds with UP.

rabbit

RabbitHealthIndicator

Checks that a Rabbit server is up.

redis

RedisHealthIndicator

Checks that a Redis server is up.
You can disable them all by setting the management.health.defaults.enabled property.

Additional HealthIndicators are available but are not enabled by default:

Key Name Description

livenessstate

LivenessStateHealthIndicator

Exposes the “Liveness” application availability state.

readinessstate

ReadinessStateHealthIndicator

Exposes the “Readiness” application availability state.

Writing Custom HealthIndicators

To provide custom health information, you can register Spring beans that implement the HealthIndicator interface. You need to provide an implementation of the health() method and return a Health response. The Health response should include a status and can optionally include additional details to be displayed. The following code shows a sample HealthIndicator implementation:

  • Java

  • Kotlin

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.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 some specific health check
		return ...
	}

}
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.HealthIndicator
import org.springframework.stereotype.Component

@Component
class MyHealthIndicator : HealthIndicator {

	override fun health(): Health {
		val errorCode = check()
		if (errorCode != 0) {
			return Health.down().withDetail("Error Code", errorCode).build()
		}
		return Health.up().build()
	}

	private fun check(): Int {
		// perform some specific health check
		return  ...
	}

}
The identifier for a given HealthIndicator is the name of the bean without the HealthIndicator suffix, if it exists. In the preceding example, the health information is available in an entry named my.
Health indicators are usually called over HTTP and need to respond before any connection timeouts. Spring Boot will log a warning message for any health indicator that takes longer than 10 seconds to respond. If you want to configure this threshold, you can use the management.endpoint.health.logging.slow-indicator-threshold property.

In addition to Spring Boot’s predefined Status types, Health can return a custom Status that represents a new system state. In such cases, you also need to provide a custom implementation of the StatusAggregator interface, or you must configure the default implementation by using the management.endpoint.health.status.order configuration property.

For example, assume a new Status with a code of FATAL is being used in one of your HealthIndicator implementations. To configure the severity order, add the following property to your application properties:

  • Properties

  • YAML

management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
management:
  endpoint:
    health:
      status:
        order: "fatal,down,out-of-service,unknown,up"

The HTTP status code in the response reflects the overall health status. By default, OUT_OF_SERVICE and DOWN map to 503. Any unmapped health statuses, including UP, map to 200. You might also want to register custom status mappings if you access the health endpoint over HTTP. Configuring a custom mapping disables the defaults mappings for DOWN and OUT_OF_SERVICE. If you want to retain the default mappings, you must explicitly configure them, alongside any custom mappings. For example, the following property maps FATAL to 503 (service unavailable) and retains the default mappings for DOWN and OUT_OF_SERVICE:

  • Properties

  • YAML

management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503
management:
  endpoint:
    health:
      status:
        http-mapping:
          down: 503
          fatal: 503
          out-of-service: 503
If you need more control, you can define your own HttpCodeStatusMapper bean.

The following table shows the default status mappings for the built-in statuses:

Status Mapping

DOWN

SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

SERVICE_UNAVAILABLE (503)

UP

No mapping by default, so HTTP status is 200

UNKNOWN

No mapping by default, so HTTP status is 200

Reactive Health Indicators

For reactive applications, such as those that use Spring WebFlux, ReactiveHealthContributor provides a non-blocking contract for getting application health. Similar to a traditional HealthContributor, health information is collected from the content of a ReactiveHealthContributorRegistry (by default, all HealthContributor and ReactiveHealthContributor instances defined in your ApplicationContext). Regular HealthContributors that do not check against a reactive API are executed on the elastic scheduler.

In a reactive application, you should use the ReactiveHealthContributorRegistry to register and unregister health indicators at runtime. If you need to register a regular HealthContributor, you should wrap it with ReactiveHealthContributor#adapt.

To provide custom health information from a reactive API, you can register Spring beans that implement the ReactiveHealthIndicator interface. The following code shows a sample ReactiveHealthIndicator implementation:

  • Java

  • Kotlin

import reactor.core.publisher.Mono;

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.stereotype.Component;

@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 some specific health check
		return ...
	}

}
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.ReactiveHealthIndicator
import org.springframework.stereotype.Component
import reactor.core.publisher.Mono

@Component
class MyReactiveHealthIndicator : ReactiveHealthIndicator {

	override fun health(): Mono<Health> {
		return doHealthCheck()!!.onErrorResume { exception: Throwable? ->
			Mono.just(Health.Builder().down(exception).build())
		}
	}

	private fun doHealthCheck(): Mono<Health>? {
		// perform some specific health check
		return  ...
	}

}
To handle the error automatically, consider extending from AbstractReactiveHealthIndicator.

Auto-configured ReactiveHealthIndicators

When appropriate, Spring Boot auto-configures the following ReactiveHealthIndicators:

Key Name Description

cassandra

CassandraDriverReactiveHealthIndicator

Checks that a Cassandra database is up.

couchbase

CouchbaseReactiveHealthIndicator

Checks that a Couchbase cluster is up.

elasticsearch

ElasticsearchReactiveHealthIndicator

Checks that an Elasticsearch cluster is up.

mongo

MongoReactiveHealthIndicator

Checks that a Mongo database is up.

neo4j

Neo4jReactiveHealthIndicator

Checks that a Neo4j database is up.

redis

RedisReactiveHealthIndicator

Checks that a Redis server is up.
If necessary, reactive indicators replace the regular ones. Also, any HealthIndicator that is not handled explicitly is wrapped automatically.

Health Groups

It is sometimes useful to organize health indicators into groups that you can use for different purposes.

To create a health indicator group, you can use the management.endpoint.health.group.<name> property and specify a list of health indicator IDs to include or exclude. For example, to create a group that includes only database indicators you can define the following:

  • Properties

  • YAML

management.endpoint.health.group.custom.include=db
management:
  endpoint:
    health:
      group:
        custom:
          include: "db"

You can then check the result by hitting localhost:8080/actuator/health/custom.

Similarly, to create a group that excludes the database indicators from the group and includes all the other indicators, you can define the following:

  • Properties

  • YAML

management.endpoint.health.group.custom.exclude=db
management:
  endpoint:
    health:
      group:
        custom:
          exclude: "db"

By default, groups inherit the same StatusAggregator and HttpCodeStatusMapper settings as the system health. However, you can also define these on a per-group basis. You can also override the show-details and roles properties if required:

  • Properties

  • YAML

management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
management.endpoint.health.group.custom.status.order=fatal,up
management.endpoint.health.group.custom.status.http-mapping.fatal=500
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500
management:
  endpoint:
    health:
      group:
        custom:
          show-details: "when-authorized"
          roles: "admin"
          status:
            order: "fatal,up"
            http-mapping:
              fatal: 500
              out-of-service: 500
You can use @Qualifier("groupname") if you need to register custom StatusAggregator or HttpCodeStatusMapper beans for use with the group.

A health group can also include/exclude a CompositeHealthContributor. You can also include/exclude only a certain component of a CompositeHealthContributor. This can be done using the fully qualified name of the component as follows:

management.endpoint.health.group.custom.include="test/primary"
management.endpoint.health.group.custom.exclude="test/primary/b"

In the example above, the custom group will include the HealthContributor with the name primary which is a component of the composite test. Here, primary itself is a composite and the HealthContributor with the name b will be excluded from the custom group.

Health groups can be made available at an additional path on either the main or management port. This is useful in cloud environments such as Kubernetes, where it is quite common to use a separate management port for the actuator endpoints for security purposes. Having a separate port could lead to unreliable health checks because the main application might not work properly even if the health check is successful. The health group can be configured with an additional path as follows:

management.endpoint.health.group.live.additional-path="server:/healthz"

This would make the live health group available on the main server port at /healthz. The prefix is mandatory and must be either server: (represents the main server port) or management: (represents the management port, if configured.) The path must be a single path segment.

DataSource Health

The DataSource health indicator shows the health of both standard data sources and routing data source beans. The health of a routing data source includes the health of each of its target data sources. In the health endpoint’s response, each of a routing data source’s targets is named by using its routing key. If you prefer not to include routing data sources in the indicator’s output, set management.health.db.ignore-routing-data-sources to true.