A Comprehensive Guide to Spring Boot Actuator: Quick Start, Endpoints, and Monitoring

Introduction

Last year our project migrated to a microservice 1.0 architecture, but monitoring lagged behind. To address this, we decided to monitor all core Spring Boot microservices using Spring Boot Actuator.

This article summarizes the learning and practical usage of the Actuator module, including quick start, important endpoints, and runtime inspection of thread dumps, heap information, and dynamic log level changes.

Quick Start – Creating a Spring Boot Actuator Demo

You can create a demo application via Spring Boot CLI:

spring init -d=web,actuator -n=actuator-demo actuator-demo

Or use Spring Initializr (image omitted).

Add the Actuator starter dependency:

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

For Gradle:

dependencies {
    compile("org.springframework.boot:spring-boot-starter-actuator")
}

Endpoints Overview

Actuator provides three categories of native endpoints:

应用配置类 : Application configuration, environment variables, auto‑configuration reports.

度量指标类 : Metrics such as JVM memory, thread pool, HTTP request stats.

操作控制类 : Operations like shutdown.

Endpoints are accessible via HTTP or JMX and can be integrated with external monitoring systems (Prometheus, Graphite, DataDog, etc.) through Micrometer.

Endpoint Exposure Configuration

Configure which endpoints are exposed:

management.endpoints.web.exposure.include=*

Or expose specific ones, separating multiple endpoints with commas:

management.endpoints.web.exposure.exclude=beans,trace

Change the base path if needed:

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

Important Endpoints

/health

Aggregates health indicators. Show details with:

management.endpoint.health.show-details=always

Disabling a specific health indicator:

management.health.mongo.enabled=false

Disabling all defaults:

management.health.defaults.enabled=false

/metrics

Returns a list of metric names. Retrieve a specific metric:

http://localhost:8080/actuator/metrics/jvm.memory.max

Filter by tag:

http://localhost:8080/actuator/metrics/jvm.memory.max?tag=id:Metaspace

/loggers

Shows all logger configurations. Change a logger level at runtime by POSTing JSON to the logger endpoint, e.g., to set the root logger to DEBUG:

{
   "configuredLevel": "DEBUG"
}

/info

Displays custom application information configured in application.properties :

info.app.name=actuator-test-demo
info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8

/beans

Lists all beans in the Spring container with their metadata.

/heapdump

Generates a JVM heap dump that can be opened with VisualVM.

/threaddump

Provides a snapshot of all threads, their states, and stack traces.

/shutdown

Gracefully shuts down the application (must be enabled):

management.endpoint.shutdown.enabled=true

POST to /actuator/shutdown returns:

{
    "message": "Shutting down, bye..."
}

Securing Actuator Endpoints with Spring Security

Add the security starter:

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

Define security rules (example version 2) to restrict all endpoints to users with role ACTUATOR_ADMIN while allowing static resources and the root path:

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 ActuatorSecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .requestMatchers(EndpointRequest.toAnyEndpoint())
                .hasRole("ACTUATOR_ADMIN")
            .requestMatchers(PathRequest.toStaticResources().atCommonLocations())
                .permitAll()
            .antMatchers("/")
                .permitAll()
            .antMatchers("/**")
                .authenticated()
            .and()
            .httpBasic();
    }
}

Configure default user credentials:

spring.security.user.name=actuator
spring.security.user.password=actuator
spring.security.user.roles=ACTUATOR_ADMIN

Conclusion

The article covered the basics of Spring Boot Actuator, how to enable and configure various endpoints, monitor application health and metrics, dynamically adjust log levels, and secure the endpoints. The full source code is available on GitHub.