Spring Boot Actuator Basics

Introduction

Spring Boot Actuator is a sub-project of Spring Boot that provides built-in endpoints which help you monitor and manage your application. These endpoints can be used to check the health of your application, gather metrics, view configuration properties, and much more. In this tutorial, we will explore the basics of Spring Boot Actuator, including how to enable it, configure its endpoints, and use them effectively.

Prerequisites

Before diving into Actuator, ensure you have a basic understanding of:

• Java programming
• Spring Boot framework
• Maven or Gradle build tools

Adding Actuator to Your Project

To integrate Spring Boot Actuator into your project, you need to add the appropriate dependency. If you are using Maven, update your pom.xml file as follows:

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

For Gradle users, add the following to your build.gradle file:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

Enabling Actuator Endpoints

By default, Spring Boot Actuator exposes a set of endpoints that are secured. To enable them for testing purposes, you can add the following properties to your application.properties or application.yml file:

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

This configuration will expose all web endpoints and display detailed health information.

Common Actuator Endpoints

Health Endpoint

The /actuator/health endpoint provides a simple status check of your application. By default, it only shows whether the app is up or down. With the management.endpoint.health.show-details=always property, you can get more detailed information about the health of various components.

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 10737418240,
        "free": 5368709120,
        "threshold": 10485760
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

Info Endpoint

The /actuator/info endpoint is used to display arbitrary application information. You can customize this by adding properties to your application.properties file:

info.app.name=MySpringBootApp
info.app.description=A simple Spring Boot app
info.app.version=1.0.0

Accessing the /actuator/info endpoint will return:

{
  "app": {
    "name": "MySpringBootApp",
    "description": "A simple Spring Boot app",
    "version": "1.0.0"
  }
}

Metrics Endpoint

The /actuator/metrics endpoint provides various metrics about the application, such as memory usage, JVM stats, and HTTP request counts.

{
  "names": [
    "jvm.buffer.pool.used.bytes",
    "jvm.memory.max",
    "jvm.memory.committed",
    "jvm.memory.used",
    ...
  ]
}

You can also get detailed metrics for specific types by appending the metric name to the endpoint, e.g., /actuator/metrics/jvm.memory.used.

Loggers Endpoint

The /actuator/loggers endpoint allows you to view and modify the logging levels of your application at runtime.

{
  "levels": null,
  "loggers": {
    "ROOT": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    },
    "org.springframework.boot": {
      "configuredLevel": null,
      "effectiveLevel": "INFO"
    }
  }
}

You can change the logging level of a specific logger by sending a POST request:

curl -X POST http://localhost:8080/actuator/loggers/org.springframework.web -H "Content-Type: application/json" -d '{"configuredLevel":"DEBUG"}'

Securing Actuator Endpoints

Exposing all endpoints without security is not recommended for production environments. Spring Boot Actuator integrates seamlessly with Spring Security to secure these endpoints.

First, add the Spring Security dependency:

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

Then, configure security in your application. For example, you can create a simple configuration class:

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.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

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

        return new InMemoryUserDetailsManager(user);
    }

    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .requestMatchers("/actuator/**").authenticated()
            .anyRequest().permitAll()
            .and()
            .httpBasic();
    }
}

This configuration secures all Actuator endpoints and requires basic authentication for access.

Customizing Actuator Endpoints

Spring Boot Actuator allows you to customize its behavior through various properties. For example, you can change the base path of the endpoints:

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

You can also create custom health indicators if you need to monitor specific application components.

Conclusion

Spring Boot Actuator is a powerful tool for monitoring and managing your Spring Boot applications. By enabling and configuring its endpoints, you can gain valuable insights into the health, performance, and configuration of your app. Always ensure that Actuator endpoints are secured in production environments to prevent unauthorized access.