spring-actuator（弹簧执行器）

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

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

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

Anti-Patterns

Quick Troubleshooting

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

External Documentation

• Spring Boot Actuator
• Actuator Endpoints
• Micrometer