Spring Boot Actuator in Spring Boot 2.0

In this post, we will take a closer look at Spring Actuator and highlight some changes in Spring Boot 2.0. We will discuss some of the endpoints and will create a custom endpoint to our application. The sources can be found at GitHub.

What Is Spring Boot Actuator?

Spring Boot Actuator supplies several endpoints in order to monitor and interact with your application. It does so by providing built-in endpoints, but you are also able to build your own endpoints. In the next sections, we will create a dummy application, enable the Actuator endpoints, provide the version and build information to it, add security to the endpoint, and customize an endpoint to our needs.

Create the Project

First of all, we will create our Spring project. As always, we do so by means of the Spring Initialzr. We select the following dependencies:

• Spring Boot 2.0.0
• Java 9
• Web for using Spring MVC
• Actuator in order to add the dependency for Spring Actuator — what this post is all about, of course

When we take a closer look at the POM, we notice that the following dependency for Spring Actuator is added:

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

In order to have some functionality in our application, we create a simple RestController which simply returns a string 'Hello Spring Boot Actuator'. The controller is the following:

@RestController
public class HelloActuatorController {

    @RequestMapping(value = "/helloactuator", method= GET)
    public String helloActuator() {
        return "Hello Spring Boot Actuator";
    }

}

Run the Spring Boot application and invoke the URL http://localhost:8080/helloactuator, which returns the string in the browser.

Actuator Endpoint

Now that we have set up our simple application, it is time to take a look at what Spring Actuator has to offer. In the browser, go to the URL http://localhost:8080/actuator/. This shows us an overview of the exposed Actuator endpoints. Compared to Spring Boot 1, the Actuator endpoints all reside after this Actuator endpoint. This should prevent naming collisions with your own endpoints whenever they would have the same name as Actuator endpoints. Invoking the URL returns us the following:

{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "info": {
            "href": "http://localhost:8080/actuator/info",
            "templated": false
        }
    }
}

As you can see, only 3 Actuator endpoints are exposed by default. In order to expose more endpoints, we need to add an include or exclude configuration to the application.properties file. We will add all endpoints to the configuration, but you can also limit the exposed endpoints by means of a comma-separated list. In order to expose all endpoints, we add the following configuration to the application.properties file:

management.endpoints.web.exposure.include=*

Restart the application and invoke the URL again: All Actuator endpoints except shutdown are available now.

All available endpoints can be found in the Spring documentation: https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html

Add Version Information

In one of the previous posts, we introduced the git commit id plugin, which provided us version information. We add the plugin to our POM just as we did in the previous post. Make sure that the format is set to properties instead of JSON. Whenever there is a git.properties file into the root of the output directory, the info Actuator endpoint will provide version information about your application. Invoke the URL http://localhost:8080/actuator/info and by default, the following information is shown:

{
    "git": {
        "branch": "master",
        "commit": {
            "id": "d7d7202",
            "time": "2018-03-24T13:24:51Z"
        }
    }
}

As you can see, this is not the complete contents of our git.properties file. In order to add the complete contents, we add the following property to our application.properties file and restart the application:

management.info.git.mode=full

At this point, we can see the complete output.

Add Build Information

Similar to the version information, we can add build information. The info Actuator endpoint will show the build information whenever a build-info.properties file is present in the META-INF directory. In order to generate the build-info.properties file, we add the build-info goal to our spring-boot-maven-plugin in the pom:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

When we re-run the application, the build information is available at the info Actuator endpoint and looks like the following:

{
    "git": {...}, // 7 items
    "build": {
        "artifact": "myspringactuatorplanet",
        "name": "myspringactuatorplanet",
        "time": "2018-03-24T13:40:03.907109600Z",
        "version": "0.0.1-SNAPSHOT",
        "group": "com.mydeveloperplanet"
    }
}

Secure the Endpoints

Most of the time, we do not want this kind of information to be accessible by everyone. In that case, we can secure the Actuator endpoints. First of all, we will add Spring Security to the pom:

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

Just by adding Spring Security already gives us a login page when trying to access the Actuator endpoints and also our own helloActuator endpoint. We can login with user user and the password which is available in the Spring Boot log. This looks like the following (of course the hash changes after each startup):

Using generated security password: 8da882c3-4bbb-4e71-88c2-13399d9f0724

Now let's assume that we only want to secure the Actuator endpoints and not our own hellActuator endpoint. According to the Spring documentation we need to add the following configuration class:

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

  @Override
  protected void configure(HttpSecurity http) throws Exception {
    http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
      .anyRequest().hasRole("ADMIN")
      .and()
      .httpBasic();
  }

}

At this point, only the Actuator endpoints have been secured. It took me some time to find out that it was only the Actuator endpoints and not the Actuator base path. I assumed that EndpointRequest.toAnyEndpoint would also secure the URL http://localhost:8080/actuator, but that is not the case. The idea behind this is that it isn't an actual endpoint. An issue for Spring Boot exists for this: https://github.com/spring-projects/spring-boot/issues/12353.

We are still stuck with the generated password. We can overcome this by adding a userDetailsService to the ActuatorSecurity class. The way we are doing this is only allowed for demonstrating purposes and should not be used in a real production environment.

@Bean
@Override
public UserDetailsService userDetailsService() {
    UserDetails user =
        User.withDefaultPasswordEncoder()
            .username("user")
            .password("password")
            .roles("ADMIN")
            .build();

    return new InMemoryUserDetailsManager(user);
}

The Actuator endpoints are now accessible with user user and password password.

The Actuator Health Endpoint

The Actuator health endpoint, by default, shows no detail. Several built-in healthindicators are present, and the information to show is collected from these healthindicators. But by default, you will only see the following:

{
    "status": "UP"
}

In order to see the information of the built-in healthindicators, you will need to add the following line to your application.properties. This way, all information from the retrieved healthindicators is being shown. The default value is never, never showing the health indicators information. We choose to show the health indicator information when an authorized user is requesting the information.

management.endpoint.health.show-details=when-authorized

Re-run the application and invoke the Actuator health endpoint. The following information is shown in our case:

{
    "status": "UP",
    "details": {
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 408943587328,
                "free": 75006865408,
                "threshold": 10485760
            }
        }
    }
}

Most likely, you will also want to create custom health indicators to be used in your monitoring software. In that case, you can create custom health indicators by implementing the HealthIndicator interface. In the following example, we will check whether we are in an odd or an even minute when invoking the request. This way, we can easily test the change of status of the health indicator. When we are in an even minute, we will return the UP status, and when we are in an odd minute, we will return the DOWN status. Our custom class OddOrEvenMinuteHealthCheck becomes the following:

@Component
public class OddOrEvenMinuteHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = 0;
        LocalTime now = LocalTime.now();
        if (now.getMinute() % 2 != 0) {
            errorCode = 1;
        }

        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

}

Re-run the application and wait for an even minute. Invoking the Actuator health endpoint shows the following:

"oddOrEvenMinute": {
  "status": "UP"
},

Invoking the Actuator health endpoint when we are in an odd minute shows the following:

"oddOrEvenMinute": {
    "status": "DOWN",
    "details": {
        "Error Code": 1
    }
},

It is also possible to add custom status codes. Let's assume we want to have the status ODD and EVEN in our health check. We need to set them into the sequence of standard status codes in the application.properties. We will do so just below the UPP status:

management.health.status.order=DOWN, OUT_OF_SERVICE, UNKNOWN, ODD, EVEN, UP

And the last thing we need to do is change the return status in our ActuatorHealth class:

if (errorCode != 0) {
    return Health.status("ODD").withDetail("Error Code", errorCode).build();
}
return Health.status("EVEN").build();

Summary

In this post, we took a look at Spring Actuator. We saw how we can enable Actuator endpoints, how we can add version and build information to the info Actuator endpoint, how we can secure the Actuator endpoints, and finally, how we can customize some health indicators to the health Actuator endpoint.