はじめてのSpring Boot Actuator入門

Spring Boot Actuatorとは

Spring Boot Actuatorは、アプリの“健康状態”や“動き具合”を外から確認できる仕組みを提供してくれる機能です。たとえば次のような情報をHTTPで取得できます。

  • アプリが生きているかどうか（Health Check）
  • アプリの基本情報（Info）
  • メモリやスレッド、GCなどのメトリクス（Metrics）
  • 設定値やログレベルの確認と変更（運用向け）

開発中のデバッグだけでなく、本番運用での監視や障害対応のスピードを上げる“基盤”としてとても便利です。

まずは依存関係を追加する

Spring Boot Actuatorはスターターを追加するだけで使えます。

Maven

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

Gradle

implementation 'org.springframework.boot:spring-boot-starter-actuator'

起動したら、まずは次のURLにアクセスしてみてください。

  • GET /actuator

ただし、初期設定では公開されるエンドポイントが限定されているため、思った表示が出ないことがあります。次で設定します。

エンドポイント公開を設定する

Actuatorの各機能はEndpoint（エンドポイント）として提供されます。安全のため、最初は必要最低限しか公開されません。

application.yml の例です。

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

これで以下が使えるようになります。

  • GET /actuator/health
  • GET /actuator/info
  • GET /actuator/metrics

動作確認は curl だと手軽です。

curl -s http://localhost:8080/actuator/health
curl -s http://localhost:8080/actuator/info
curl -s http://localhost:8080/actuator/metrics

すべて公開したい場合は * も使えますが、セキュリティ的に本番ではおすすめしません。

management:
  endpoints:
    web:
      exposure:
        include: "*"

よく使うエンドポイントを触ってみる

Healthで死活監視を作る

/actuator/health は監視の基本です。

curl -s http://localhost:8080/actuator/health

多くの場合はこんな形で返ります。

  • status: UP なら正常
  • status: DOWN や OUT_OF_SERVICE なら異常

詳細を出したい場合は、次の設定が便利です。

management:
  endpoint:
    health:
      show-details: when_authorized

show-details は情報漏えいに繋がることがあるので、always ではなく when_authorized を基本にすると安心です。

Infoでアプリ情報を返す

/actuator/info は、バージョンやビルド情報など「運用で欲しい情報」を返すのに向いています。

management:
  info:
    env:
      enabled: true

info:
  app:
    name: sample-api
    version: 1.0.0
curl -s http://localhost:8080/actuator/info

デプロイしたものが「どのバージョンか」をすぐ確認できるようになるので、地味に便利です。

Metricsで状況を数値で見る

/actuator/metrics は、メトリクス名の一覧を返します。

curl -s http://localhost:8080/actuator/metrics

個別のメトリクスを見るには、メトリクス名を指定します。

curl -s "http://localhost:8080/actuator/metrics/jvm.memory.used"

レスポンスには measurements があり、現在値が入っています。まずは「取れる」ことを確認できればOKです。

本番向けに安全に使うためのポイント

Actuatorは便利な反面、公開の仕方を間違えると危険です。最低限、次は押さえておくのがおすすめです。

公開するエンドポイントを絞る

まずは必要なものだけ include しましょう。

management:
  endpoints:
    web:
      exposure:
        include: health,info

運用でメトリクスが必要なら metrics を追加、Prometheusを使うなら prometheus を追加、という感じで段階的に増やすのが安全です。

Actuatorのベースパスを変える

デフォルトは /actuator ですが、変えたい場合はこうします。

management:
  endpoints:
    web:
      base-path: /management

Actuator専用のポートで分離する

アプリの公開ポートと分けると、ネットワーク的に守りやすくなります。

management:
  server:
    port: 9001

これで通常のAPIは :8080、Actuatorは :9001 のように分けられます。

認証を必ずかける

特に env や configprops などは設定値が見えてしまうため、公開には要注意です。基本方針はシンプルで、

  • 公開範囲を絞る
  • 必要ならSpring Securityで認証する
  • 可能なら管理ネットワークのみに閉じる

この3点セットで守るのが堅実です。

カスタムヘルスチェックを追加する

「DBに繋がるか」「外部APIが応答するか」など、自分のアプリに合わせたチェックを追加したくなります。そんなときは HealthIndicator を実装します。

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class ExternalApiHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        boolean ok = pingExternalApi();
        if (ok) {
            return Health.up().withDetail("externalApi", "reachable").build();
        }
        return Health.down().withDetail("externalApi", "unreachable").build();
    }

    private boolean pingExternalApi() {
        // ここで疎通確認をする（タイムアウト短め推奨）
        return true;
    }
}

こうすると /actuator/health の結果に組み込まれます。監視側が「どこが死んでいるか」を素早く切り分けできるようになります。

Prometheusとつなぐと監視が一気に楽になる

Actuatorは Micrometer と連携しており、Prometheus向けのエンドポイントも用意できます。Prometheusを使う場合は依存関係を追加します。

Maven

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Gradle

implementation 'io.micrometer:micrometer-registry-prometheus'

公開設定も追加します。

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus

すると次が取れます。

  • GET /actuator/prometheus

Prometheusが定期的にスクレイプし、Grafanaで可視化する、という監視の仕組みが簡単に作れます。

つまずきやすいポイント

404になる

多くは「エンドポイントを公開していない」か「ベースパスを変えている」のどちらかです。

  • management.endpoints.web.exposure.include を確認
  • management.endpoints.web.base-path を確認

healthの詳細が出ない

show-details の設定次第です。まずは開発環境だけ always にして挙動を理解し、本番は when_authorized に戻すのが安全です。

management:
  endpoint:
    health:
      show-details: always

まとめ

Spring Boot Actuatorを導入すると、アプリの状態を外から確認できる“運用の入り口”が一気に整います。

  • まずは health と info を公開して監視の土台を作る
  • 必要に応じて metrics や prometheus を段階的に追加する
  • 本番では公開範囲と認証をしっかり設計する

ここまでできると、障害対応や運用がぐっと楽になります。次は「Spring SecurityでActuatorを保護する」や「Grafanaでダッシュボード化する」あたりに進むと、さらに実戦的になります。 ぜひ活用してみてください！

関連記事