How do you implement custom health indicators?

Table of Contents

• Introduction
  • What is a Health Indicator?
  • Steps to Implement a Custom Health Indicator
    • 1. Add Spring Boot Actuator Dependency
    • 2. Create a Custom Health Indicator
    • 3. Register the Health Indicator
    • 4. Expose the Health Check Endpoint
    • 5. Test the Custom Health Indicator
    • 6. Additional Custom Health Indicators
• Conclusion

Introduction

Spring Boot's Actuator module provides a powerful feature for monitoring your application, including an out-of-the-box /actuator/health endpoint that reports the application's overall health. However, sometimes the default checks (like database or disk space health) might not cover specific checks unique to your application or services. To address this, you can implement custom health indicators that evaluate the health of specific components or services in your application.

In this guide, we’ll show you how to implement custom health indicators using Spring Boot Actuator to monitor different aspects of your application’s health.

What is a Health Indicator?

A health indicator is a component in Spring Boot that implements the HealthIndicator interface. This interface has a method called health() that you must implement. The method should return an instance of Health, which indicates the health status of a particular component or service in your application.

A custom health indicator can be used to check the health of specific services, databases, or even external APIs that your application depends on. You can return a Health.up(), Health.down(), or Health.outOfService() status depending on the check results.

Steps to Implement a Custom Health Indicator

1. Add Spring Boot Actuator Dependency

If you haven't already, add the Spring Boot Actuator dependency to your project. This will allow you to access the health check endpoint and create custom health indicators.

**pom.xml** for Maven:

**build.gradle** for Gradle:

2. Create a Custom Health Indicator

To create a custom health indicator, you need to implement the HealthIndicator interface. Let’s create a custom health indicator that checks the availability of an external API service.

Example: Custom Health Indicator for an External API

In this example, we’re using RestTemplate to make an HTTP GET request to an external API. If the API responds with "OK", we mark it as "UP", otherwise "DOWN". If the request fails due to an exception, it’s marked as "DOWN" with the exception details.

3. Register the Health Indicator

In Spring Boot, any component annotated with @Component is automatically registered as a Spring bean. The custom health indicator ExternalApiHealthIndicator will automatically be detected and registered by Spring Actuator as long as it's annotated with @Component.

4. Expose the Health Check Endpoint

If you haven’t already, expose the health check endpoint by configuring the application.properties or application.yml file.

Example (**application.properties**):

You can also expose all Actuator endpoints like this:

5. Test the Custom Health Indicator

Once your application is running, you can test the health check endpoint at:

If the external API is reachable and healthy, the response will look like this:

If the external API is unreachable, the response will look like this:

6. Additional Custom Health Indicators

You can implement as many custom health indicators as you need. For example, if you want to check the database connection or the availability of a specific service, you can implement separate health indicators for each.

Example: Custom Health Indicator for Database Connection

This example checks the database connection to ensure it is reachable and valid.

Conclusion

Custom health indicators in Spring Boot provide a flexible and powerful way to monitor the status of specific services or components within your application. By implementing the HealthIndicator interface, you can easily add custom logic to check the health of external APIs, databases, or other services. Spring Boot Actuator automatically registers these indicators, making it simple to integrate into your application’s health monitoring strategy. You can expose these custom checks through the /actuator/health endpoint and make them an integral part of your application’s observability.