Spring Boot for Cloud: Actuator

In previous articles, we talked about some features of Spring Boot that are very useful in the development phase of our system: we described simplified dependency management and API development, for instance. In this article, we are going to cover functionalities that are related to a production environment.

When a Spring Boot application is finally in production, it needs all the tools to manage and monitor it. This is especially important in complex scenarios like those related to microservice systems. Spring Boot provides an effective solution to provide the required functionalities, the Actuator. The Actuator is a Spring Boot module with a set of features available as HTTP or JMX endpoints, or even with a remote SSH shell.

The HTTP endpoints are available if we use a Spring Boot Web dependency, by the spring-boot-starter-web starter. In this article, we will show how to activate the Actuator module and describe the main features available with it, in the context of a web application.

Spring Boot Actuator

Activating the Spring Boot Actuator

The Spring Boot Actuator is a set of functionalities that are very useful in a production environment. It can be introduced in our project by the following starter:

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

A Spring Boot application configured with a spring-boot-starter-web and spring-boot-starter-actuator dependencies will expose a set of URL endpoints to manage, monitor,  and gather statistics of the running system. We show here some of the endpoints available:

• /actuator: It shows a list of the other endpoints
• /env: Shows properties from the application environment
• /health: Provides health info on system components
• /metrics: Shows statistics about memory, threads, and so on.
• /heapdump: Executes a dump of Java heap memory
• /shutdown: Can be used to perform a "graceful" shutdown. It is not available by default.

In the following sections, we will make a quick review focused mainly on the /health and /metrics endpoints, and some configurations required to properly use the actuator features.

Configuring the Actuator to Show All the Endpoints

To access the single endpoints we need a path starting with /actuator. For instance, to access the /health endpoint we have to use the following address:

http://localhost:8080/actuator/health

The /actuator path itself is supposed to show a list of all the available endpoints. With the actuator starter dependency and no other additional configuration in place, we will see that if we try to access the actuator endpoint only the /health endpoint will be available. In fact, If we run the application with the "mvn spring-boot:run" Maven command and enter the http://localhost:8080/actuator/health address in our browser, we will have the following result:

{
    "_links": {
       "self": {
          "href": "http://localhost:8080/actuator",
          "templated": false
       },
       "health": {
          "href": "http://localhost:8080/actuator/health",
          "templated": false
      },
      "health-path": {
         "href": "http://localhost:8080/actuator/health/{*path}",
         "templated": true
      }
   }
}

In order to show all the endpoints, we must include the following peace of configuration in the application.yaml  file:

management:
   endpoints:
      web:
         exposure:
            include: '*'

Or, in case we have an application.properties file instead, we will use the corresponding plain text version: "management.endpoints.web.exposure.include='*' ".

With the above configuration, if we start the application and access again /actuator endpoint we will see a complete list, as we can see in the following screenshot:

Securing the Spring Boot Actuator Endpoints

By default, the endpoints are not secured and are freely available without providing any credentials. To add a security layer, we have to add the following starter to the POM:

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

A further required step would be to configure a username and password in the application.yaml file (or application.properties):

spring:
   security:
      user:
         name: username
         password: pass

If we start the application again with the above configuration and try to access, for instance, the actuator endpoint, we will get the following:

By entering the username and password and clicking on the "Sing in" button, we will get again the list described in the previous section.

About the Spring Boot Actuator /health Endpoint, and How to Make It Show Detailed Information

The /health endpoint plays an important role in a production scenario: it allows a system administrator to quickly check if the application is in a healthy condition: if all its components are up, and if all the required resources, like for instance disk space, are available. If we start the application without any additional setup, we will see that by default the /health endpoint shows only generic status information:

{
   "status": "UP"
}

The status will be "UP" as long as all the application components and resources are up and available.  In order to get more detailed health information we have to add the following peace of configuration: 

management:
   endpoint: 
      health:
         show-details: always

If we then restart the application and access the /health endpoint again, we will obtain something like this:

As we can see, with the additional configuration described above, we have some more information, in this case about the status of an H2 DB instance and disk space. The service behind the /health endpoint uses specific health indicator classes to show all the information available for a particular component or resource. A number of predefined indicators are available, for example DataSourceHealthIndicator and DiskSpaceHealthIndicator. 

It is also possible to define custom indicators, by extending the AbstractHealthIndicator abstract class and overriding the doHealthCheck method.

The Spring Boot Actuator /metrics Endpoint

The /metrics endpoint allows us to obtain various statistics about our running application. The main path http://localhost:8080/actuator/metrics shows a list of available metrics. As we can see in the following screenshot, we obtain a list of names. 

In order to access the details of a single metric from the list we must complete the path with its name. For instance, if we want to check how many classes were loaded into the Java Virtual Machine, we can use the following address: http://localhost:8080/actuator/metrics/jvm.classes.loaded, as shown in the screenshot below.

Conclusion

Moving a Spring Boot application into production requires all the functionalities to manage, assess the status and health of the running application, and gather detailed statistics. Spring Boot provides the features mentioned above, through the Actuator module described in this article.

A sample application is available at GitHub.