SpringTechnology

Spring Boot Actuator with Spring Boot 2

Guide to Spring Boot Actuator – Learn how to use, configure actuators and create custom actuators with the help of code Examples.

What is Spring Boot Actuator?

When you are running critical applications on Production environments, it is very important to ensure they are always up and running. Also, you want know when an application is in trouble and act upon quickly. Therefore, we need some sort of Monitoring and Management mechanism to analyse the Applications health. Without Spring Boot you have to use JMX and Managed Beans (MBeans). Otherwise, you have to write custom code which monitors the code components and send notifications.

Actuator is Spring Boot’s in-built Monitoring and Management Mechanism.

Moreover, each application get’s it without having to write a single line of code. When you enable actuator in your Spring Boot Application, the application exposes few additional HTTP endpoints. After that, you can query these endpoints to know many important things about your applications health. You can tie up these endpoints to any Monitoring and Notification tool.

Actuator is a production-ready feature of Spring Boot. Because, it is readily available to use for Production monitoring purpose. Similar to any other Spring Boot features it is very easy to enable and configure.

Enable Spring Boot Actuator

The way you enable actuator is very similar to any other configurable feature of Spring Boot. And that is, starter dependency.

Maven Users

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

Gradle Users

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

After this, you should see /heathand /infoare activated and available. Lets, test the /health endpoint now

➜  ~ curl http://localhost:8080/actuator/health
{"status":"UP"}%

By default, only /health and /info endpoints are available. While, spring boot disables rest of the endpoints as they are sensitive.
Because, they reveal sensitive information about your application.

However, you can enable all of the endpoints like this.

management:
  endpoints:
    web:
      exposure:
        include: '*'

Alternatively, you can enable only specific endpoints, keeping the others disabled.

management:
  endpoints:
    web:
      exposure:
        include: ["metrics", "beans"]

Here, you enabled the sensitive endpoints. However, your can make them secured by enabling username/password combinations for the endpoints. Visit to learn more: How to Secure Spring Boot Actuator Endpoints.

Predefined Endpoints

Spring Boot provides bunch of pre-defined endpoints, which are ready to use. Now, we will look at some of them below. Unlike, spring boot 1,x, Spring Boot 2 actuator endpoints have a default context of /actuator. Hence, instead of doing /heath you will have to use /actuator/health.

  • /auditevents: Exposes audit events information for the current application.
  • /beans: Returns list of all spring beans in the application.
  • /caches: Gives information about the available caches.
  • /health: Provides applications health information.
  • /conditions: Provides list of conditions those were evaluated during auto configurations.
  • /configprops: Returns list of application level properties.
  • /info: Provides information about current application. This info can be configured in a properties file.
  • /loggers: Displays logging configurations. Moreover, this endpoint can be used to modify the configurations.
  • /headdump: Produces a head dump file and returns it.
  • /metrics: Returns various metrics about the application. Includes memory, heap and threads info. However, this endpoint doesn’t return any metrics. While, it only returns list of available metrics, the metrics names can be used in a separate request to fetch the respective details. For instance, /actuator/metrics/jvm.memory.max like this.
  • /scheduledtasks: Returns a list of Scheduled tasks in the application.
  • /httptrace: Returns last 100 http interactions in the form of request and response. Including, the actuator endpoints.
  • /mappings: List of all Http Request Mappings. Also includes the actuator endpoints.

Spring Boot Actuator Custom Endpoints

Spring Boot Actuator provides many useful endpoints. However, sometimes your application may need to reveal specific information. That is why, Spring Boot provides an easy way to add your custom endpoints.

Controller Endpoints

The Spring Boot Actuator Controller endpoints can be accessed only via Spring MVC or Spring WebFlux.

These controller endpoints can be added using @RestControllerEndpoint or @ControllerEndpoint. Where, the former is used for Rest Controllers and the later is used for the Spring MVC Controller.

@Component
@RestControllerEndpoint(id = "custom-rest-endpoint")
public class CustomRestActuator {

    @GetMapping
    public Map<String, String> get() {
        Map<String, String> map = new HashMap<>();
        map.put("server.date", LocalDate.now().toString());
        map.put("server.time", LocalTime.now().toString());
        return map;
    }

    @PostMapping
    public String post(@RequestBody  String request) {
        return "We have received your request: " + request;
    }
}

First, lets test the GET endpoint first

➜  ~ curl -X GET \
  http://localhost:8080/actuator/custom-rest-endpoint \
  -H 'Postman-Token: b47f31cc-3171-4fe2-8d28-b1244ccc6557' \
  -H 'cache-control: no-cache'

--
{"server.date":"2019-02-22","server.time":"09:31:06.892"}

Now, test the post endpoint.

➜  ~ curl -X POST \
  http://localhost:8080/actuator/custom-rest-endpoint \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 4b337573-ed7c-48f4-b281-c8c53f47dde8' \
  -H 'cache-control: no-cache' \
  -d '{
"request":"This is my request"
}'

---
We have received your request: {
"request":"This is my request"
}

Web Endpoints

You can add web endpoints using @Endpoint, @WebEndpoint, or @EndpointWebExtension annotations. Moreover, these endpoints are available over HTTP using Spring MVC, Spring WebFlux, or Jersey.

This time, Let’s see any example of using @Endpoint.

@Component
@Endpoint(id = "custom-endpoint")
public class ServerTimeActuator {

    @ReadOperation
    public Map<String, String> readOperation() {
        Map<String, String> map = new HashMap<>();
        map.put("server.date", LocalDate.now().toString());
        map.put("server.time", LocalTime.now().toString());
        return map;
    }

    @WriteOperation
    public String writeOperation() {
        // Implementation skipped
        return "";
    }

    @DeleteOperation
    public String deleteOperation() {
        // Implementation skipped
        return "";
    }
}

Now, lets test the GET endpoint

➜  ~ curl -X GET \
  http://localhost:8080/actuator/custom-endpoint \
  -H 'Postman-Token: d26ab39f-36bf-4165-b00c-855b2dbfca9d' \
  -H 'cache-control: no-cache'

--
{"server.date":"2019-02-22","server.time":"09:44:32.762"}

Summary

In This Spring Boot 2 Tutorial, you learnt about Spring Boot Actuators. To sum up, you learnt what is actuator, reasons to use actuator, and most of the ready to use actuators provided by Spring Boot. In addition, you also learnt how to write your own actuators using @Endpoint and @RestControllerEndpoint.

To keep learning about actuators visit our next tutorial How to Secure Spring Boot Actuator Endpoints

The source code examples used here are available at GitHub.