Spring boot Actuator Example – Integration with rest service

Spring Boot Actuator is an essential tool for managing and monitoring Spring Boot applications, providing developers with the ability to gain insights into their applications’ health, metrics, and configuration. In this article, we’ll delve into the features of Spring Boot Actuator, discuss its various endpoints, and explore how to set up and configure Actuator for optimal performance.

What is Spring Boot Actuator?

Spring Boot Actuator is an extension of the Spring Boot framework that simplifies the management and monitoring of Spring Boot applications. It provides production-ready features, such as health checks, metrics, environment information, and more, allowing developers to quickly assess their applications’ state and perform management tasks with ease. This makes it simpler for operations teams to monitor, troubleshoot, and maintain applications in production environments.

Key Features of Spring Boot Actuator

Spring Boot Actuator offers several powerful features that make it a valuable tool for developers and operations teams. Some of these features include:

  • Health Checks: Actuator provides built-in health checks that can be used to monitor the status of application components, such as database connections, message queues, and more. This helps ensure that your application is running optimally and can quickly identify potential issues.
  • Metrics: Actuator collects and exposes various metrics about your application, such as memory usage, request counts, and response times. This information can be invaluable for understanding your application’s performance and identifying areas for improvement.
  • Auditing: Actuator supports auditing capabilities, allowing you to track user activities and events within your application. This can be useful for security and compliance purposes.
  • Environment Information: Actuator provides detailed information about your application’s environment, including configuration properties, system properties, and environment variables. This can be helpful for troubleshooting and diagnosing issues.

Spring Boot Actuator Example

Adding actuator to an existing rest-service

In this post, we are going to add spring boot actuator to an existing webservice which we created in this article.

That article outlined how to create a web-service that provides a REST API to manage a collection of films. The client can retrieve the list of films in the collection along with their year of release and other details. We can add films to it, modify individual films’ attributes as well as delete films from it. You can get the source-code here or use your own project for this post. Specifically, the rest of the post assumes a Jersey / Spring MVC web application or webservice that is built using Spring 2.x and setup as a Maven project.

In order to add the actuator endpoints, we only need to edit the pom.xml file. This involves one simple step of adding the spring-boot-actuator dependency to our pom.xml. Open pom.xml and add the below dependency (irrespective of the Boot version):

When you save pom.xml file, you will notice Maven downloading the necessary dependencies in the background (check progress tab in STS). Now that our webservice is ready after adding the Spring-boot-Actuator dependency, we can run our application by right-clicking on our project and selecting “Run As…” -> “Spring Boot App”. The embedded Tomcat server will be launched and the webservice will be deployed.

Run JerseyFilms as Spring Boot App
Run JerseyFilms as Spring Boot App

Now we can access the web-service by pointing our browser at http://localhost:8080/films or by using Postman.

Postman invokes GET on the REST API at http://localhost:8080/films
Access REST API using Postman

Try accessing http://localhost:8080/actuator/health.

Point Browser to actualtor/health an HTTP Endpoint exposed by spring boot actuator
Access Spring Boot actuator endpoint

This is one of the several endpoints automatically provided by Spring boot Actuator. All the HTTP end-points added by spring boot actuator are available under the base URI /actuator by default. There are more endpoints with varied functionality and each can be customised and extended. We will walk-through these details in the rest of the post.

History of Spring boot Actuator

Spring Boot Actuator is a sub-project of Spring Boot, a widely-used framework for building stand-alone, production-ready applications with minimal configuration. While it is challenging to pinpoint the exact point in history when Spring Boot Actuator came into existence, it is closely tied to the history of the Spring Boot project itself.

Spring Boot was first introduced in 2013 by Phil Webb and Dave Syer, both from Pivotal (now part of VMware). The primary goal of Spring Boot was to simplify the process of creating and deploying Spring applications by providing pre-configured templates, embedded servers, and other tools to streamline development.

Spring Boot Actuator emerged as an extension to Spring Boot, aimed at simplifying the monitoring and management of Spring Boot applications. It was introduced to address the growing need for better observability and operational control over applications, as microservices architectures and cloud deployments became more prevalent.

Spring Boot Actuator provides production-ready features such as health checks, metrics, auditing, and environment information, allowing developers to quickly assess the state of their applications and perform management tasks with ease. These capabilities make it easier for operations teams to monitor, troubleshoot, and maintain Spring Boot applications in production environments.

Since its introduction, Spring Boot Actuator has evolved alongside Spring Boot, with regular updates and improvements to its features. The development team behind Spring Boot Actuator continues to focus on enhancing its functionality and making it even more valuable for developers and operations teams managing Spring Boot applications.

Since our project uses JDK 8 and Spring Boot 2, we are using the 2.X version of the Spring boot Actuator which is the 2nd generation.

The 1.X version of Spring boot actuator, available since the first Spring boot release (Apr 2014), follows a Read/Write model, where we can get the health of our app or change our logging configuration, gracefully turn off our app etc. by either reading from it or writing to it. It requires Spring MVC to expose the end points through HTTP regardless of how the rest of the app is designed. The 1.X actuator has its own model to provide security by taking advantage of spring security constructs which should be configured independently.

The 2.X version released with Spring Boot 2 (early 2018) differs from the 1.X actuator by not being tied to Spring MVC. The 2.X actuator also has better defaults and simpler security configuration. It requires Java 8 or later.

In 2.X Actuator, most endpoints are not public and are disabled over HTTP. Only two endpoints, namely /info and /health, are enabled by default and publicly available. Other endpoints are senstive and require a username/password to access over HTTP if web security is enabled, or not exposed over HTTP as sensitive endpoints are not exposed publicly.

Spring Boot Actuator endpoints

A few commonly used endpoints provided by Boot 2.X Actuator are enlisted below:

Endpoint name Purpose
/auditevents Exposes audit events like user login/logout
/beans Returns all beans configured in the Bean factory
/conditions Creates a report of conditions built around auto-configuration
/configprops Displays a list of all configuration properties
/env Returns the present environment properties
/health Returns health of the current application
/threaddump Performs a thread dump of the JVM
/info Displays info about the application
/logfile Returns logs of the application
/loggers Shows the logger configuration logged in the application
/metrics Displays metrics information(generic and custom) of the application
/shutdown Allows gracefull shutdown of the application
/sessions Displays last few HTTP sessions of the Spring session
/flyway Shows details about Flyway DB migration

For the complete list of Actuator endpoints, have a look here.

Configuring the endpoint properties

Spring Boot Actuator is richly customizable to fit every application / user need. The URL and endpoint properties are configured or customised by modifying application.properties in (src/main/resources). Below is the modified application.properties for our project.

The first line selects all end-points for making available through HTTP. Although in this exercise we are only interested in HTTP end-points, actuator also provides access over JMX. By default, most endpoints are enabled (meaning active) but only the health and info end-points are exposed over HTTP – this line makes all enabled end-points accessible over HTTP.

The 2nd line sets all end-points to be enabled by default and the 3rd line disables the env endpoint – this is an example to illustrate how individual end-points can be disabled. Also an application can adopt a more conservative strategy of setting enabled-by-default to false and use one-liners like line 8 for every end-point that it would like to deliberately enable. The correct choice for the approach would depend on the application context.

The next 2 lines change the base-path – /actuator is the default and if there is context mapping, e.g., in a Spring-MVC app then base-path is changed to the context path, but it can also be set in application.properties as shown here. The last line sets the verbosity of the /health end-point. This is a parameter that is specific to health. End-points can provide such attributes for customising their behaviour.

In case spring-security is enabled in the app, then all the endpoints are sensitive by default (except health). We would need to add custom security configuration that allows unauthenticated access to the endpoints as shown below or provide an alternate security configuration use RequestMatcher objects that select specific users or roles. For more on this see this section of actuator docs.

Additionally management.server.port can be set in application.properties to set the HTTP port for actuator end-points. These settings are not needed in our app as of now but head here to learn how to secure a webservice.

Customizing endpoints

In general each endpoint can be customized using three properties, namely:

  1. id – name of this endpoint when accessed over HTTP (URI)
  2. enabled -if true, endpoint can be accessed, else cannot be accessed
  3. sensitive – if true, needs authorisation for access

Now, each endpoint can be configured using the below format:

endpoints.[name of the endpoint].[property that needs to be customised]=[value]

In addition to above three properties each end-point may expose custom properties which are documented here.

Extending endpoint functionality

It’s easy to extend existing end-points to add information specific to our application. For example, Spring Boot Actuator provides auto-configuration for Micrometer, so we can easily add counters and gauges. In our example, we will add 4 new end-points within the /metrics to display the current size of the films database (id=filmsdb.size) and count the number of POST (id=filmsdb.adds), PUT (id=filmsdb.mods) and DELETE (id=filmsdb.deletes) API requests made. Of course in a real-world application the metrics names may be prefixed by an FQDN or other namespace qualifier to prevent collision.

In order to achieve this extension, we modify the FilmService class by injecting a MeterRegistry object and registering a gauge for the size of the films database and 3 counters – one each for adds, mods and deletes. The source code of the modified file is below.

Notice how spring boot takes care of dependency injection for us so we don’t have to worry about the life-cycle of the MeterRegistry object. Run the application we can now see the new data being reported under metrics (remember the actuator endpoints are accessible at localhost:8080/admin). Below is a screenshot of the API being accessed using curl – curl or wget provide simple yet flexible & powerful command-line based access to REST APIs that can come handy in automating tests or quickly accessing an API even on remote systems that don’t have browsers etc., installed. Using grep we highlight the newly added metrics endpoints in the curl output.

Using curl to query metrics endpoint including newly added extensions
Query metrics endpoint including newly added extensions

Norice how the counter values for adds, mods and deletes correlate with the current size of the database. We had added 4 movies and deleted 1 so the database size is now 3.

Next we extend the health indicator with a custom indicator class that reports the Genres which are active in the database. For this, we create a new class called ActiveGenreCollector in the com.javagists.jerseyfilms.controller package. Source code is below. This class implements the HealthIndicator interface and is decorated with the @Component tag. Thus, spring-boot automatically adds this to the health indicator end-point (configured at localhost:8080/admin/status).

Now we run the app and notice that the output from our newly added end-point is part of the response.

Spring Boot actuator health endpoint shows additional information.
Extended health endpoint in action

Also see how diskspaceusage is reported automatically. This is one of the auto-configured health indicators that gets picked up. There are several such indicators that are auto-configured based on application configuration (e.g., if you have MongoDB dependency in your app, a MongoHealthIndicator is added to the end-point automatically). More details here.

Adding a new actuator end-point

Finally we add a brand-new actuator end-point that outputs the genre-wise distribution of movies in our database. For this we add a new class with @WebEndpoint decorator and implement the necessary methods in it. The source for this GenreDistribution.java is below.

Now running our application exposes a new end-point at http://localhost:8080/admin/genre (the suffix as specified in id parameter of the @WebEndpoint decorator. The HTTP GET method on this endpoint is mapped to the Java method having the @ReadOperation decorator, i.e., the getGenreDistribution() method which simply iterates through the films list, counts the occurrence of each genre and returns a HashMap with genre-wise count. Spring boot takes care of auto-converting this into JSON, which is then returned as response to the request. Below is a session showing its output.

Postman session accessing the newly added genre endpoint in spring boot actuator.
A new Endpoint added to Spring Boot Actuator!

Summary

In this post we looked at adding Spring boot actuator to a spring boot project. We looked at the actuator end-points functionality and how they can be customized and extended including adding new end-points. These administrative end-points are immensely valuable in monitoring and maintaining production applications and spring-boot-actuator provides them essentially for free with rich customization possibilities. We hope you are able to leverage these advanced features to make your web applications and services robust and maintainable.

The source code for this project can be downloaded here. Also a Postman collection with a collection of requests to exercise the JerseyFilms API and the actuator endpoints is available here. Go ahead and give it a spin!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.