Working with Spring Boot Actuators

The Spring Boot Actuator provides several endpoints in your application through which you can view the internals of your running application.

Through the Actuator, you can find out how beans are wired together in the Spring application context, determine what environment properties are available to your application, and get a snapshot of runtime metrics.

Enable Spring Boot Actuators

To enable the Actuator endpoints, you need include the spring-boot-starter-actuator starter dependency to your project. If you have Gradle based project, you can add the following dependency to your build.gradle file.

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-actuator
}

If you’re using maven, you can include the following dependency on your pom.xml file.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Once you have the dependency added to your application, Spring Boot’s auto-configuration will kick in when the application is running and Actuator will be enabled.

Run your application and visit http://localhost:8080/actuator/health

Actuator Endpoints

Spring Boot includes several built-in endpoints and lets you add your custom actuator endpoints.

Here is the list of available endpoints in Spring Boot:

Enable Actuator Endpoints

You can enable or disable each individual endpoint and expose them as per your requirement. All disabled endpoints are removed entirely from the application context.

By default, all endpoints except for shutdown are enabled. You can enable a specific endpoints using the management.endpoint.<endpoint_id>.enabled property.

For example, the following example enables the shutdown and info endpoint

management.endpoint.shutdown.enabled=true
management.endpoint.info.enabled=true

Exposing Actuator Endpoints

Since endpoints may contain sensitive information about your application, you should carefully consider what endpoint is expose them.

By default, only the health endpoint is exposed over HTTP. To change which endpoints are exposed we can use the include and exclude property.

#Include or exclude specific endpoints. Comma seperated endpoint names
management.endpoints.web.exposure.exclude=scheduledtasks
management.endpoints.web.exposure.include=info, health

#Exposes all actuator endpoints
management.endpoints.web.exposure.include=* 

Endpoint Caching

Note that, the spring boot actuator endpoints automatically cached for read operations that do not take any parameters. To configure the amount of time for which an endpoint caches a response, we can use the following property.

management.endpoint.beans.cache.time-to-live=10s

Implementing Custom Actuator Endpoints

To create a custom actuator endpoint, we need to create a class with @Component in combination with @Endpoint annotation.

The methods can be annotated with @ReadOperation, @WriteOperation, or @DeleteOperation and are automatically exposed over HTTPS.

Read Operation

The following example demonstrates, creating a custom actuator endpoint /foo-bar that supports read operation:

@Component  
@Endpoint(id = "foo-bar")
public class FeaturesEndpoint {

    @ReadOperation
    public Map<String, String> readOperation() {
        return Map.of("foo", "bar");
    }
}

Run your application and you will visit /actuator/foo-bar endpoint. It will return the following response:

{
    "foo": "bar"
}

Write Operation

We can pass the input parameter through the custom actuator endpoints as well using the @WriteOperation annotation.

@Component  
@Endpoint(id = "foo-bar")
public class FeaturesEndpoint {

    @ReadOperation  
    public Map<String, String> readOperation() {
        return Map.of("foo", "bar");
    }

    @WriteOperation
    public Map<String, String> writeOperation(String param1, String param2) {
        return Map.of("param1", param1, "param2", param2);
    }
}

Now, we can test the endpoint as follows;

curl --location 'http://localhost:8080/actuator/foo-bar' \
--header 'Content-Type: application/json' \
--data '{
    "param1": "Hello",
    "param2": "World!"
}'

Delete Operation

In conjunction with @ReadOperation, @WriteOperation we can also use @DeleteOperation, which maps to the HTTP DELETE request type.

@DeleteOperation  
public Map<String, Boolean> deleteOperation() {  
    return Map.of("success", true);  
}

Example:

curl --location --request DELETE 'http://localhost:8080/actuator/foo-bar'