A Guide to Spring Boot Actuator – Learn how to use, configure, and create custom actuators with the help of code Examples.
Tutorial Contents
What is Spring Boot Actuator?
When running a critical application in Production environments, it is important to ensure it is always up and running. Also, we want to know when an application is in trouble and act upon it quickly. Therefore, we need a Monitoring and Management mechanism to analyze the Application’s health. Without Spring Boot, we have to use JMX and Managed Beans (MBeans) and write custom code that monitors the code components and sends notifications.
The actuator is Spring Boot’s in-built Monitoring and Management Mechanism.
The actuator is a production-ready feature of Spring Boot. We can plugin Spring Boot Actuator in an application with zero configuration. The actuator exposes a few HTTP endpoints that we can use to query the Application’s health and take a few actions.
Learn more:
Enabling the Spring Boot Actuator
We need to add its starter dependency to enable the Spring Boot actuator.
Maven Users
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>Code language: HTML, XML (xml)Gradle Users
compile("org.springframework.boot:spring-boot-starter-actuator")Code language: Gradle (gradle)When we launch the Application, we can invoke the ‘/actuator/health‘ and ‘/actuator/info‘ endpoints.
~ curl http://localhost:8080/actuator/health
{"status":"UP"}Code language: Bash (bash)Although several other endpoints are available in the actuator, Spring Boot disables the rest as they may reveal sensitive information about the Application.
We can override this setting and enable all actuator endpoints from a Properties or YAML configuration.
management:
endpoints:
web:
exposure:
include: '*'Code language: YAML (yaml)Alternatively, we can enable only specific endpoints, keeping the others disabled.
management:
endpoints:
web:
exposure:
include: ["metrics", "beans"]Code language: YAML (yaml)We can also use Spring Security to secure the Spring Boot Actuator Endpoints.
Spring Boot Actuator Predefined Endpoints
Spring Boot provides a bunch of pre-defined endpoints which are ready to use. All the Spring Boot actuator endpoints start with the ‘/actuator‘ context root.
- /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 the Application’s health information.
- /conditions: Provides a list of conditions evaluated during auto configurations.
- /configprops: Returns list of application-level properties.
- /info: Provides information about the 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 a list of available metrics names. To fetch the metrics values, we can provide the name of the metrics, for example, ‘/actuator/metrics/jvm.memory.max‘.
- /scheduledtasks: Returns a list of Scheduled tasks in the Application.
- /httptrace: Returns the last 100 HTTP interactions in request and response, including the actuator endpoints.
- /mappings: List of all Http Request Mappings. It also includes the actuator endpoints.
Spring Boot Actuator Custom Endpoints
Spring Boot Actuator provides many useful endpoints. However, sometimes our Application may need to reveal specific information. That is why Spring Boot provides an easy way to add 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. The former is used for Rest Controllers, and the latter 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;
}
}Code language: Java (java)First, let’s test the GET endpoint first
~ curl -X GET \
http://localhost:8080/actuator/custom-rest-endpoint
{"server.date":"2019-02-22","server.time":"09:31:06.892"}Code language: Bash (bash)Now, try the post endpoint.
~ curl -X POST \
http://localhost:8080/actuator/custom-rest-endpoint \
-H 'Content-Type: application/json' \
-d '{
"request":"This is my request"
}'
---
We have received your request: {
"request":"This is my request"
}Code language: Bash (bash)Web Endpoints
We 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 an 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 "";
}
}Code language: Java (java)Now, let’s test the GET endpoint
~ curl -X GET \
http://localhost:8080/actuator/custom-endpoint
--
{"server.date":"2019-02-22","server.time":"09:44:32.762"}Code language: Bash (bash)Summary
In this Spring Boot Actuator guide, we learnt what an actuator is, the reasons to use actuators, and most of the ready-to-use actuators provided by Spring Boot. In addition, we also learnt how to write our actuators using @Endpoint and @RestControllerEndpoint.
To keep learning about actuators, visit our following tutorial, How to Secure Spring Boot Actuator Endpoints.
The source code examples used here are available in our Github Repository.