Spring Boot Actuator スキル

概要

• Actuator エンドポイント、プローブ、Micrometer 統合を使用して、Spring Boot サービスに本番対応の可観測性を提供します。
• ヘルス、メトリクス、診断構成を標準化し、詳細なリファレンス資料は references/ に委譲します。
• セキュアな運用、SLO レポート、インシデント診断のプラットフォーム要件をサポートします。

使用時期

• トリガー：「actuator エンドポイントを有効にする」– 新規または既存の Spring Boot サービス向けに Actuator をブートストラップします。
• トリガー：「管理ポートをセキュアにする」– Spring Security ポリシーを適用して管理トラフィックを保護します。
• トリガー：「ヘルスプローブを設定する」– オーケストレーターのための readiness グループと liveness グループを定義します。
• トリガー：「メトリクスを prometheus にエクスポートする」– Micrometer レジストリを連携させ、メトリクス公開をチューニングします。
• トリガー：「actuator 起動をデバッグする」– エンドポイントが不足している、または遅い場合に条件評価と起動メトリクスを検査します。

クイックスタート

<!-- Maven -->
<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. 管理トラフィックをセキュアにする

• EndpointRequest.toAnyEndpoint() とロールベースのルールを使用して、分離された SecurityFilterChain を適用します。
• management.server.port をファイアウォール制御またはサービスメッシュポリシーと組み合わせて、オペレーター専用アクセスを実現します。
• /actuator/health/** を公開アクセス可能にするのは必要な場合のみに留め、それ以外は認証を強制します。

検証: 保護されたエンドポイントへの認証なしリクエストは 401 Unauthorized を返します。

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

• management.endpoint.health.probes.enabled=true を有効にして /health/liveness と /health/readiness を使用可能にします。
• 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 ビーンを適用して、可観測性の相関関係のための 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 ペイロードを返します。

例

基本 – ヘルスと info を安全に公開

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

中級 – カスタムインジケーター付きの readiness グループ

@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 を使用してイミュータブルな設定を適用し、環境を合わせます。
• actuator トラフィックを別途監視して、スクレイピングの悪用またはブルートフォース攻撃を検出します。
• CI/CD パイプラインで curl プローブのスクリプト化によるリグレッションチェックを自動化します。

制約と警告

• 公開ネットワーク上では /actuator/env、/actuator/configprops、/actuator/logfile、/actuator/heapdump を公開しないようにします。
• 絶対に必要な場合を除き、イベントループスレッドをブロックしたり 250 ms を超える実行時間を持つカスタムヘルスインジケーターをシップしないでください。
• Actuator メトリクスエクスポーターが サポートされている Micrometer レジストリで実行されることを確認します。サポートされていないエクスポーターはカスタムレジストリビーンが必要です。
• Spring Boot 3.5.x の慣例との互換性を保持します。古いバージョンはプローブと observation 機能が不足している可能性があります。
• 本番環境で認証なしに actuator エンドポイントを公開しないでください。
• ヘルスインジケーターは、アプリケーションパフォーマンスに影響を与える可能性のあるコストの高い操作を実行しないようにしてください。
• /actuator/beans と /actuator/mappings は内部アプリケーション構造を明かすため、注意が必要です。

リファレンス資料

• エンドポイントクイックリファレンス
• 実装例
• 公式ドキュメント抜粋
• Actuator を使用した監査
• Cloud Foundry 統合
• Actuator 機能を有効にする
• HTTP exchange 記録
• JMX 公開
• 監視とメトリクス
• ログ設定
• メトリクスエクスポーター
• Micrometer を使用した可観測性
• プロセスと監視
• トレーシング
• スクリプトディレクトリ（scripts/）は将来の自動化向けに予約済みです。現在はランタイム依存関係はありません。

検証チェックリスト

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