/spring-boot-actuator

name: spring-boot-actuator
description: Provides patterns to configure Spring Boot Actuator for production-grade monitoring, health probes, secured management endpoints, and Micrometer metrics across JVM services. Use when setting up monitoring, health checks, or metrics for Spring Boot applications.
allowed-tools: Read, Write, Bash

Spring Boot Actuator Skill

Overview

• Deliver production-ready observability for Spring Boot services using Actuator endpoints, probes, and Micrometer integration.
• Standardize health, metrics, and diagnostics configuration while delegating deep reference material to `references/`.
• Support platform requirements for secure operations, SLO reporting, and incident diagnostics.

When to Use

• Trigger: "enable actuator endpoints" – Bootstrap Actuator for a new or existing Spring Boot service.
• Trigger: "secure management port" – Apply Spring Security policies to protect management traffic.
• Trigger: "configure health probes" – Define readiness and liveness groups for orchestrators.
• Trigger: "export metrics to prometheus" – Wire Micrometer registries and tune metric exposure.
• Trigger: "debug actuator startup" – Inspect condition evaluations and startup metrics when endpoints are missing or slow.

Quick Start

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

// Gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-actuator"
}

After adding the dependency, verify endpoints respond:

curl http://localhost:8080/actuator/health
curl http://localhost:8080/actuator/info

Instructions

1. Add Actuator Dependency

Include `spring-boot-starter-actuator` in your build configuration. > **Validate**: Restart the service and confirm `/actuator/health` and `/actuator/info` respond with `200 OK`.

2. Expose Required Endpoints

• Set `management.endpoints.web.exposure.include` to the precise list or `"*"` for internal deployments.
• Adjust `management.endpoints.web.base-path` (e.g., `/management`) when the default `/actuator` conflicts with routing.
• Review detailed endpoint semantics in `references/endpoint-reference.md`.

> **Validate**: `curl http://localhost:8080/actuator` returns the list of exposed endpoints.

3. Secure Management Traffic

• Apply an isolated `SecurityFilterChain` using `EndpointRequest.toAnyEndpoint()` with role-based rules.
• Combine `management.server.port` with firewall controls or service mesh policies for operator-only access.
• Keep `/actuator/health/**` publicly accessible only when required; otherwise enforce authentication.

> **Validate**: Unauthenticated requests to protected endpoints return `401 Unauthorized`.

4. Configure Health Probes

• Enable `management.endpoint.health.probes.enabled=true` for `/health/liveness` and `/health/readiness`.
• Group indicators via `management.endpoint.health.group.*` to match platform expectations.
• Implement custom indicators by extending `HealthIndicator` or `ReactiveHealthContributor`; sample implementations in `references/examples.md#custom-health-indicator`.

> **Validate**: `/actuator/health/readiness` returns `UP` with all mandatory components before promoting to production.

5. Publish Metrics and Traces

• Activate Micrometer exporters (Prometheus, OTLP, Wavefront, StatsD) via `management.metrics.export.*`.
• Apply `MeterRegistryCustomizer` beans to add `application`, `environment`, and business tags for observability correlation.
• Surface HTTP request metrics with `server.observation.*` configuration when using Spring Boot 3.2+.

> **Validate**: Scrape `/actuator/prometheus` and confirm required meters (`http.server.requests`, `jvm.memory.used`) are present.

6. Enable Diagnostics Tooling

• Turn on `/actuator/startup` (Spring Boot 3.5+) and `/actuator/conditions` during incident response to inspect auto-configuration decisions.
• Register an `HttpExchangeRepository` (e.g., `InMemoryHttpExchangeRepository`) before enabling `/actuator/httpexchanges` for request auditing.
• Consult `references/endpoint-reference.md` for endpoint behaviors and limits.

> **Validate**: `/actuator/startup` and `/actuator/conditions` return valid JSON payloads.

Examples

Basic – Expose health and info safely

management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  endpoint:
    health:
      show-details: never

Intermediate – Readiness group with custom indicator

@Component
public class PaymentsGatewayHealth implements HealthIndicator {

    private final PaymentsClient client;

    public PaymentsGatewayHealth(PaymentsClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        boolean reachable = client.ping();
        return reachable ? Health.up().withDetail("latencyMs", client.latency()).build()
                         : Health.down().withDetail("error", "Gateway timeout").build();
    }
}

management:
  endpoint:
    health:
      probes:
        enabled: true
      group:
        readiness:
          include: "readinessState,db,paymentsGateway"
          show-details: always

Advanced – Dedicated management port with Prometheus export

management:
  server:
    port: 9091
    ssl:
      enabled: true
  endpoints:
    web:
      exposure:
        include: "health,info,metrics,prometheus"
      base-path: "/management"
  metrics:
    export:
      prometheus:
        descriptions: true
        step: 30s
  endpoint:
    health:
      show-details: when-authorized
      roles: "ENDPOINT_ADMIN"

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(c -> c
                .requestMatchers(Endpo