--- name: spring-actuator description: | Spring Boot Actuator for monitoring and management. Covers health indicators, metrics with Micrometer, Prometheus integration, custom endpoints, Kubernetes probes, and endpoint security. USE WHEN: user mentions "actuator", "health endpoint", "metrics", "prometheus", "micrometer", "kubernetes probes", "liveness", "readiness", "/health", "/metrics" DO NOT USE FOR: application profiling - use `spring-profiles` instead, distributed tracing - use `micrometer-tracing` instead allowed-tools: Read, Grep, Glob, Write, Edit --- # Spring Boot Actuator ## Quick Start ```xml org.springframework.boot spring-boot-starter-actuator io.micrometer micrometer-registry-prometheus ``` ```yaml # application.yml management: endpoints: web: exposure: include: health,info,metrics,prometheus endpoint: health: show-details: when_authorized info: env: enabled: true info: app: name: @project.name@ version: @project.version@ ``` --- ## Endpoints Configuration ```yaml management: endpoints: web: exposure: include: "*" # Dev: all # include: health,info,metrics,prometheus # Prod exclude: shutdown,threaddump base-path: /actuator endpoint: health: enabled: true show-details: when_authorized show-components: when_authorized shutdown: enabled: false # Dangerous in prod ``` ### Available Endpoints | Endpoint | Description | Default | |----------|-------------|---------| | `/health` | Health status | Enabled | | `/info` | App info | Enabled | | `/metrics` | Metrics | Enabled | | `/prometheus` | Prometheus format | Enabled* | | `/env` | Environment properties | Disabled | | `/configprops` | Configuration properties | Disabled | | `/beans` | All beans | Disabled | | `/mappings` | Request mappings | Disabled | | `/loggers` | Logger levels | Disabled | | `/threaddump` | Thread dump | Disabled | | `/shutdown` | Graceful shutdown | Disabled | --- ## Health Indicators ```yaml management: health: db: enabled: true redis: enabled: true diskspace: enabled: true threshold: 10MB ``` ### Custom Health Indicator ```java @Component public class ExternalServiceHealthIndicator implements HealthIndicator { private final RestClient restClient; @Override public Health health() { try { long startTime = System.currentTimeMillis(); ResponseEntity response = restClient.get() .uri("/health") .retrieve() .toBodilessEntity(); long responseTime = System.currentTimeMillis() - startTime; if (response.getStatusCode().is2xxSuccessful()) { return Health.up() .withDetail("service", "external-api") .withDetail("responseTime", responseTime + "ms") .build(); } return Health.down().build(); } catch (Exception e) { return Health.down() .withDetail("error", e.getMessage()) .build(); } } } ``` > **Full Reference**: See [health.md](health.md) for composite indicators, health groups, and availability management. --- ## Kubernetes Probes ```yaml management: endpoint: health: probes: enabled: true group: liveness: include: livenessState readiness: include: readinessState,db,redis health: livenessstate: enabled: true readinessstate: enabled: true ``` ```yaml # Kubernetes deployment spec: containers: - name: app livenessProbe: httpGet: path: /actuator/health/liveness port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 10 periodSeconds: 5 ``` > **Full Reference**: See [health.md](health.md) for availability state management and K8s probe configuration. --- ## Metrics with Micrometer ```yaml management: metrics: enable: all: true tags: application: ${spring.application.name} environment: ${spring.profiles.active:default} distribution: percentiles-histogram: http.server.requests: true ``` ### Custom Metrics ```java @Service public class OrderService { private final MeterRegistry meterRegistry; private final Counter orderCounter; private final Timer orderProcessingTimer; public OrderService(MeterRegistry meterRegistry) { this.meterRegistry = meterRegistry; this.orderCounter = Counter.builder("orders.created") .description("Total orders created") .register(meterRegistry); this.orderProcessingTimer = Timer.builder("orders.processing.time") .publishPercentiles(0.5, 0.95, 0.99) .register(meterRegistry); } public Order createOrder(OrderRequest request) { return orderProcessingTimer.record(() -> { Order order = processOrder(request); orderCounter.increment(); return order; }); } } ``` > **Full Reference**: See [metrics.md](metrics.md) for annotations, Prometheus config, and Grafana alerts. --- ## Prometheus Integration ```yaml management: endpoints: web: exposure: include: prometheus prometheus: metrics: export: enabled: true ``` ```yaml # prometheus.yml scrape_configs: - job_name: 'spring-boot-app' metrics_path: '/actuator/prometheus' scrape_interval: 15s static_configs: - targets: ['localhost:8080'] ``` --- ## Security ```java @Configuration @EnableWebSecurity public class ActuatorSecurityConfig { @Bean public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception { return http .securityMatcher(EndpointRequest.toAnyEndpoint()) .authorizeHttpRequests(auth -> auth .requestMatchers(EndpointRequest.to("health", "info")).permitAll() .requestMatchers(EndpointRequest.to("prometheus")).permitAll() .requestMatchers(EndpointRequest.to("env", "beans")).hasRole("ADMIN") .anyRequest().authenticated() ) .httpBasic(Customizer.withDefaults()) .build(); } } ``` ```yaml # Separate management port management: server: port: 9090 address: 127.0.0.1 ``` > **Full Reference**: See [custom-endpoints.md](custom-endpoints.md) for custom endpoints and testing. --- ## Best Practices | Do | Don't | |----|-------| | Expose only necessary endpoints in prod | Expose all endpoints | | Use health groups for K8s probes | Use single health endpoint | | Configure metrics with consistent tags | Use high-cardinality tags | | Implement custom health indicators | Rely only on built-in | | Separate management port in production | Use same port as app | --- ## When NOT to Use This Skill - **Application profiling** - Use `spring-profiles` for environment config - **Distributed tracing** - Use `micrometer-tracing` for trace context - **Log aggregation** - Use logging frameworks and ELK/Loki - **APM tools** - Actuator complements Datadog, New Relic --- ## Common Pitfalls | Error | Cause | Solution | |-------|-------|----------| | Endpoints not exposed | Missing config | Add to `management.endpoints.web.exposure.include` | | Health always UP | Indicators not configured | Verify dependencies in classpath | | Metrics missing | Registry not configured | Add `micrometer-registry-prometheus` | | Security bypass | Endpoints public | Configure security for actuator | | Memory leak | High cardinality tags | Avoid userId, requestId as tags | --- ## Anti-Patterns | Anti-Pattern | Problem | Solution | |--------------|---------|----------| | Exposing all endpoints in prod | Security risk | Limit to health, metrics, prometheus | | High cardinality metric tags | Memory explosion | Use bounded tag values | | No auth on sensitive endpoints | Information leak | Configure Spring Security | | Ignoring health groups | Poor K8s integration | Use liveness/readiness groups | --- ## Quick Troubleshooting | Problem | Diagnostic | Fix | |---------|------------|-----| | Endpoints not exposed | Check config | Add to exposure.include | | Health always DOWN | Check component | Fix failing indicator | | Metrics missing | Check registry | Add Micrometer dependency | | 401 on endpoints | Security blocking | Configure actuator security | | Prometheus not scraping | Check path | Verify `/actuator/prometheus` | --- ## Production Checklist - [ ] Health endpoints configured - [ ] K8s probes (liveness, readiness) active - [ ] Prometheus scraping configured - [ ] Alert rules defined - [ ] Security on sensitive endpoints - [ ] Custom health indicators for external deps - [ ] Business metrics implemented - [ ] Grafana dashboard configured --- ## Reference Files | File | Content | |------|---------| | [health.md](health.md) | Health Indicators, K8s Probes, Availability | | [metrics.md](metrics.md) | Micrometer, Prometheus, Grafana Alerts | | [custom-endpoints.md](custom-endpoints.md) | Custom Endpoints, Security, Testing | --- ## External Documentation - [Spring Boot Actuator](https://docs.spring.io/spring-boot/reference/actuator/index.html) - [Actuator Endpoints](https://docs.spring.io/spring-boot/reference/actuator/endpoints.html) - [Micrometer](https://micrometer.io/docs)