spring-boot-actuator

# 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
```xml
<!-- Maven -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
```
```gradle
// Gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-actuator"
}
```
After adding the dependency, verify endpoints respond:
```bash
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
```yaml
management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  endpoint:
    health:
      show-details: never
```

### Intermediate – Readiness group with custom indicator
```java
@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();
    }
}
```
```yaml
management:
  endpoint:
    health:
      probes:
        enabled: true
      group:
        readiness:
          include: "readinessState,db,paymentsGateway"
          show-details: always
```

### Advanced – Dedicated management port with Prometheus export
```yaml
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"
```
```java
@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 document