Spring Boot Actuator – An Introduction

Spring boot actuator feature can be used to publish the application details, metrics, etc. that we can use to monitor the application easily.

These application metrics play a vital role in the microservice architecture. Also, with the help of actuators, we can easily integrate the centralized metrics collection and monitoring frameworks to collect and monitor the spring boot services.

Table of Contents

• Enabling the spring boot actuator
• Actuator endpoints
• Actuator configuration properties
  • Include or exclude actuator endpoints
  • Enabling health information
  • customizing endpoint path
• changing the actuator http management port
• Creating custom endpoints
• Creating the custom health indicator
• Application metrics
• Logging with actuator
• Conclusion

Enabling the spring boot actuator

We can use the actuator starter dependency to enable the actuator feature.

The below snippet shows the maven dependency.

Adding this dependency will autoconfigure the required configuration in the application and also enables the default actuator endpoints and health indicators.

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

Actuator endpoints

We can use actuator endpoints to monitor and interact with our applications.

By default, the actuator endpoint has prefix path /actuator, as shown below.

Also, only a few actuator endpoints are exposed over HTTP by default.

The below are a few of the endpoints.

• /health: Exposes the application health status.
• /beans: Exposes the configured spring beans in the application context. Provides details like the scope of the bean, bean type, etc.
• /caches: Exposes available caches in the application.
• /env: Provides all available environment configuration property details.
• /configprops: Exposes all available configuration classes list.
• /mappings: Exposes all availabe HTTP request mapping details in the application.
• /metrics: Exposes application metrics like JVM metrics, system metrics, and also the tomcat server metrics, etc.
• /heapdump: Provides the application heap dump.
• /threaddump: Exposes the thread information.
• /loggers: Exposes the logging application configuration information like log level, etc.
• /logfile: For web applications, this endpoint returns the logfile content. We can also retrieve only a part of the log file.
• /shutdown: We can use this endpoint to gracefully shut down the spring boot application. This is disabled by default.

Also, there are many other HTTP and JMX actuator endpoints available.

Actuator configuration properties

We can also override the default actuator configuration using the application properties.

Include or exclude actuator endpoints

By default, very few endpoints are included. To include and expose additional endpoints, we can use the below configuration. We can also exclude the endpoints with configuration properties, as shown below.

#To include all the default web endpoints:
management.endpoints.web.exposure.include=*

#To include specific web endpoints:
management.endpoints.web.exposure.include=health,info

#To exclude specific web endpoints:
management.endpoints.web.exposure.exclude=beans

Enabling health information

By default, only the application status is exposed in the /health endpoint.

We can also use the below configurations to expose application health details and component details.

management.endpoint.health.show-details=always
management.endpoint.health.show-components=always

customizing endpoint path

We also can modify the default actuator endpoint base path actuator/ with the below application property.

management.endpoints.web.base-path=/my-app-management-path

changing the actuator http management port

By default, the actuator exposes the HTTP endpoints with the same application’s port number.

We can also modify the HTTP management port of the application using the below application configuration property.

Here, the application will use port number 8080, and the actuator will use port number 9080 to expose the endpoints.

management.server.port=9080

Creating custom endpoints

Along with the default spring boot actuator endpoints, we can easily add custom endpoints also.

Spring boot provides annotation support to easily create custom actuator endpoints. Also, for web applications, the custom endpoints are exposed over HTTP.

The below code snippet shows an example implementation.

package com.asbnotebook;

import java.util.HashMap;
import java.util.Map;
import org.springframework.boot.actuate.endpoint.annotation.DeleteOperation;
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.stereotype.Component;

@Component
@Endpoint(id = "myapp")
public class CustomActuatorEndpoint {

    @ReadOperation
    public Map<String, String> myCustomreadEndpoint() {
        Map<String, String> map = new HashMap<>();
        map.put("readMessage", "This is cystom actuator endpoint.!!");
        return map;
    }

    @WriteOperation
    public Map<String, String> myCustomWriteEndpoint(String value) {
        Map<String, String> map = new HashMap<>();
        map.put("writeMessage", "This is cystom actuator write endpoint.!!" + value);
        return map;
    }

    @DeleteOperation
    public Map<String, String> myCustomDeleteEndpoint() {
        Map<String, String> map = new HashMap<>();
        map.put("readMessage", "This is cystom actuator delete endpoint.!!");
        return map;
    }
}

We are using the below annotations to create our custom web actuator endpoints.

• @Endpoint: we can use this annotation to set the endpoint id for our custom actuator endpoint.
• @ReadOperation: Creates an HTTP GET actuator endpoint.
• @WriteOperation: Exposes an HTTP POST endpoint and supports passing input parameters.
• @DeleteOperation: exposes an HTTP delete endpoint.

Run the application, and we can observe the custom actuator endpoints as shown below.

Also, the read operation endpoint returns a key-value string, as shown below.

Also, we can use the POST request to pass user data to the write actuator endpoint and the HTTP DELETE request to invoke the delete actuator endpoint.

The annotations also support exposing the JMX actuator endpoints. For more information, check the official documentation.

Creating the custom health indicator

By default, the actuator exposes an application health endpoint to indicate the health of application components.

We can also create a custom health indicator class by implementing the HealthIndicator interface and providing the required implementation to the health() method.

The below example shows a simple example implementation of the custom health indicator.

package com.asbnotebook;

import java.util.Random;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class CustomHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check();
        if (errorCode != 0) {
            return Health.down().withDetail("Custom service is down!!", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        Random random = new Random();
        int n = random.nextInt(10);
        return n % 2;
    }
}

Also, add the below configuration property to display the application health details.

management.endpoints.web.exposure.include=*
management.endpoint.health.show-details=always

Run the application, and access the health endpoint on the browser.

We can observe the myapp health indicator and also the details of the health indicator in the below image.

Application metrics

The spring boot version 2 provides the required autoconfiguration for the micrometer metrics facade out of the box.

Micrometer supports various metrics monitoring systems like Elastic, Prometheus, etc. We can also easily integrate these monitoring systems to monitor our spring boot application metrics.

Logging with actuator

The /loggers endpoint provides all the available logging levels and a list of loggers.

We can also set the logging level at the runtime of a particular logger with the help of the actuator.

Invoke the HTTP POST request with the below request body to set the logger level of a logger resource to ERROR.

{
    "configuredLevel": "ERROR"
}

The below image shows how we can set the ROOT logging level to ERROR.

We can also observe the changed logging level for the ROOT logger in the below image.

Conclusion

In this article, we learned the basics of actuators and the benefits of enabling the actuator in spring boot applications.

We also learned default actuator endpoints, configuring the actuator, etc.

Finally, we also learned about adding the custom endpoints, creating custom health indicators, changing the logging level using the loggers, etc.

The example code is available on Github.