How do you expose custom endpoints in Spring Boot Actuator?

Table of Contents

• Introduction
  • Step-by-Step Guide to Exposing Custom Endpoints
    • 1. Add the Actuator Dependency
    • 2. Create a Custom Endpoint
      • Method 1: Using @Endpoint Annotation (Recommended)
      • Method 2: Implementing AbstractEndpoint
    • 3. Expose the Custom Endpoint via Configuration
    • 4. Accessing the Custom Endpoint
    • 5. Securing Custom Endpoints
  • Practical Example of Custom Endpoint Use Case
• Conclusion

Introduction

Spring Boot Actuator provides a set of built-in endpoints for monitoring and managing applications. These include health checks, metrics, environment properties, and more. However, there are times when you may need to expose custom endpoints to monitor application-specific functionality, provide custom metrics, or expose business-specific information. Spring Boot Actuator allows you to create and expose custom endpoints with minimal configuration.

In this guide, we’ll explain how to expose custom endpoints in Spring Boot Actuator, including code examples and configurations.

Step-by-Step Guide to Exposing Custom Endpoints

To expose custom endpoints in Spring Boot Actuator, you need to create a Spring-managed bean that implements one of the available endpoint types, such as Endpoint or AbstractEndpoint. You can then register these endpoints with the Spring context, and they will be exposed via the Actuator.

1. Add the Actuator Dependency

First, ensure that you have the spring-boot-starter-actuator dependency in your project. This starter will automatically include all necessary Actuator modules.

For Maven (pom.xml):

For Gradle (build.gradle):

2. Create a Custom Endpoint

There are different ways to create custom endpoints in Spring Boot. Below, we’ll cover two common methods: using the @Endpoint annotation (for modern Spring Boot versions) and implementing the AbstractEndpoint class.

Method 1: Using @Endpoint Annotation (Recommended)

Spring Boot Actuator provides the @Endpoint annotation, which is a simpler and more modern way to expose custom endpoints. You can create a class annotated with @Endpoint and use the @ReadOperation and @WriteOperation annotations to define operations for the endpoint.

Example:

Let’s say you want to create a custom endpoint that provides information about the application’s current status.

In this example:

• @Endpoint(id = "status"): Defines the custom endpoint with the ID status. The URL to access this endpoint would be /actuator/status.
• @ReadOperation: Marks the method getStatus() as a read operation that will be invoked when the endpoint is accessed.

Method 2: Implementing AbstractEndpoint

Before the @Endpoint annotation was introduced, custom endpoints were often created by extending the AbstractEndpoint class. This method still works in Spring Boot 2.x and allows for more flexibility if needed.

Example:

In this example:

• CustomEndpoint extends AbstractEndpoint<String>, and you override the invoke() method to define the response for the endpoint.
• The endpoint is exposed with the ID customEndpoint, which would be available at /actuator/customEndpoint.

3. Expose the Custom Endpoint via Configuration

By default, Actuator exposes certain endpoints such as /health, /metrics, and /info. You can configure the exposure of custom endpoints in the application.properties or application.yml file.

To expose your custom endpoint, modify the following in application.properties:

This ensures that both the status and customEndpoint are included in the Actuator's exposed endpoints.

Alternatively, you can use application.yml for configuration:

4. Accessing the Custom Endpoint

Once the custom endpoint is created and configured, you can access it via HTTP, just like other Actuator endpoints. Assuming your Spring Boot app is running locally on port 8080, the URLs for your custom endpoints would be:

• For the status endpoint:
  http://localhost:8080/actuator/status
• For the custom endpoint:
  http://localhost:8080/actuator/customEndpoint

You should see responses like:

• For /actuator/status:
  Application is running smoothly!
• For /actuator/customEndpoint:
  This is a custom endpoint response!

5. Securing Custom Endpoints

It's important to secure your custom endpoints to avoid exposing sensitive information in production environments. You can use Spring Security to secure the Actuator endpoints.

For example, to secure your endpoints:

1. Add Spring Security dependency:

2. Configure security settings in application.properties:

3. Secure the endpoints with HTTP basic authentication or OAuth, depending on your needs.

Practical Example of Custom Endpoint Use Case

Let’s say you want to expose an endpoint that provides metrics for the current number of active users in your application. Here’s how you could expose it via a custom Actuator endpoint.

Step 1: Create the Custom Endpoint

Step 2: Expose the Endpoint

In application.properties:

Step 3: Access the Endpoint

Once your Spring Boot application is running, you can access the custom endpoint to view the active users:

Conclusion

Exposing custom endpoints in Spring Boot Actuator is a simple yet powerful way to monitor and manage your application. Whether you need to expose custom metrics, application status, or business-specific information, Spring Boot makes it easy to define and expose your endpoints using the @Endpoint annotation or AbstractEndpoint class. Remember to configure which endpoints to expose via the application.properties file and secure them to prevent unauthorized access in production environments. By utilizing these custom endpoints, you can tailor the monitoring and management of your application to fit your specific needs.