Custom Health Check in Spring Boot Actuator

Quick guide to Custom Health Indicator with Spring Boot Actuator – with help of actual examples.

Enable Health Endpoint

Health is an important endpoint of Spring Boot Actuator.
It is useful to know the health of an application at realtime. You have to add a starter dependency to enable the endpoints.

 compile("org.springframework.boot:spring-boot-starter-actuator")

Now, you can verify that the /heath is working.

➜  ~ curl -X GET \
  http://localhost:8080/actuator/health \
  -H 'Postman-Token: dcc9266f-a6c9-4b9e-b8d4-fc099fbe38c7' \
  -H 'cache-control: no-cache'

---
{"status":"UP"}

Detailed View of /heath

By default, the health endpoint shows cumulative health information from many components in your application. However, you can enable a detailed view by setting a property.

management:
  endpoint:
    health:
      show-details: always

Then, you should see more detailed /health.

{
   "status":"UP",
   "details":{
      "db":{
         "status":"UP",
         "details":{
            "database":"H2",
            "hello":1
         }
      },
      "diskSpace":{
         "status":"UP",
         "details":{
            "total":250790436864,
            "free":36748783616,
            "threshold":10485760
         }
      }
   }
}

Pre-Defined Health Indicators

The above JSON response shows “db” and “diskSpace” checks. These checks are called as Health Indicators. Our application has a datasource. Therefore, Spring adds a “db” health indicator. While, the “diskSpace” health indicator is configured by default.

Spring Boot comes with number of pre-defined Health Indicators.
Now, we will take a look at some of them.

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

When, you use Mongo or Solr etc. in your Spring Boot application, Spring Boot automatically adds the respective Health Indicators.

Add Custom Heath Checks

Spring boot provides bunch of ready to use Health Indicators. However, you can add your own health indicator. For the same, you need to implement HealthIndicator interface.

As an example, lets consider your application talks to Service A (which is UP) and Service B (which is DOWN). If either of service is DOWN your application should be considered as Down. Therefore, we will write two Health Indicators.
Like this:

Health Indicator 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;
    }
}

Now, write Health Indicator 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;
    }
}

Finally, we will get below result from /health endpoint.

{
   "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
         }
      }
   }
}

Now, you should see our health indicators added to the response. Where, Service A is UP while Service B is DOWN. Hence, the overall health check is DOWN.

Summary

To sum up, in this tutorial you learnt about the Spring Boot Health Indicator and how to see the detailed view of Health Indicator. Also, you learnt that Spring Boot provides bunch of pre-defined Health Indicators and plugged in when you use the respective tool or technology. Finally, you wrote your own custom Health Indicator and learnt you can control the Health check of your Application.

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

---