Guide to Spring Boot Actuator – Learn how to use, configure actuators and create custom actuators with the help of code Examples.
Tutorial Contents
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.
Learn more:
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 /heath
and /info
are 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.