spring-boot-actuator

$2a

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(EndpointRequest.to("health")).permitAll()

                .anyRequest().hasRole("ENDPOINT_ADMIN"))

            .httpBasic(Customizer.withDefaults());

        return http.build();

    }

}

More end-to-end samples are available in references/examples.md.

Best Practices

• Keep SKILL.md concise and rely on references/ for verbose documentation to conserve context.

• Apply the principle of least privilege: expose only required endpoints and restrict sensitive ones.

• Use immutable configuration via profile-specific YAML to align environments.

• Monitor actuator traffic separately to detect scraping abuse or brute-force attempts.

• Automate regression checks by scripting curl probes in CI/CD pipelines.

Constraints and Warnings

• Avoid exposing /actuator/env, /actuator/configprops, /actuator/logfile, and /actuator/heapdump on public networks.

• Do not ship custom health indicators that block event loop threads or exceed 250 ms unless absolutely necessary.

• Ensure Actuator metrics exporters run on supported Micrometer registries; unsupported exporters require custom registry beans.

• Maintain compatibility with Spring Boot 3.5.x conventions; older versions may lack probes and observation features.

• Never expose actuator endpoints without authentication in production environments.

• Health indicators should not perform expensive operations that could impact application performance.

• Be cautious with /actuator/beans and /actuator/mappings as they reveal internal application structure.

Reference Materials

• Endpoint quick reference

• Implementation examples

• Official documentation extract

• Auditing with Actuator

• Cloud Foundry integration

• Enabling Actuator features

• HTTP exchange recording

• JMX exposure

• Monitoring and metrics

• Logging configuration

• Metrics exporters

• Observability with Micrometer

• Process and Monitoring

• Tracing

• Scripts directory (scripts/) reserved for future automation; no runtime dependencies today.

Validation Checklist

• Confirm mvn spring-boot:run or ./gradlew bootRun exposes expected endpoints under /actuator (or custom base path).

• Verify /actuator/health/readiness returns UP with all mandatory components before promoting to production.

• Scrape /actuator/metrics or /actuator/prometheus to ensure required meters (http.server.requests, jvm.memory.used) are present.

• Run security scans to validate only intended ports and endpoints are reachable from outside the trusted network.