Spring Boot Actuator Complete Tutorial with Example

Spring Boot Actuator

In this article, We will get the complete understanding of  Spring Boot Actuator with Examples.

If you have not read my introduction article of Spring Boot, I would request you to take a look –  Spring Boot Tutorial.

Spring Boot Actuator is a module / component of Spring Boot framework. Spring Boot Actuator is very essential to the Spring Boot framework. Once our application is ready and running in production, then the monitoring of application is very much required as the slowdown or any error in production env can cause huge impact on the business.

We can manage and monitor the application in production environment with the help of Spring boot Actuator and there is no need of additional coding and configurations for this.

Let’s understand the Spring Boot Actuator in depth :

Introduction to Spring Boot Actuator

The application’s managing and monitoring informations are exposed through the endpoint URLs such as REST API. We can say that Spring Boot Actuator is a tool which has multiple HTTP endpoints and we can monitor and manage our application using these endpoints.

spring-boot-actuator module provides us multiple production-ready features. It provides us various information like application metrics details, health of application, info, env details, logger details, auditing etc. All the endpoints of Spring Boot Actuator is by default secured.

Spring allows only Http and Jmx endpoints.

In the old way before the inception of Spring Boot Actuator, developers needed to write the code for the health check of the application. With Spring Boot Actuator, It becomes very easy. It provides several endpoints which can be used for this purpose.

Spring Boot Actuator includes the built-in endpoints and we can also add our own endpoints or we can also configure the existing endpoints to be exposed on any other built-in or custom endpoints.

This is to be consider that all the endpoints are configurable but all cannot be exposed publicly. There are several endpoints that are sensitive like env, beans etc. Spring Boot framework itself sets the sensitive defaults to true for endpoints that requires credentials when they are accessed over the HTTP. The endpoints like info and health are by default not sensitive.

Spring Boot Actuator can also gets integrated with the external monitoring systems like Graphite, Prometheus, Wavefront, Influx, DataDog etc. These monitoring system provides their own dashboard, graphs, analytics etc which helps in monitoring and managing your application more easily

Spring Boot Actuator uses Micrometer internally. Micrometer is application metric system used to integrate with the external monitoring systems. As it uses Micrometer, it becomes easy to integrate any external monitoring system with very less configurations.

Spring Boot Actuator Maven dependency

To use the Spring Boot Actuator in your project, add the following maven dependency in your pom.xml file :

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

Spring Boot Actuator Endpoints

Spring Boot Actuator endpoints helps in monitoring and interacting with Spring Boot application.

Spring Boot contains several built-in endpoints and we can also add custom endpoints as per requirement :

Below is the list of important endpoints :

Spring Boot Actuator

The complete list of Spring Boot Actuator endpoints is available in Spring official page.

Creating a Custom Actuator Endpoint

In Spring Boot, we can actually create custom actuator endpoints for our application.

  • @Endpoint annotation at class level is used to create the custom actuator endpoint.
  • @ReadOperation, @WriteOperation, @DeleteOperation annotations are used at method level to expose the method as actuator endpoint bean.
  • @JmxEndpoint and @WebEndpoint annotations are used to create the custom technology specific actuator endpoints.

Let’s understand this in more detail with below example :

Example to Create a Custom Actuator Endpoint

package com.techblogstation;

import org.springframework.stereotype.Component;
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.context.annotation.Bean;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;


@Endpoint(id="customendpoint")
@Component
public class CustomEndpointExample {

	@ReadOperation
	@Bean
	public String message() {
		return "returning message from custom endpoint";
	}
}

How to Enable or Disable the Actuator Endpoints

In Spring , All the endpoints, listed earlier , are by default enabled except the shutdown endpoint.

We can easily enable or disable any Spring Boot Actuator endpoint whether it is existing or custom by setting the below property as true or false :

management.endpoint.<<id>>.enabled = true
management.endpoint.<<id>>.enabled = false

<<id>> is the identifier of the endpoint. As in the above custom endpoint example, our endpoint id is customendpoint.

For Example, Below property needs to be added in application.properties file to enable the endpoint –shutdown :

management.endpoint.shutdown.enabled=true

Exposing Actuator Endpoints

  • In Spring, health and info endpoints are exposed over HTTP.
  • All other endpoints are exposed over JMX.

However, we can modify this property in application.properties file for our application.

Exposing Actuator endpoints over HTTP

Suppose if you want specific endpoints to be exposed over HTTP then use the below property and mention the comma separated endpoints list :

management.endpoints.web.exposure.include=health,beans,info,env

To Expose all the endpoints over HTTP set the below property with value * :

management.endpoints.web.exposure.include=*

You can also use below property to exclude any endpoints to be exposed over HTTP :

management.endpoints.web.exposure.exclude=

Exposing Actuator endpoints over JMX

Suppose if you want specific endpoints to be exposed over JMX then use the below property and mention the comma separated endpoints list :

management.endpoints.jmx.exposure.include=health,beans,info,env

To Expose all the endpoints over JMX set the below property with value * :

management.endpoints.jmx.exposure.include=*

You can also use below property to exclude any endpoints to be exposed over JMX:

management.endpoints.jmx.exposure.exclude=

Securing Actuator Endpoints using Spring Security

In Spring, only health and info endpoints are by default not sensitive. All other endpoints are by default sensitive and hence authorization is needed to access these endpoints.

Hence , we need to secure our sensitive endpoints from any unauthorized access. We can achieve this security using Spring Security.

Spring Security secures the endpoints using a basic form-based HTTP authentication. Below is the maven dependency for Spring Security :

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

We can also override the default security define our own security access rules using WebSecurityConfigurerAdapter class.

  • In the below example, we have illustrated sample Spring Security configuration.
  • We are using one RequestMatcher factory called EndPointRequest to configure security access rules for the actuator endpoints.
  • It is provided by the spring-boot-actuator module.
package com.techblogstation.config;

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.boot.actuate.context.ShutdownEndpoint;
import org.springframework.boot.autoconfigure.security.servlet.PathRequest;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class ActuatorSecConfig extends WebSecurityConfigurerAdapter {


    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                    .requestMatchers(EndpointRequest.to(ShutdownEndpoint.class))
                        .hasRole("ADMIN_ACTUATOR_ROLE")
                    .requestMatchers(EndpointRequest.toAnyEndpoint())
                        .permitAll()
                    .requestMatchers(PathRequest.toStaticResources().atCommonLocations())
                        .permitAll()
                    .antMatchers("/")
                        .permitAll()
                    .antMatchers("/**")
                        .authenticated()
                .and()
                .httpBasic();
    }
}

Now, we must add the default spring security user in the application.properties file to test the above configuration class with the basic HTTP authentication :

spring.security.user.name=actuator

spring.security.user.password=actuator

spring.security.user.roles=ADMIN_ACTUATOR_ROLE

Enabling CORS support for Actuator endpoints

Well, CORS support in Spring Boot is by default disabled. To enable the CORS support, property endpoints.cors.allowed-origins needs to be set in the application.properties :

endpoints.cors.allowed-origins = <<url which needs to be enabled>>
endpoints.cors.allowed-methods = GET,POST

Conclusion

We have learned about all the Spring Boot Actuator endpoints, How to create custom endpoints, How to enable or disable the actuator endpoints, Securing the endpoints, enabling the CORS support for endpoints.

Leave a Reply

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