Spring Boot Actuator で外形監視を実装してみた

はじめに

今まで外形監視で「200 OK」が出ていれば安心だと思っていました。
しかし詳しく調べると、実は認証ページにリダイレクトされたログイン画面が 200 を返していただけで、アプリの本当の生存確認ができていないことに気づきました。

そこで、GitHub Copilot に教えてもらった Spring Boot Actuator を導入し、認証を回避しつつ DB などの健全性まで正しく監視できる環境を作ったので、その設定をメモしておきます。

Spring Boot Actuator とは？

簡単に言うと、「アプリの健康状態を監視するための機能セット」 です。
公式ドキュメントにはこう説明されています。

Spring Boot includes a number of additional features to help you monitor and manage your application when you push it to production. (Spring Bootには、アプリケーションを本番環境にデプロイした際の監視や管理に役立つ追加機能が多数含まれています)

これを導入するだけで、自作しなくても /actuator/health などのエンドポイントが使えるようになり、アプリが本当に「健全」か（DB に接続できているか等）を即座に判定できるようになります。

Actuator でできること

Actuator を導入すると、以下のようなエンドポイントが使えるようになります。

• /actuator/health：アプリケーションの健全性確認（今回はこれを使います！）
• /actuator/metrics：メモリ使用量やリクエスト数などの統計情報
• /actuator/info：アプリケーションの任意の情報（バージョンなど）

他にもたくさんありますが、今回は「外形監視を正しく行う」ために、/actuator/health に絞って設定していきます。
（※他の機能について詳しく知りたい方は、公式ドキュメントを参照してください！）

実装

技術スタック

• 言語： Kotlin
• フレームワーク： Spring Boot 3.5.x
• セキュリティ： Spring Security
• インフラ： AWS ALB, ECS (Fargate)

依存関係の追加

まずは build.gradle.kts にライブラリを追加します。
これだけで Actuator の基本機能が使えるようになります。

build.gradle.kts

dependencies {
    // Spring Boot Actuator
    implementation("org.springframework.boot:spring-boot-starter-actuator")
}

エンドポイントの公開設定

デフォルトではセキュリティの観点から、多くのエンドポイントが隠されています。
外形監視で使う /actuator/health を詳細まで見えるように、application.yml に設定を追加します。

application.yml

management:
  endpoints:
    web:
      exposure:
        include: "health" # web 公開のデフォルト対象だが、明示しておく
  endpoint:
    health:
      show-details: always # DB 接続などの詳細ステータスも表示する

/actuator/health がブロックされてしまう場合は、 SecurityConfig.kt に監視用のパスだけを許可する設定を追加します。

SecurityConfig.kt

// SecurityConfig.kt のイメージ
authorizeHttpRequests {
    it.requestMatchers("/actuator/health").permitAll()
}

確認

ブラウザや curl でアクセスして、以下の挙動になれば成功です

• 正常時： {"status": "UP"} （HTTP 200 OK）
• 異常時（DB接続不可など）： {"status": "DOWN"} （デフォルトでは HTTP 503 Service Unavailable）

詳細ステータスが確認できたら、show-details: never にして、最小限の情報のみ公開するようにしましょう。

補足

自動設定される監視対象

ドキュメント内の Auto-configured HealthIndicators を参照してください。

ここには、Spring Boot が標準でチェックしてくれる対象が並んでいます。

• db：DB 接続
• diskSpace：ディスク容量
• ping：アプリ応答
• などなど…

ECS 環境での運用メモ

今回は ECS (Fargate) で運用していますが、Target Group のヘルスチェックパスを / から /actuator/health に変えるだけで、DB 疎通を含めた正確な切り離しができるようになりました。

ブルーグリーンデプロイをより安全にする設定

「新しい環境に切り替えた瞬間、まだアプリの準備ができてなくてエラーが出た」という事態を防ぐには、この設定が役立ちます。

application.yml

management:
  endpoint:
    health:
      probes:
        enabled: true

この設定を有効にするだけで、親エンドポイントの /actuator/health が「アプリの準備状態（Readiness）」まで考慮してくれるようになります。

これにより、たとえ ALB の向き先が /actuator/health のままでも、「起動はしたけど、まだリクエストを捌ける準備ができていない」という短い隙間時間にトラフィックが流れてしまう事故 を防げます。

おわりに

これで Spring Boot Actuator を使った外形監視が実装できました。
認証ページに騙されることなく、DB の疎通確認を含めた本当の健全性を監視できるようになりました。

初めてのライブラリを使うのはちょっと怖かったけど、使ってみてよかったです😊

Let's monitor the real health, not just the HTTP 200! 🏥