Monitoring Spring Boot projects with Actuator

featured_image

Shipping an application to the production requires reliable mechanisms responsible for auditing, health checks, and metrics collection. Fortunately, with Spring Boot we can apply those features effortlessly and monitor an app with Actuator.

What we’re going to build

In this article you can read how to:

  • add Actuator to a Spring Boot project and use its HTTP endpoints;
  • enable/disable chosen endpoints;
  • configure the info endpoint to show some data already defined in the project’s pom.xml file;
  • configure the health endpoint to display more details;
  • secure the health details and other endpoints.

Meanwhile, you can clone the example spring-boot-log4j-2-scaffolding project from my GitHub repository and test it locally.

Add Actuator to a Spring Boot project

If you use Maven, add the Spring Boot Starter Actuator maven dependency to the pom.xml file:

You can find how to add the dependency if you use Gradle in the documentation. The plugin is auto-configured. That’s why we can monitor a Spring Boot app with Actuator so effortlessly.

Actuator endpoints

Actuator makes monitoring straightforward and provides a deep insight due to the comprehensive and extendable set of configurable endpoints. To begin with, run the application and go to http://localhost:8080/actuator/ to see the default endpoints:

default Actuator endpoints

What details of a Spring Boot app you can monitor with default Actuator settings

Almost all endpoints (except for http://localhost:8080/actuator/shutdown) are enabled. However, they won’t be listed under the /actuator endpoint, unless you explicitly expose them. In order to see all enabled endpoints, expose them in the application.properties file with the following line:

After that, restart the application and visit http://localhost:8080/actuator/. As a result, you’ll be able to see a new, longer response:

how to find all Actuator endpoints

How to configure endpoints availability

Similarly, if you want to enable only a few endpoints, you have to modify the app’s properties as follows:

In other words, we:

  • disabled all endpoints;
  • enabled and exposed only one – info;

As a result, we’ll see the following response after rebuilding the app:

Monitor Spring Boot health with selected Actuator endpoint

Disabling an endpoint removes it from the application context completely. On the other hand, you can use only the exclude and include properties to configure the endpoints availability. Therefore, they can remain in the application context, even though they are hidden from a user. I’m going to configure the management.endpoints.web.exposure.include property. As a result, Actuator will serve the info, health and metrics endpoints in the browser and the rest of the endpoints will keep their default – enabled state:

Consequently, my chosen endpoints are listed on the screenshot below:

monitor Spring Boot info, health and metrics with chosen Actuator endpoints

Finally, if you want to exclude an enabled endpoint, pass it to the management.endpoints.web.exposure.exclude property.

Configure the info endpoint

The http://localhost:8080/actuator/info path returns an empty json by default. We’re going to configure what info should be displayed. For that purpose, I’m going to add the same information that are defined in the pom.xml file, as explained in the docs:

You can automatically expand properties from the Maven project by using resource filtering. If you use the spring-boot-starter-parent, you can then refer to your Maven ‘project properties’ with @..@ placeholders (…).

https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto-automatic-expansion-maven

According to the documentation, I can add to the properties the following lines:

After restarting the app, I can see the data returned by the info endpoint:

project details from maven in Actuator info endpoint

Monitoring the health of your app

The http://localhost:8080/actuator/health endpoints returns a simple health check by default:

see basic status in Actuator health endpoint

Later in this post, we’re going to add details to its response in a secure manner.

The default endpoint list includes actuator/health/{*path} as well. This gives you the possibility to:

Browse the app metrics

On the screenshot below you can see some of the available metrics for the application:

Spring Boot metrics that you can monitor with Actuator

In order to see a metric details, add its name to the /actuator/metrics endpoint:

verify selected Spring Boot  metric

Protect Actuator endpoints with Spring Boot security

At this point, all enabled and exposed endpoints are available for everyone. In reality, you don’t want to expose such sensitive information to outsiders.

Enable Spring Boot security

Add the Spring Boot Starter Security dependency to your pom.xml file:

For the sake of simplicity, I set up default credentials in the application.properties file:

Remember to override those simple values when shipping to production!

Verify whether endpoints are secured

Restart the application and visit http://localhost:8080/actuator. You’ll see the login form:

login form

All endpoints except for info and health are available only after you’d successfully singed in. However, you can customize security configuration to:

  • enable unauthorized access to some endpoints;
  • only allow users with a certain role to access specified endpoints.

Get more detailed health information

Since the Actuator endpoints are secured, we can configure the /actuator/health endpoint to provide more details for an authorised user.

Monitor health components

Configure the management.endpoint.health.show-components property, so that you can see the health components:

Consequently, the health output will look like on the screenshot below:

Actuator health components

Monitor health details

For more detailed response, use the management.endpoint.health.show-details property instead:

On the following screenshot you can see that the response includes more data:

Actuator health details
Most importantly, don’t forget to take care of logging. Checking health isn’t enough when you can’t browse logs (e.g. in Kibana) to actually debug what happened.

To sum up, including Actuator in a project is a first step towards responsible metrics management. Especially since it provides auto-configuration and dependency handling for Micrometer – a metrics instrumentation library enabling transparent integrations with the most popular monitoring systems.

In addition, you can find the code that enables us to monitor Spring Boot with Actuator in the commit f860e3be2125c78527ab74306ec0f9c17e658fd4.

Learn more on how to monitor Spring Boot with Actuator

Photo by Retha Ferguson from Pexels

Leave a Reply

Your email address will not be published. Required fields are marked *