Custom Health Check in Spring Boot Actuator

A quick guide to Custom Health Indicator with Spring Boot Actuator – with the help of actual examples.

Enable Spring Boot Actuator Health Endpoint

Health is an essential endpoint of the Spring Boot Actuator. It is helpful to know the health of an application in real-time.

We need to add the Gradle/Maven dependency to enable the Spring Boot Actuator endpoints.

build.gradle

compile("org.springframework.boot:spring-boot-starter-actuator")
Code language: Gradle (gradle)

pom.xml

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
Code language: HTML, XML (xml)

Having this dependency, Spring Boot automatically configures actuator endpoints. We can start our application and test the ‘/actuator/health‘ endpoint.

~ curl -X GET \
  http://localhost:8080/actuator/health

---
{"status":"UP"}
Code language: Bash (bash)

Detailed View of the Spring Boot /health Endpoint

As we can see in the previous response, the health endpoint, by default, returns a high-level status of our application’s health. This status is cumulatively derived from the health of various components of an application.

However, we can also enable a detailed view on the ‘/actuator/health‘ endpoint.

management:
  endpoint:
    health:
      show-details: always
Code language: YAML (yaml)

Reexecuting the ‘/actuator/health‘ endpoint, we can see Spring boot actuator returns a detailed response.

{
  "status":"UP",
  "details":{
    "db":{
      "status":"UP",
      "details":{
        "database":"H2",
        "hello":1
      }
    },
    "diskSpace":{
      "status":"UP",
      "details":{
        "total":250790436864,
        "free":36748783616,
        "threshold":10485760
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

Pre-Defined Health Indicators

The detailed view of the application’s health endpoint contains various Health Indicators, for example, database and disk space checks in the previous response. Spring Boot has some pre-defined Health Indicators that automatically plug in depending on the services the application uses. For example, our application interacts with a Database,, so Spring Boot Actuator automatically plugs in the DataSourceHealthIndicator. However, the disk space check is performed by the DiskSpaceHealthIndicator, which always executes.

Next is the list of some of the Spring Boot Actuator’s built-in Health Indicators.

• DataSourceHealthIndicator (seen in the above example)
• MongoHealthIndicator
• Neo4jHealthIndicator
• CassandraHealthIndicator
• RedisHealthIndicator
• RabbitHealthIndicator
• CouchbaseHealthIndicator
• DiskSpaceHealthIndicator (seen in the above example)
• ElasticsearchHealthIndicator
• InfluxDbHealthIndicator
• JmsHealthIndicator
• MailHealthIndicator
• SolrHealthIndicator

Creating Spring Boot Actuator Custom Health Indicator

Spring Boot Actuator provides ready-to-use health indicators for almost all of the services. However, sometimes an application may need a custom health indicator that depends on its business or internal logic.

Thankfully, Spring Boot Actuator allows us to implement custom health indicators where an application can have custom logic to flag the application’s health. To understand it better, we will implement our own Sprign Boot Actuator Custom Health Indicators.

Consider, an application depends on two services – ServiceA, and ServiceB, that the application cannot run when either of the services are down. To automate this behaviour, we are going to create two implementions of HeathIndicator interface – one for each service.

Spring Boot Custom Health Indicator Implementation for Service A

@Component
public class ServiceAHealthIndicator 
    implements HealthIndicator {

  private final String message_key = "Service A";
    
  @Override
  public Health health() {
    if (!isRunningServiceA()) {
      return Health.down().withDetail(message_key, "Not Available").build();
    }
    return Health.up().withDetail(message_key, "Available").build();
  }

  private Boolean isRunningServiceA() {
    Boolean isRunning = true;
    // Logic Skipped

    return isRunning;
  }
}
Code language: Java (java)

And, Spring Boot Custom Health Indicator Implementation for Service B

@Component
public class ServiceBHealthIndicator 
    implements HealthIndicator {
  
  private final String message_key = "Service B";

  @Override
  public Health health() {
    if (!isRunningServiceB()) {
      return Health.down().withDetail(message_key, "Not Available").build();
    }

    return Health.up().withDetail(message_key, "Available").build();
  }

  private Boolean isRunningServiceB() {
    Boolean isRunning = false;
    // Logic Skipped

    return isRunning;
  }
}
Code language: Java (java)

Note that, both HealthIndicator implementations have a Spring Steretype Annotation – @Component. Which is why, Spring will automatically locate and register these custom health checks.

We can now turn on our Application and execute the actuator’s ‘/actuator/health‘ endpoint and observe the response.

{
  "status":"DOWN",
  "details":{
    "serviceA":{
      "status":"UP",
      "details":{
        "Service A":"Available"
       }
    },
    "serviceB":{
      "status":"DOWN",
      "details":{
        "Service B":"Not Available"
      }
    },
    "db":{
      "status":"UP",
      "details":{
        "database":"H2",
        "hello":1
      }
    },
    "diskSpace":{
      "status":"UP",
      "details":{
        "total":250790436864,
        "free":36591120384,
        "threshold":10485760
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

As we can see in the snippet, the Health Check response additionally contains our custom health check statuses. Although, all other Health Checks are green, because of the ServiceB’s status our Application status is flagged DOWN.

Summary

This detailed tutorial covered all the details of Spring Boot Actuator Health Indicators. We learned about Spring Boot Actuator health check responses and how to enable a detailed view of internal health statuses. Then we had an overview of Spring Boot Actutor’s inbuilt HealthIndicators that are ready-to-use. In the last section, we implemented two custom health checks and obeserved the ‘/actuator/health‘ response to see how Spring Boot actuator cumulatively derives status of our application.

The source code of the examples used in this tutorial is available on our GitHub Repository.

---