Spring Boot Actuator Tutorial Guide

By Dhiraj Ray, 09 February,2017   | Last updated on: 20 February,2017

Today, we will be discussing about spring boot actuator in great details. This post aims to provide complete tutorial guide for spring boot actuators. Starting from the overview, we will deep dive into actuator concepts, configuring actuator in spring boot applications, customizing endpoints, exposing custom endpoints and also override default security to the sensitive endpoints of spring boot actuator.

spring boot actuator

What is Spring Boot Actuator

Spring Boot Actuator is a sub-project of Spring Boot. It provides several production grade ready features to any spring boot application. Once it is configured in any spring boot application, it exposes a no. of REST endpoints out of the box. These REST endpoints can be consumed to manage and monitor your application. You can monitor your application health, application bean details, version details, thread dumps, logger details etc. without wrting any extra line of code.

Once spring actuator is configured in your project, you get 16 built-in endpoints to manage and monitor your application by default. The list of these endpoints are provided below. In case you require more control, you can also add your own endpoints. Not only this spring actuator also provide flexibility to rename the exisitng REST endpoints to any custom name you want.

Once these REST endpoints are exposed, anybody can consume it and manage your application. But this is not what we want. We want to restrict these endpoints to be consumed by authorized users only and Spring provides easy way to secure your REST endpoints. Spring boot provides sensitive defaults to true for all endpoints except /info and /health which requires username/password to be accessible over http.

Enabling Spring Boot Actuator

You can enable spring boot actuator feaure by including following dependency in your pom.xml. Once this dependency is added you can have access to /info and /health REST Endpoints without any authentication.

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

Different Actuator Endpoints Lists

Once actuator feature is enabled by including above maven dependency, following 16 endpoints are exposed out of the box by spring Boot actuator. Among the list of 16 endpoints, only /health and /info can be accessed and rest of the endpoints are disabled by default unless you enable it explicitly or include spring-boot-starter-security artifact as maven dependency.

1. actuator : It provides a hypermedia-based discovery page for the other endpoints. It is required to have Spring HATEOS on the classpath to enable it. By default it is sensitive and hence requires username/password for access or may be disabled if web security is not enabled.

2. auditevents: It exposes audit events information.

3. autoconfig: It displays an auto-configuration report showing all auto-configuration candidates.

4. beans: It displays complete beans configured in the app.

5. configprops: It displays a collated list of all @ConfigurationProperties.

6. dump: It performs a thread dump.

7. env: It exposes properties from Spring ConfigurableEnvironment.

8. flyway: It shows any Flyway database migrations that have been applied.

9. health: It shows application health information (when the application is secure, a simple ‘status’ when accessed over an unauthenticated connection or full message details when authenticated).

10. info: It displays arbitrary application info.

11. loggers: It shows and modifies the configuration of loggers in the application.

12. liquibase: It shows any Liquibase database migrations that have been applied.

13. metrics: It shows metrics information for the current application.

14. mappings: It displays a collated list of all @RequestMapping paths.

15. shutdown: It allows the application to be gracefully shutdown (not enabled by default).

16. trace: It displays trace information (by default the last 100 HTTP requests).

If you are also using spring mvc then other 4 additional endpoints such as docs, heapdump, jolokia and logfile can be used

Customizing Endpoints

You can customize each actuator endpoints in 3 different ways. You can enable or disable an endpoint, customize its sensitivity and its id. All these customization can be achieved by creating entries in application.properties

Following is an example to customize /metrics endpoint.

endpoints.metrics.id=mymetrics endpoints.metrics.sensitive=false endpoints.shutdown.enabled=true

Above customization will disable the metrics endpoint to be accessed at /metrics and it enables metrics endpoint to be accesses at new endpoint - /mymetrics. It will also make this metrics insensitive and hence it is not required any authentication to access the endpoint /mymetrics. Apart from this it also registers a shutdown hook for metrics endpoint.

Customizing Endpoints Globally

Above example of endpoint customization is valid for only metrics endpoint as we are only customizing the metrics endpoint related settings. You can also customize behaviour of all the endpoints with one time configurations by customizing endpoints globally. Following example marks all endpoints as sensitive except info.

endpoints.sensitive=true endpoints.info.sensitive=false
More detailed explanation on Spring Boot Actuator REST Endpoints with sample code base is explained in my another post - Spring Boot Actuator REST Endpoints Example

Securing Actuator Endpoints

Apart from 2 endpoints - /health and /info, all the other endpoints are sensitive by default. And also to have access to other endpoints apart from /health and /info, we require to have required authorization. To have access to non-sensitive endpoints you can either disable the sensitivity of these sensitive endpoints which is of course not recommended or secure it using spring security(recommended).

While dealing with Spring Boot, include following maven dependency in your pom.xml.

Once you include this dependency to pom file, all of your rest endpoints including application controllers endpoints will also be secure by Spring basic authentication and to avoid this you require some extra effort which I have discussed in Securing Spring Boot Actuator Endpoints with Spring Security

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

In spring boot application including above dependencies will by default provides inbuilt form based authentication with userid as user and random generated password. Following entries are then required to enable the basic security to your sensitive endpoints.

management.security.enabled=true security.user.name=act security.user.password=act management.security.roles=ACTRADMIN

Define Custom Actuator Endpoints

This is the last section of this guide on spring boot actuator endpoint where we will be creating a new custom endpoint and define some custom functions for this endpoint. Spring Actuator provides an abstract class AbstractEndpoint which you can extend to define your own custom endpoint.

Following is a simple example of creating a custom actuator endpoint that can be accessed at localhost:8080/showendpoints

ListEndPoints.java
import org.springframework.boot.actuate.endpoint.AbstractEndpoint; import org.springframework.boot.actuate.endpoint.Endpoint; import org.springframework.stereotype.Component; import java.util.List; @Component public class ListEndPoints extends AbstractEndpoint> { private List endpoints; public ListEndPoints(List endpoints) { super("showendpoints"); this.endpoints = endpoints; } @Override public List invoke() { return this.endpoints; } }

Conclusion

I hope this article served you that you were looking for. If you have anything that you want to add or share then please share it below in the comment section.

References

Spring Actuator Docs

Suggest more topics in suggestion section or write your own article and share with your colleagues.

Is this page helpful to you? Please give us your feedback below. We would love to hear your thoughts on these articles, it will help us improve further our learning process.

Further Reading: