Spring Boot Actuator

Introduction

Spring Boot Actuator is a powerful module that provides production-ready features such as monitoring, metrics, and health checks. It enables you to monitor and manage your application through HTTP endpoints and JMX. In this chapter, we will cover everything you need to know about Spring Boot Actuator, including how to set it up, the available endpoints, and their uses.

Table of Contents

1. Introduction
2. What is Spring Boot Actuator?
3. Setting Up Spring Boot Actuator
4. Commonly Used Actuator Endpoints
   • /info
   • /health
   • /beans
   • /conditions
   • /mappings
   • /configprops
   • /metrics
   • /env
   • /threaddump
   • /loggers
   • /shutdown
5. Customizing Actuator Endpoints
6. Securing Actuator Endpoints
7. Monitoring and Metrics with Prometheus and Grafana
8. Conclusion

What is Spring Boot Actuator?

1. Spring Boot Actuator module provides production-ready features such as monitoring, metrics and health checks.
2. The Spring Boot Actuator enables you to monitor the application using HTTP endpoints and JMX.
3. Spring Boot Provides a spring-boot-starter-actuator library to auto-configure Actuator

Setting Up Spring Boot Actuator

To get started with Spring Boot Actuator, follow these steps:

1. Add the Actuator Dependency:

Add the Spring Boot Actuator dependency to your pom.xml file:

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

2. Configure Application Properties:

In your application.properties file, you can configure Actuator settings. For example:

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

These settings will expose all actuator endpoints and show detailed health information.

Commonly Used Actuator Endpoints

/info

The /info endpoint displays arbitrary application information. You can customize this by adding properties in application.properties.

Example:

info.app.name=My Spring Boot Application
info.app.description=This is a demo application.
info.app.version=1.0.0

Output:

{
  "app": {
    "name": "My Spring Boot Application",
    "description": "This is a demo application.",
    "version": "1.0.0"
  }
}

/health

The /health endpoint shows the health of the application, including the disk space, databases, and more.

Example:

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 180231299072,
        "threshold": 10485760
      }
    }
  }
}

/beans

The /beans endpoint shows all the beans registered in your application, including the beans you explicitly configured and those auto-configured by Spring Boot.

Example:

{
  "contexts": {
    "application": {
      "beans": {
        "myBean": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.example.MyBean",
          "resource": "classpath:com/example/MyBean.class"
        }
        // other beans
      }
    }
  }
}

/conditions

The /conditions endpoint shows the auto-configuration report, categorized into positiveMatches and negativeMatches.

Example:

{
  "positiveMatches": {
    "org.springframework.boot.autoconfigure.context.PropertyPlaceholderAutoConfiguration": [
      "ConditionalOnProperty"
    ]
  },
  "negativeMatches": {
    "org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration": [
      "ConditionalOnClass"
    ]
  }
}

/mappings

The /mappings endpoint shows all the @RequestMapping paths declared in the application. This is very helpful for checking which request path will be handled by which controller method.

Example:

{
  "contexts": {
    "application": {
      "mappings": {
        "dispatcherServlets": {
          "dispatcherServlet": [
            {
              "handler": "public java.lang.String com.example.MyController.hello()",
              "predicate": "{GET /hello}"
            }
            // other mappings
          ]
        }
      }
    }
  }
}

/configprops

The /configprops endpoint offers all the configuration properties defined by @ConfigurationProperties bean, including your configuration properties defined in the application.properties or YAML files.

Example:

{
  "contexts": {
    "application": {
      "beans": {
        "myProperties": {
          "prefix": "my",
          "properties": {
            "name": "My Application",
            "description": "This is my application"
          }
        }
      }
    }
  }
}

/metrics

The /metrics endpoint shows various metrics about the current application such as how much memory it is using, how much memory is free, the size of the heap used, the number of threads used, and so on.

Example:

{
  "names": [
    "jvm.memory.used",
    "jvm.memory.max",
    "jvm.memory.committed",
    "jvm.memory.used",
    // other metrics
  ]
}

To get a specific metric:

GET /actuator/metrics/jvm.memory.used

/env

The /env endpoint exposes all the properties from the Spring’s ConfigurableEnvironment interface, such as a list of active profiles, application properties, system environment variables, and so on.

Example:

{
  "activeProfiles": [
    "default"
  ],
  "propertySources": [
    {
      "name": "server.ports",
      "properties": {
        "local.server.port": {
          "value": 8080
        }
      }
    },
    // other property sources
  ]
}

/threaddump

Using the /threaddump endpoint, you can view your application’s thread dump with running thread details and JVM stack trace.

Example:

{
  "threads": [
    {
      "threadName": "main",
      "threadId": 1,
      "blockedTime": -1,
      "blockedCount": 0,
      "waitedTime": -1,
      "waitedCount": 0,
      "lockName": null,
      "lockOwnerId": -1,
      "lockOwnerName": null,
      "inNative": false,
      "suspended": false,
      "threadState": "RUNNABLE",
      "stackTrace": [
        {
          "methodName": "park",
          "fileName": "Unsafe.java",
          "lineNumber": -2,
          "className": "sun.misc.Unsafe",
          "nativeMethod": true
        }
        // other stack traces
      ]
    }
    // other threads
  ]
}

/loggers

The /loggers endpoint allows you to view and configure the log levels of your application at runtime.

Example:

To get all loggers:

GET /actuator/loggers

To get a specific logger:

GET /actuator/loggers/com.example.MyClass

To change the logging level:

POST /actuator/loggers/com.example.MyClass
Content-Type: application/json

{
  "configuredLevel": "DEBUG"
}

/shutdown

The /shutdown endpoint can be used to gracefully shut down the application. This endpoint is not enabled by default. You can enable this endpoint by adding the following property in the application.properties file:

management.endpoint.shutdown.enabled=true

After adding this property, you need to send the HTTP POST request to the endpoint:

POST /actuator/shutdown

Example:

POST http://localhost:8080/actuator/shutdown

Customizing Actuator Endpoints

You can customize the behavior and information exposed by Actuator endpoints. This can include changing the base path, enabling or disabling specific endpoints, and adding custom endpoints.

Example: Custom Base Path

In application.properties:

management.endpoints.web.base-path=/manage

Example: Custom Endpoint

Create a custom endpoint by implementing the @Endpoint annotation:

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

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {

    @ReadOperation
    public String custom() {
        return "Custom Endpoint";
    }
}

Access the custom endpoint at /actuator/custom.

Securing Actuator Endpoints

It’s important to secure your Actuator endpoints, especially in a production environment. You can use Spring Security to secure these endpoints. Here’s how to do it with Spring Boot 3.2:

First, add the Spring Security dependency to your pom.xml:

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

Then, configure security settings in your application:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config

.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorizeRequests ->
                authorizeRequests
                    .requestMatchers("/actuator/**").hasRole("ADMIN")
                    .anyRequest().authenticated()
            )
            .httpBasic();
        return http.build();
    }
}

Monitoring and Metrics with Prometheus and Grafana

Spring Boot Actuator can be integrated with Prometheus and Grafana for advanced monitoring and visualization.

Step 1: Add Dependencies

Add the Prometheus dependency to your pom.xml:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Step 2: Configure Prometheus

In application.properties:

management.metrics.export.prometheus.enabled=true
management.endpoints.web.exposure.include=prometheus

Step 3: Setup Prometheus and Grafana

• Install Prometheus and Grafana on your server.
• Configure Prometheus to scrape metrics from your Spring Boot application.
• Use Grafana to visualize the metrics collected by Prometheus.

Conclusion

Spring Boot Actuator provides a comprehensive set of tools for monitoring and managing your Spring Boot applications. By leveraging Actuator endpoints, you can gain valuable insights into your application’s health, performance, and behavior. With the latest version of Spring Boot 3.2, securing and customizing these endpoints is easier and more flexible. Integrating Actuator with tools like Prometheus and Grafana further enhances your ability to monitor and maintain your applications effectively.