Spring Boot Actuator

Quick Start

<!-- pom.xml --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> </dependency>

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

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

management: health: db: enabled: true redis: enabled: true diskspace: enabled: true threshold: 10MB

Custom Health Indicator

@Component public class ExternalServiceHealthIndicator implements HealthIndicator {

private final RestClient restClient;

@Override
public Health health() {
    try {
        long startTime = System.currentTimeMillis();
        ResponseEntity<Void> 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 for composite indicators, health groups, and availability management.

Kubernetes Probes

management: endpoint: health: probes: enabled: true group: liveness: include: livenessState readiness: include: readinessState,db,redis

health: livenessstate: enabled: true readinessstate: enabled: true

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 for availability state management and K8s probe configuration.

Metrics with Micrometer

management: metrics: enable: all: true tags: application: ${spring.application.name} environment: ${spring.profiles.active:default} distribution: percentiles-histogram: http.server.requests: true

Custom Metrics

@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 for annotations, Prometheus config, and Grafana alerts.

Prometheus Integration

management: endpoints: web: exposure: include: prometheus prometheus: metrics: export: enabled: true

prometheus.yml

scrape_configs:

• job_name: 'spring-boot-app' metrics_path: '/actuator/prometheus' scrape_interval: 15s static_configs:
  • targets: ['localhost:8080']

Security

@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();
}

}

Separate management port

management: server: port: 9090 address: 127.0.0.1

Full Reference: See 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 Indicators, K8s Probes, Availability

metrics.md Micrometer, Prometheus, Grafana Alerts

custom-endpoints.md Custom Endpoints, Security, Testing

External Documentation

• Spring Boot Actuator

• Actuator Endpoints

• Micrometer