spring-boot-actuator
Configure Spring Boot Actuator for production-grade monitoring, health probes, secured management endpoints, and Micrometer metrics across JVM services.
When & Why to Use This Skill
This Claude skill simplifies the implementation of Spring Boot Actuator to provide production-ready observability for JVM-based services. It enables developers to efficiently configure health probes, secure management endpoints, and integrate Micrometer metrics, ensuring robust monitoring, streamlined incident diagnostics, and adherence to SRE best practices.
Use Cases
- Kubernetes Health Monitoring: Configure liveness and readiness probes to ensure seamless container orchestration and automated service recovery in cloud-native environments.
- Performance Metrics Export: Integrate Micrometer with Prometheus, OTLP, or Grafana to track JVM performance, HTTP request latency, and custom business KPIs for real-time observability.
- Security Hardening: Apply role-based access control (RBAC) and dedicated management ports to protect sensitive diagnostic data and administrative endpoints from unauthorized access.
- Incident Diagnostics & Troubleshooting: Utilize startup reports and condition evaluation logs to rapidly identify performance bottlenecks and auto-configuration issues during service deployment.
| name | spring-boot-actuator |
|---|---|
| description | Configure Spring Boot Actuator for production-grade monitoring, health probes, secured management endpoints, and Micrometer metrics across JVM services. |
| allowed-tools | Read, Write, Bash |
| category | backend |
| tags | [spring-boot, actuator, monitoring, health-checks, metrics, production] |
| version | 1.1.0 |
| context7_library | /websites/spring_io_spring-boot_3_5 |
| context7_trust_score | 7.5 |
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
- Add the starter dependency.
<!-- Maven --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>// Gradle dependencies { implementation "org.springframework.boot:spring-boot-starter-actuator" } - Restart the service and verify
/actuator/healthand/actuator/inforespond with200 OK.
Implementation Workflow
1. Expose the required endpoints
- Set
management.endpoints.web.exposure.includeto the precise list or"*"for internal deployments. - Adjust
management.endpoints.web.base-path(e.g.,/management) when the default/actuatorconflicts with routing. - Review detailed endpoint semantics in
references/endpoint-reference.md.
2. Secure management traffic
- Apply an isolated
SecurityFilterChainusingEndpointRequest.toAnyEndpoint()with role-based rules. - Combine
management.server.portwith firewall controls or service mesh policies for operator-only access. - Keep
/actuator/health/**publicly accessible only when required; otherwise enforce authentication.
3. Configure health probes
- Enable
management.endpoint.health.probes.enabled=truefor/health/livenessand/health/readiness. - Group indicators via
management.endpoint.health.group.*to match platform expectations. - Implement custom indicators by extending
HealthIndicatororReactiveHealthContributor; sample implementations live inreferences/examples.md#custom-health-indicator.
4. Publish metrics and traces
- Activate Micrometer exporters (Prometheus, OTLP, Wavefront, StatsD) via
management.metrics.export.*. - Apply
MeterRegistryCustomizerbeans to addapplication,environment, and business tags for observability correlation. - Surface HTTP request metrics with
server.observation.*configuration when using Spring Boot 3.2+.
5. Enable diagnostics tooling
- Turn on
/actuator/startup(Spring Boot 3.5+) and/actuator/conditionsduring incident response to inspect auto-configuration decisions. - Register an
HttpExchangeRepository(e.g.,InMemoryHttpExchangeRepository) before enabling/actuator/httpexchangesfor request auditing. - Consult
references/official-actuator-docs.mdfor endpoint behaviors and limits.
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
curlprobes in CI/CD pipelines.
Constraints
- Avoid exposing
/actuator/env,/actuator/configprops,/actuator/logfile, and/actuator/heapdumpon 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.
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:runor./gradlew bootRunexposes expected endpoints under/actuator(or custom base path). - Verify
/actuator/health/readinessreturnsUPwith all mandatory components before promoting to production. - Scrape
/actuator/metricsor/actuator/prometheusto 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.