days
-4
-4
hours
0
-6
minutes
-1
-3
seconds
-3
-4
search
Ready for take-off

Spring Boot 2 – An overview: Actuator 2.0

Michael Simons
© Shutterstock.com / Zoom Team

One of the most popular modules Spring Boot has to offer is Spring Boot Actuator. In the world of actuators, as part of the drive technology sector, actuators refer to drive elements that actively intervene in the respective process and bring about desired changes. They often have a great leverage effect: small changes lead to great agitation. As a core component of Spring Boot 2, this module undergoes some changes.

Michael Simons is a speaker at JAX 2018 and author of the book “Spring Boot – Moderne Softwareentwicklung im Spring Ökosystem“, published by dpunkt.verlag.

As usual: Simple integration

One thing remains the same: You only have to declare the spring-boot-starter-actuator as a dependency to use Spring Boot Actuator. This means that Spring Boot 2.0 applications have a good number of new interfaces and management endpoints.

These interfaces have traditionally included topics covering:

  • health – Information about the application’s state of health
  • info – Any information; e.g. latest commit information etc.
  • conditions – Information about the result of an application’s automatic configuration
  • httptrace – HTTP traces of the last n request/response cycles

…and much more. See the reference documentation for a complete list.

What has changed?

Names…not just hollow words

If you take a closer look, you will already find some changes in the list above: Several endpoints have been renamed to highlight their purpose. trace is now called httptrace and auto-config is listed as conditions.

The quest for meaningful names runs through Spring Boot 2 and the configuration of management endpoints now completely takes place via the management.endpoints prefix.

Harmonization of configuration properties
In Spring Boot 2, the namespace for offered configuration properties (prefix) has been reduced. The configuration of Spring Boot, actuator endpoints and new metrics take place within spring, management and management.metric namespaces. To keep it organized, the Spring team provides changelogs (besides its own) for configuration (RC1-Changelog, RC2-Changelog).Old configuration properties have not been marked as deprecated, but have been deleted without replacements. Upgrading a Spring-Boot-1 application will thus certainly require active migration. To facilitate this, a new module stands at your disposal: org.springframework.boot:spring-boot-properties-migrator, a property migrator. You may add this module during migration. It analyzes existing properties, issues warnings if they no longer exist, and temporarily migrates them to their new counterparts if available. The module is not intended to permanently remain within an application, but to minimize error-prone manual work.

Management web endpoints are no longer published to /, but to the /actuator path specified in management.endpoints.web.base-path. The paths for individual endpoints can be configured through management.endpoints.web.path-mapping.<id-of-the-endpoint>. So for example the path of the health endpoint can be mapped to healthcheck with management.endpoints.web.path-mapping.health=healthcheck.

Additionally, Endpoints are now exposed or hidden using the management.endpoints.web.exposure.include or management.endpoints.web.exposure.exclude properties. There are equally corresponding properties for JMX (...jmx...). The enabled flag has been removed.

Native support for JMX, Spring MVC, Spring WebFlux and Jersey

Actuator Endpoints are technology-independent in Spring Boot 2. For Spring-Boot-1 applications, the web endpoints also required the incorporation of Spring MVC. This is no longer the case. Due to the fact that Spring Boot 2 should also have (and now has) Reactive-Actuator, JMX and Jersey now benefit from this decision as well.

The allocation of separate actuators for all mentioned technologies has become very easy. Listing 1 shows an actual actuator with its required configuration:

@Endpoint(id = "custom")
class CustomEndpoint {
 
    private final AtomicInteger cnt =
            new AtomicInteger();
 
    @ReadOperation
    public String someReadOperation() {
        return "Current value " + cnt.get();
    }
 
    @WriteOperation
    public String someWriteOperation() {
        return "New value " + cnt.incrementAndGet();
    }
 
    @ReadOperation
    public WebEndpointResponse<void> otherReadOperation(
        @Selector String name
    ) {
        return new WebEndpointResponse<>(
                HttpStatus.NOT_IMPLEMENTED.value());
    }
}
 
@ManagementContextConfiguration
public class CustomEndpointConfig {
 
    @Bean
    public CustomEndpoint customEndpoint() {
        return new CustomEndpoint();
    }
}

The configuration needs to be specified with spring.factories in order to be recognized as a special configuration of an endpoint. This is necessary because Spring Boot still allows management endpoints to run in separate jump contexts, which are configured separately. This new structure apparently forces the migration of existing management endpoints.

Structural changes

The endpoints env, flyway, liquibase and especially metrics come in new formats. Depending on the means by which these endpoints are used, there may be respective tasks to be carried out. The drastic changes in the metrics endpoint are due to the fact that Spring Boot’s own metrics have been replaced by the Library Micrometer. Micrometer is an easy way to orchestrate applications so that metrics can be collected as cross-sectional information regardless of the subject matter.

Listing 2 shows the metrics endpoint at the top level. Micrometer metrics are multidimensional.

{
    "names": [
        "jvm.memory.used",
        "http.server.requests",
        "jvm.buffer.memory.used",
        "jvm.buffer.count",
        "data.source.max.connections",
        "logback.events",
        "process.uptime",
        "data.source.active.connections"
    ]
}

A Drilldown now takes place via path variables instead of via query parameters. A call to /actuator/metrics/http.server.requests? tag=uri:/hello&tag=status:200 returns the number and duration of calls to a URL “/hello“, which had the status code 200.

Actuator Security

The independent security configuration of management endpoints has been dropped without replacement. All endpoints except the shutdown endpoint are enabled by default, but only health and info are exposed across the web.

If endpoints are exposed via web interfaces – irrespective of the technology used – the Spring Security decisions (already described in the last part of this series) are valid: Defaults apply as long as something to the contrary is configured. In other words: it is up to the user to ensure that sensitive information is not exposed. There are several ways to ensure this:

  • Deploying web endpoints in different contexts on different HTTP ports and protecting them with a firewall
  • Explicit configuration of Spring Security

In order to keep the paths flexible and still allow users to use Java-based DSL to configure Spring Security, matchers (as shown in Listing 3) are provided. They will automatically determine the correct path.

@Override
public void configure(final HttpSecurity http) throws Exception {
    http
        .antMatcher("/api/**")
            .authorizeRequests()
                .requestMatchers(EndpointRequest.to(
                        InfoEndpoint.class,
                        HealthEndpoint.class,
                        MetricsEndpoint.class
                )).permitAll()
                .requestMatchers(EndpointRequest.toAnyEndpoint()).authenticated()
                .antMatchers("/api/**").permitAll()
        .and()
            .sessionManagement()
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .enableSessionUrlRewriting(false)
        .and()
            .csrf()
            .disable();
}

Conclusion

Depending on the use case, the migration to Spring Boot Actuator 2 will vary greatly between unobtrusive and very complex.

If the application in question only uses health or info, a migration is managed by making some path adjustments. If custom endpoints have been created, a migration within the application is necessary. Work in the security area may also be required.

From the user point of view, the greatest efforts reside, in my opinion, when integration points have been created using the old metrics endpoint.

Examples of this article can be found on GitHub. The EuregJUGs repository also shows an example migration.

The last part of this series will present a collection of minor news in Spring Boot 2.

Spring Boot – Modern software development within the Spring ecosystem
The Spring Boot book will be published in late April 2018 and will cover all current topics related to Spring Boot 2. In addition to the reactive programming model with Spring 5, this includes the new actuator infrastructure, Micrometer.io support and much more.This book is intended to appeal to interested developers from the Java EE area as well as Spring developers and give them a “recipe” to handle recurring tasks from everyday business life elegantly and without distraction using Spring Boot.

Further information on the book can be found here!

Author
spring boot

Michael Simons

Michael Simons works as a Senior Consultant at innoQ Germany. He is a member of the NetBeans Dream Team and founder of the Euregio JUG. Michael writes on his blog about Java, Spring and software architecture. He is on Twitter as @rotnroll666, where he deals with Java, music and minor and major problems as a husband and father of two children. In January 2018 Michael’s book “Spring Boot — Moderne Softwareentwicklung im Spring-Ökosystem” will be published by dpunkt.verlag. The book can already be pre-ordered at springbootbuch.de. It covers Spring Boot 2 and the new, reactive programming paradigm of Spring 5 as well as Spring basics and thus appeals to experienced Spring developers as well as new beginners. The diagrams in this article are also from the book, as are some of the examples shown. The code is already available on GitHub.


Leave a Reply

Be the First to Comment!

avatar
400
  Subscribe  
Notify of