Spring Boot Actuatorとは

Spring Boot Actuatorとは、動いているアプリの状態を外から確認するためのHTTPエンドポイント群を、スターターを1つ追加するだけで使えるようにしてくれるSpring Bootの機能です。/actuator/health で死活、/actuator/metrics でJVMやHTTPの数値、/actuator/info でバージョン情報、といった具合に監視に必要な情報を取り出せます。

内部ではメトリクスライブラリのMicrometerと連携していて、PrometheusやDatadogなどの監視基盤へそのまま数値を送れるのも大きな特徴です。Actuatorでできることをざっくり分けると次の4つになります。

  • アプリが生きているかどうかを返す（Health Check）
  • バージョンやビルド情報など、アプリの基本情報を返す（Info）
  • メモリやスレッド、GC、HTTPリクエストなどのメトリクスを返す（Metrics）
  • 設定値やログレベルを確認・変更する（運用向け）

開発中のデバッグだけでなく、本番運用での監視や障害対応のスピードを上げる基盤として、とても便利です。なお、この記事の設定例はSpring Boot 3.x系で動作確認しています。

Spring Boot Actuatorのエンドポイント一覧（早見表）

spring-boot-starter-actuator を入れると使えるようになる主なエンドポイントを、先に一覧で押さえておきましょう。本番でそのまま公開してよいものと、認証や内部ネットワーク限定にすべきものが混ざっているので、右端の列を目安にしてください。依存関係の追加と最小の application.yml は、この後のセクションで順に設定していきます。

パス目的本番公開の目安
GET /actuator/health死活監視（UP / DOWN）◎ 公開推奨
GET /actuator/health/livenessプロセス生存確認（K8s liveness）◎
GET /actuator/health/readiness受け入れ可否確認（K8s readiness）◎
GET /actuator/infoバージョン・ビルド情報○
GET /actuator/metricsメトリクス一覧（JVM / HTTP / GC など）△ 認証推奨
GET /actuator/metrics/{name}個別メトリクス値△ 認証推奨
GET /actuator/prometheusPrometheus スクレイプ用△ 内部網限定推奨
GET /actuator/env環境変数・設定値✕ 公開非推奨
GET /actuator/configprops@ConfigurationProperties 一覧✕ 公開非推奨
GET /actuator/loggersログレベル参照/変更✕ 公開非推奨

このうち health / info / metrics / prometheus の使い方は、この後で1つずつ触っていきます。env や configprops のような公開非推奨のものは設定値がそのまま見えてしまうため、本番向けのポイントの節で守り方を説明します。

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

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

個別の値を見るには、メトリクス名をパスに続けます。まずはJVMのヒープ使用量を見てみましょう。

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

レスポンスには measurements があり、現在値が入っています。あわせて availableTags という項目も返ってきていて、ここに並ぶタグで値を絞り込めます。たとえばHTTPリクエストの件数と所要時間を持つ http.server.requests を、特定のURIとステータスコードに絞るとこうなります。

curl -s "http://localhost:8080/actuator/metrics/http.server.requests?tag=uri:/api/users&tag=status:200"

最初に覚えておくと便利なメトリクス名は次のあたりです。

メトリクス名分かること
jvm.memory.used / jvm.memory.maxヒープ・非ヒープのメモリ使用量と上限
jvm.gc.pauseGCの停止時間と回数
jvm.threads.live稼働中のスレッド数
http.server.requestsHTTPリクエストの件数・所要時間（uri / status / method タグ付き）
hikaricp.connections.activeDBコネクションプールの使用中コネクション数（DataSource利用時のみ）
process.cpu.usage / system.cpu.usageプロセスとOS全体のCPU使用率

ここまで確認できれば、あとは監視基盤側で集めるだけです。コネクションプール指標の見方と枯渇の検知方法は Spring BootでHikariCPのコネクションプールをMicrometer・Actuatorで監視する方法 で詳しく解説しています。

configprops / env / loggersは運用向けのエンドポイント

早見表で公開非推奨にしていた3つは、使いどころを知っておくと障害調査でかなり役立ちます。ローカルや検証環境で試すときは、次のように公開対象へ追加します。

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,configprops,env,loggers

/actuator/configprops は、@ConfigurationProperties でバインドされている設定値の一覧をプレフィックスごとにまとめて返します。「この設定、結局どの値で動いているんだっけ」を確かめたいときに便利で、/actuator/configprops/{prefix} のようにプレフィックスを指定すれば1グループだけを取り出せます。

curl -s "http://localhost:8080/actuator/configprops/spring.datasource"

/actuator/env はプロパティソースごとの設定値と環境変数を返し、/actuator/env/{プロパティ名} でどのソースの値が採用されたかを追えます。/actuator/loggers はロガーごとのログレベルを返し、POSTすれば再起動なしにレベルを変更できます。

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"configuredLevel":"DEBUG"}' \
  http://localhost:8080/actuator/loggers/com.example.app

便利な反面、configprops と env には接続先やパスワードの設定キーがそのまま含まれます。Spring Boot 3.xでは値がデフォルトで ****** にマスクされます（show-values: when_authorized にすると認証済みのときだけ値を表示できます）が、どのキーが存在するか自体が攻撃のヒントになるため、本番では公開しないか、次のセクションで説明する認証の内側に置くのが基本です。

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

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 のように分けられます。

Spring SecurityでActuatorエンドポイントを保護する

特に env や configprops は設定値がそのまま見えてしまうため、公開範囲を絞るだけでなく認証もかけておきたいところです。Spring Securityを使うと、Actuatorのエンドポイントだけを対象にした認証ルールをまとめて書けます。

まず spring-boot-starter-security を依存関係に追加します。

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

次に、Actuator専用の SecurityFilterChain を定義します。EndpointRequest.toAnyEndpoint() がActuatorの全エンドポイントにマッチするので、ベースパスやポートを変えていてもそのまま使えます。アプリ側にすでに SecurityFilterChain がある場合は、こちらを @Order で先に評価させてください。

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.boot.actuate.health.HealthEndpoint;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    @Order(1)
    public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(EndpointRequest.to(HealthEndpoint.class)).permitAll()
                .anyRequest().hasRole("ACTUATOR"))
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

ポイントは、死活監視に使う health だけは認証なしで通し、それ以外は ACTUATOR ロールを持つユーザーに限定していることです。ロードバランサーやKubernetesのプローブは認証ヘッダーを付けられないことが多いので、この分け方が実務では扱いやすいです。

監視用のユーザーは、まずは application.yml の設定で用意できます。パスワードは環境変数から渡しましょう。

spring:
  security:
    user:
      name: monitor
      password: ${ACTUATOR_PASSWORD}
      roles: ACTUATOR
curl -s -u monitor:${ACTUATOR_PASSWORD} http://localhost:8080/actuator/metrics

show-details: when_authorized にしていたhealthの詳細も、認証情報を付けて /actuator/health を叩いたときだけ表示されるようになります。Spring Security自体の導入手順やBasic認証とフォーム認証の違いは Spring BootのSpring Securityで始める認証入門 - Basic認証からフォーム認証まで で解説しています。

基本方針はシンプルで、公開範囲を絞る、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

Kubernetes運用での実践設定

Kubernetesで運用する場合は、liveness と readiness を分けて使うと安定します。

management:
  endpoint:
    health:
      probes:
        enabled: true
  endpoints:
    web:
      exposure:
        include: health,info,prometheus

これで、次のエンドポイントが利用できます。

  • GET /actuator/health/liveness
  • GET /actuator/health/readiness

「プロセスは生きているがDBに繋がらない」状態を見分けやすくなるため、再起動ループや誤判定を減らせます。

本番向けの最小公開テンプレート

公開しすぎを防ぐため、最初は次の構成がおすすめです。

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    health:
      show-details: when_authorized
  server:
    port: 9001

加えて、管理ポートは内部ネットワークのみに閉じ、アプリ本体の公開ポートとは分離すると安全です。

監視設計で先に決めること

Actuatorを導入したら、次を先に決めると運用が安定します。

  • 監視のSLO/SLAに合わせたアラート閾値
  • どのメトリクスをダッシュボード化するか（CPU、メモリ、HTTP、エラー率）
  • 障害時に誰へ通知するか（オンコールルール）
  • デプロイ単位でinfo.app.versionを必ず更新する運用

「導入だけ」で終わらせず、通知と運用フローまで決めることが実効性につながります。

まとめ

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

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

ここまでできると、障害対応や運用がぐっと楽になります。次のステップとしては、Prometheusで集めたメトリクスをGrafanaでダッシュボード化する手順を Spring BootのメトリクスをPrometheus＋Grafanaで可視化する で、DBや外部APIの疎通を含めた独自ヘルスチェックの作り方を Spring Bootでカスタムヘルスチェック（HealthIndicator）と独自Actuatorエンドポイントを作る方法 で解説しているので、あわせて読んでみてください。

ぜひ活用してみてください！

次に読みたい関連記事