spring-boot-actuator

Spring Boot Actuator スキル

概要

• Actuator エンドポイント、プローブ、Micrometer 統合を使用して、Spring Boot サービスに本番環境向けのオブザーバビリティを提供します。
• ヘルス、メトリクス、診断の設定を標準化し、詳細なリファレンス資料は references/ に委ねます。
• セキュアな運用、SLO レポート、インシデント診断に関するプラットフォーム要件をサポートします。

使用する場面

• トリガー：「Actuator エンドポイントを有効にする」– 新規または既存の Spring Boot サービスで Actuator を初期設定します。
• トリガー：「管理ポートを保護する」– 管理トラフィックを保護する Spring Security ポリシーを適用します。
• トリガー：「ヘルスプローブを設定する」– オーケストレーター向けにレディネスグループとライブネスグループを定義します。
• トリガー：「メトリクスを Prometheus にエクスポートする」– Micrometer レジストリを接続し、メトリクスの公開を調整します。
• トリガー：「Actuator の起動をデバッグする」– エンドポイントが見つからない、または応答が遅い場合に、条件評価と起動メトリクスを調べます。

クイックスタート

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

// Gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-actuator"
}

依存関係を追加した後、エンドポイントが応答することを確認します。

curl http://localhost:8080/actuator/health
curl http://localhost:8080/actuator/info

手順

1. Actuator の依存関係を追加する

ビルド設定に spring-boot-starter-actuator を含めます。

検証：サービスを再起動し、/actuator/health と /actuator/info が 200 OK を返すことを確認します。

2. 必要なエンドポイントを公開する

• management.endpoints.web.exposure.include に、対象を絞ったリスト、または内部デプロイの場合は "*" を設定します。
• デフォルトの /actuator がルーティングと競合する場合は、management.endpoints.web.base-path（例：/management）を調整します。
• エンドポイントの詳細な動作については、references/endpoint-reference.md を確認してください。

検証：curl http://localhost:8080/actuator が公開されたエンドポイントの一覧を返すことを確認します。

3. 管理トラフィックを保護する

• ロールベースのルールを設定した、分離された SecurityFilterChain で EndpointRequest.toAnyEndpoint() を使用します。
• management.server.port とファイアウォール制御またはサービスメッシュポリシーを組み合わせ、オペレーターのみがアクセスできるようにします。
• /actuator/health/** の公開アクセスは必要な場合に限り許可し、それ以外の場合は認証を必須にします。

検証：保護されたエンドポイントへの未認証リクエストが 401 Unauthorized を返すことを確認します。

4. ヘルスプローブを設定する

• /health/liveness と /health/readiness を有効にするため、management.endpoint.health.probes.enabled=true を設定します。
• management.endpoint.health.group.* でインジケーターをグループ化し、プラットフォームの要件に合わせます。
• HealthIndicator または ReactiveHealthContributor を拡張してカスタムインジケーターを実装します。実装例は references/examples.md#custom-health-indicator にあります。

検証：本番環境への昇格前に、必須コンポーネントがすべて揃った状態で /actuator/health/readiness が UP を返すことを確認します。

5. メトリクスとトレースを公開する

• management.metrics.export.* で Micrometer エクスポーター（Prometheus、OTLP、Wavefront、StatsD）を有効にします。
• MeterRegistryCustomizer Bean を適用して、オブザーバビリティの相関分析に必要な application、environment、ビジネスタグを追加します。
• Spring Boot 3.2+ を使用している場合は、server.observation.* の設定で HTTP リクエストのメトリクスを公開します。

検証：/actuator/prometheus をスクレイプし、必須のメーター（http.server.requests、jvm.memory.used）が存在することを確認します。

6. 診断ツールを有効にする

• インシデント対応時に /actuator/startup（Spring Boot 3.5+）と /actuator/conditions を有効にし、自動構成の判断内容を調べます。
• リクエスト監査用に /actuator/httpexchanges を有効にする前に、HttpExchangeRepository（例：InMemoryHttpExchangeRepository）を登録します。
• エンドポイントの動作と制限については、references/endpoint-reference.md を参照してください。

検証：/actuator/startup と /actuator/conditions が有効な JSON ペイロードを返すことを確認します。

例

基本 – health と info を安全に公開する

management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  endpoint:
    health:
      show-details: never

中級 – カスタムインジケーターを使用したレディネスグループ

@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

上級 – Prometheus エクスポート対応の専用管理ポート

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

エンドツーエンドのサンプルは、references/examples.md にあります。

ベストプラクティス

• コンテキストを節約するため、SKILL.md は簡潔に保ち、詳細なドキュメントは references/ を参照してください。
• 最小権限の原則を適用し、必要なエンドポイントのみを公開して、機密性の高いエンドポイントへのアクセスを制限してください。
• 環境間の整合性を保つため、プロファイルごとの YAML を使って不変の設定を適用してください。
• スクレイピングによる不正利用やブルートフォース攻撃を検出できるよう、アクチュエーターへのトラフィックを個別に監視してください。
• CI/CD パイプラインで curl プローブをスクリプト化して、回帰チェックを自動化してください。

制約と警告

• /actuator/env、/actuator/configprops、/actuator/logfile、/actuator/heapdump をパブリックネットワークに公開しないでください。
• 絶対に必要な場合を除き、イベントループスレッドをブロックしたり、250 ms を超えたりするカスタムヘルスインジケーターを配布しないでください。
• アクチュエーターのメトリクスエクスポーターが、サポート対象の Micrometer レジストリで動作することを確認してください。サポート対象外のエクスポーターには、カスタムレジストリ Bean が必要です。
• Spring Boot 3.5.x の規約との互換性を維持してください。古いバージョンでは、プローブやオブザベーション機能が利用できない場合があります。
• 本番環境では、認証なしでアクチュエーターのエンドポイントを公開しないでください。
• ヘルスインジケーターで、アプリケーションのパフォーマンスに影響する可能性のある高コストな処理を実行しないでください。
• /actuator/beans と /actuator/mappings は、アプリケーション内部の構造を明らかにするため、慎重に扱ってください。

参考資料

• エンドポイントのクイックリファレンス
• 実装例
• 公式ドキュメントの抜粋
• Actuator を使用した監査
• Cloud Foundry との統合
• Actuator 機能の有効化
• HTTP エクスチェンジの記録
• JMX への公開
• 監視とメトリクス
• ロギングの設定
• メトリクスエクスポーター
• Micrometer によるオブザーバビリティ
• プロセスと監視
• トレーシング
• スクリプトディレクトリ（scripts/）は今後の自動化用に確保されています。現時点で実行時の依存関係はありません。

検証チェックリスト

• mvn spring-boot:run または ./gradlew bootRun を実行し、期待されるエンドポイントが /actuator（またはカスタムのベースパス）で公開されることを確認してください。
• 本番環境への移行前に、必須コンポーネントがすべて揃った状態で /actuator/health/readiness が UP を返すことを確認してください。
• /actuator/metrics または /actuator/prometheus をスクレイピングし、必要なメーター（http.server.requests、jvm.memory.used）が存在することを確認してください。
• セキュリティスキャンを実行して、信頼されたネットワークの外部から到達できるのが、意図したポートとエンドポイントのみであることを検証してください。