Spring Boot Actuator is a powerful tool that helps you monitor and manage your Spring Boot applications. It exposes production-ready features like health checks, metrics, environment properties, thread dumps, and more through HTTP endpoints, JMX beans, or custom integrations.
How to Add Spring Boot Actuator
Add the dependency to your pom.xml:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>Key Actuator Features with Full Examples
1. Exposing Endpoints
Enable HTTP Actuator Endpoints
In application.properties or application.yml:
# Enable all endpoints
management.endpoints.web.exposure.include=*2. /actuator/health – Health Check
Shows application health status.
Default:
{
"status": "UP"
}Custom Health Indicator Example:
@Component
public class CustomHealthIndicator implements HealthIndicator {
@Override
public Health health() {
boolean condition = checkSomething();
if (condition) {
return Health.up().withDetail("custom", "All good!").build();
}
return Health.down().withDetail("custom", "Something went wrong!").build();
}
private boolean checkSomething() {
return true; // your logic here
}
}3. /actuator/metrics – Application Metrics
Provides JVM and custom metrics.
Example Endpoint:
/actuator/metrics/jvm.memory.usedCustom Metric Example:
@Component
public class CustomMetrics {
public CustomMetrics(MeterRegistry registry) {
Gauge.builder("my.custom.metric", () -> Math.random() * 100)
.description("A custom random gauge")
.register(registry);
}
}4. /actuator/info – App Info
Show application info like version or description.
management.endpoint.info.enabled=true
info.app.name=MyApp
info.app.version=1.0.0
info.app.description=Spring Boot App with ActuatorOutput:
{
"app": {
"name": "MyApp",
"version": "1.0.0",
"description": "Spring Boot App with Actuator"
}
}5. /actuator/refresh – Refresh Beans (with Spring Cloud)
If you use Spring Cloud Config, you can refresh beans annotated with @RefreshScope at runtime.
Enable endpoint:
management.endpoints.web.exposure.include=refreshUse in code:
@RefreshScope
@RestController
public class MessageController {
@Value("${custom.message:default}")
private String message;
@GetMapping("/message")
public String getMessage() {
return message;
}
}Trigger refresh (e.g., via curl):
curl -X POST http://localhost:8080/actuator/refresh6. Securing Actuator Endpoints
Add Spring Security:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>Custom Security Config:
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/**").hasRole("ADMIN")
.anyRequest().permitAll()
)
.httpBasic();
return http.build();
}
}Set user in application.properties:
spring.security.user.name=admin
spring.security.user.password=secret
spring.security.user.roles=ADMIN7. /actuator/threaddump
Provides thread dump of the JVM – useful for debugging.
Example:
curl http://localhost:8080/actuator/threaddump8. /actuator/env
Displays all environment properties.
Use carefully as it might expose sensitive data.
9. /actuator/beans
Shows all Spring beans loaded in the context.
Helpful for debugging bean registration issues.
10. /actuator/mappings
Lists all request mappings in the app.
Example output:
{
"/api/users": {
"handler": "UserController#getUsers()",
"methods": ["GET"]
}
}Custom Actuator Endpoint Example
You can define your own actuator endpoint.
@Endpoint(id = "customstatus")
@Component
public class CustomStatusEndpoint {
@ReadOperation
public Map<String, String> getStatus() {
return Map.of("status", "Everything is running fine!");
}
}Visit /actuator/customstatus to see it.
Actuator with Prometheus/Grafana
Spring Boot Actuator integrates with Micrometer, which supports Prometheus.
Add dependency:
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>Enable Prometheus endpoint:
management.endpoints.web.exposure.include=prometheusVisit /actuator/prometheus for metrics in Prometheus format.
Testing Actuator Endpoints
Basic integration test:
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
public class ActuatorTests {
@Autowired
private MockMvc mockMvc;
@Test
public void healthEndpointShouldReturnUp() throws Exception {
mockMvc.perform(get("/actuator/health"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.status").value("UP"));
}
}Conclusion
Spring Boot Actuator is essential for monitoring, managing, and debugging your app. With features like metrics, health checks, environment details, and custom endpoints, it makes your app production-ready and observability-friendly.
