Spring Boot Actuatorの使い方｜エンドポイント公開設定と監視・診断を実装する

Spring Boot Actuatorは、アプリの稼働状態・メトリクス・設定情報をHTTPやJMXのエンドポイントとして公開し、本番運用の監視と障害調査を支えるモジュールです。依存関係を1つ追加するだけで使い始められますが、「エンドポイントにアクセスできない」「management.security.enabled が効かない」「httptrace が見当たらない」といったつまずきは、デフォルトの公開範囲やSpring Boot 3・4での仕様変更を知らないことが原因です。この記事では、導入と公開設定（management.endpoints.web.exposure.include）、health・info・metricsなど主要エンドポイントの使い方、SecurityFilterChain による保護、そしてSpring Boot 3・4で変わった点までを、動くコードで解説します。

まとめ：Spring Boot Actuator設定の要点

• 導入は spring-boot-starter-actuator を追加するだけ。HTTPで公開されるのは初期状態では health エンドポイントのみ。
• 他のエンドポイントは management.endpoints.web.exposure.include で明示的に公開する。全公開の * は本番非推奨。
• env・beansなどは設定値やBean構成を露出するため、本番では SecurityFilterChain で認証をかけ、healthだけ公開に留めるのが基本。
• Spring Boot 3.0で httptrace は httpexchanges に改称、WebSecurityConfigurerAdapter は廃止（Security 6）。info.* は2.6以降 management.info.env.enabled=true が必要。最新は4.0（2025年11月）／4.1（2026年6月）。

Spring Boot Actuatorとは：本番運用向けの監視・診断機能

Actuatorは、Spring Bootの「production-ready features（本番対応機能）」を提供するモジュールです。アプリを再ビルドせずに、稼働状態・JVMメトリクス・環境プロパティ・Bean構成・URLマッピングといった内部情報を、/actuator 配下のエンドポイントとして参照できます。用途は大きく3つに分かれます。

• ヘルスチェック：Kubernetesのliveness／readinessプローブやロードバランサの死活監視に /actuator/health を使う。
• メトリクス監視：Micrometer経由でJVMメモリ・スレッド・GC・HTTPリクエスト数を収集し、Prometheusなどへ送る。
• 構成診断：起動後に有効になっているプロパティやBeanを env・beans・mappings で確認し、設定ミスを切り分ける。

逆に、外部公開のAPIサーバーでActuatorを無防備に全公開するのは避けるべきです。env や configprops は接続情報を含む設定値を返すため、情報漏えいの入口になります。公開範囲を絞り、認証をかける前提で使います。主要なエンドポイントは次のとおりです。

導入手順とエンドポイントの公開設定

依存関係の追加（Maven・Gradle）

Mavenならpom.xmlに、Gradleならbuild.gradleにスターターを追加します。バージョンはSpring BootのBOMが管理するため、個別指定は不要です。

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

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

追加してアプリを起動すると /actuator/health が有効になります。ここで他のエンドポイントも見えると思い込むと、次で説明する公開設定でつまずきます。

公開エンドポイントの指定（management.endpoints.web.exposure.include）

「エンドポイントを追加したのにアクセスできない」の大半は、HTTP公開の初期値が health のみだからです。health以外をHTTP経由で見るには、公開するIDを management.endpoints.web.exposure.include に列挙します。application.properties／application.ymlのどちらでも指定できます。

# 公開するエンドポイントを明示する（初期状態は health のみ）
management.endpoints.web.exposure.include=health,info,metrics

# 全公開したうえで特定のものだけ隠す場合（本番では非推奨）
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

ここで混同しやすいのが enabled と exposure の違いです。management.endpoint.<id>.enabled はエンドポイント自体の有効・無効を切り替え、exposure.include は「有効なエンドポイントをHTTPで見せるか」を制御します。たとえばhealthエンドポイントごと止めるなら次のように書きます。公開パスの接頭辞 /actuator も変更できます。

# health エンドポイント自体を無効化する
management.endpoint.health.enabled=false

# 公開パスの接頭辞を /actuator から変更する
management.endpoints.web.base-path=/manage

つまり、公開したいのに出てこないときはまず exposure.include に対象IDを足す、特定機能を完全に止めたいときは enabled=false を使う、と切り分けます。

主要エンドポイントの使い方

health：稼働状態の確認とカスタムHealthIndicator

healthエンドポイントは、アプリ本体に加えてデータベースやディスク容量など、自動構成された依存先の状態をまとめて返します。初期状態のレスポンスは {"status":"UP"} のように状態だけで、詳細は伏せられます。詳細を出すには show-details を設定します。値は never（既定）・when-authorized・always の3種類です。

management.endpoints.web.exposure.include=health
# 認証済みユーザーにだけ内訳を見せる（本番の推奨）
management.endpoint.health.show-details=when-authorized
management.endpoint.health.roles=ADMIN

アプリ独自の条件で健全性を判定したいときは HealthIndicator を実装します。外部APIへの疎通など、フレームワークが知らない依存を監視対象に加えられます。

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() {
        if (!isReachable()) {
            return Health.down()
                    .withDetail("api", "unreachable")
                    .build();
        }
        return Health.up().build();
    }

    private boolean isReachable() {
        // 実際の疎通確認ロジックを実装する
        return true;
    }
}

Kubernetesで稼働させる場合は、生存確認と受け入れ準備を分ける liveness／readiness グループが自動で用意され、/actuator/health/liveness と /actuator/health/readiness をプローブに指定できます。

info：アプリ情報の公開とinfo.*が出ないときの対処

infoエンドポイントは、バージョンや説明などの任意情報を返します。ここで頻出のつまずきが「info.app.name を書いたのに空で返る」現象です。Spring Boot 2.6以降、info.* プロパティを読み取るenvコントリビュータは既定で無効になっており、management.info.env.enabled=true を明示しないと反映されません。

# 2.6 以降、info.* を出すにはこの設定が必須
management.info.env.enabled=true

info.app.name=order-service
info.app.version=1.4.0

ビルド情報やGitのコミットハッシュを出したい場合は、info.app.* を手書きするより build-info（Mavenの spring-boot-maven-plugin）やGit情報プラグインを使うと、リリースのたびに自動で最新化されます。

metrics：Micrometerによる計測とカスタムメトリクス

metricsエンドポイントは、Micrometerが収集したJVMメモリ・スレッド数・GC・HTTPリクエスト数などを返します。/actuator/metrics で一覧、/actuator/metrics/jvm.memory.used のように名前を付けて個別値を取得します。業務イベントを数えたいときは MeterRegistry からカウンターやタイマーを作ります。

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.stereotype.Component;

@Component
public class OrderMetrics {

    private final Counter orderCounter;

    public OrderMetrics(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.created")
                .description("作成された注文の件数")
                .register(registry);
    }

    public void recordOrder() {
        orderCounter.increment();
    }
}

Prometheusへ送る場合は micrometer-registry-prometheus を依存に追加し、management.endpoints.web.exposure.include に prometheus を含めると /actuator/prometheus がスクレイプ用に開きます。監視基盤との接続はこのエンドポイントが起点になります。

loggers：実行時のログレベル変更

loggersエンドポイントは、再起動せずにログレベルを変更できます。障害調査中に特定パッケージだけDEBUGへ上げ、終わったら戻す、といった運用に有効です。変更はGETではなくPOSTで、対象ロガー名をパスに、新しいレベルをボディに指定します。

# com.example のログレベルを実行時に DEBUG へ変更する
curl -X POST http://localhost:8080/actuator/loggers/com.example \
     -H "Content-Type: application/json" \
     -d '{"configuredLevel": "DEBUG"}'

元に戻すには {"configuredLevel": null} をPOSTすると、設定ファイルで定義した既定レベルに復帰します。

env・beans・mappings：構成を把握する診断系

設定値や依存関係を追いたいときは、次の3つで起動後の実状態を確認します。いずれも機密を含みうるため公開には注意します。

envは環境変数やDBパスワード等を平文で含む場合があるため、外部からアクセスできる環境では必ず認証下に置きます。

httpexchanges：直近HTTP送受信の追跡（旧httptrace）

Spring Boot 2系の httptrace は、3.0で httpexchanges に改称されました（Micrometer Tracingとの混同を避けるため）。さらに、記録用の HttpExchangeRepository Beanを自分で定義しないとエンドポイントが有効になりません（既定では用意されません）。

import org.springframework.boot.actuate.web.exchanges.InMemoryHttpExchangeRepository;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class HttpExchangesConfig {

    @Bean
    public InMemoryHttpExchangeRepository httpExchangeRepository() {
        return new InMemoryHttpExchangeRepository();
    }
}

あわせて management.endpoints.web.exposure.include に httpexchanges を加えれば、/actuator/httpexchanges で直近のリクエスト・レスポンスのメソッドやステータスを確認できます。メモリ保持のため件数は限られる点に注意します。

Actuatorエンドポイントのセキュリティ保護

env・beans・configpropsは設定値やインフラ構成を露出し、heapdumpはメモリ内容ごと持ち出せます。本番でこれらを無認証公開するのは危険です。Spring Securityがクラスパスにあり独自の SecurityFilterChain が無い場合、Actuatorはhealth以外が自動的に保護されますが、要件に合わせるなら明示的に定義します。

Spring Boot 3以降はSpring Security 6が前提で、旧来の WebSecurityConfigurerAdapter は使えません。SecurityFilterChain をBeanとして返す形式に統一されています。EndpointRequest を使うと、Actuatorのパスが変わってもマッチングが追随します。

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
    public SecurityFilterChain actuatorSecurity(HttpSecurity http) throws Exception {
        http
            .securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(EndpointRequest.to("health")).permitAll()
                .anyRequest().hasRole("ADMIN"))
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

この設定は、healthだけ無認証で開放し、他のActuatorエンドポイントはADMINロールのBasic認証必須にします。healthを permitAll() しても、内訳を出すかどうかは前述の show-details が別に制御するため、無認証公開でも詳細は伏せられます。監視ツールにはhealthを、運用者には認証付きの他エンドポイントを、という分離が作れます。SecurityFilterChain の仕組みはSecurityFilterChainの解説記事、Spring Security全体の構成はSpring Securityの基本ガイドで詳しく説明しています。加えて、公開範囲そのものを絞る（exposure.include を必要最小限にする）、Actuatorを内部ネットワークからのみ到達可能にする、といったネットワーク面の対策も併用します。

独自Actuatorエンドポイントの作成

標準エンドポイントで足りない情報は、@Endpoint を付けたBeanで独自エンドポイントを追加できます。参照用の操作は @ReadOperation、更新用は @WriteOperation で定義します。たとえば機能フラグの状態を返すエンドポイントは次のように書きます。

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
@Endpoint(id = "features")
public class FeatureEndpoint {

    @ReadOperation
    public Map<String, Boolean> features() {
        return Map.of("newCheckout", true, "betaSearch", false);
    }
}

IDを features にしたので、management.endpoints.web.exposure.include に features を加えると /actuator/features で参照できます。運用ダッシュボードに独自の状態を載せたいときに有効です。

Spring Boot 3・4で変わったActuatorの注意点

ネット上のActuator解説はSpring Boot 2系のまま書かれたものが多く、そのまま写すと動きません。移行時に効く変更点を整理します。

とくに management.security.enabled=false で保護を切る古い手順は、Spring Boot 2.0以降まったく効きません。セキュリティは前掲の SecurityFilterChain で制御します。Spring Boot 4はベースラインがJava 17で、Java 25（LTS）まで対応し、コードベースのモジュール化が進んだ世代です。バージョンごとの変更点はSpring Boot 4の変更点まとめ、サポート期限を踏まえた版選びはSpring Bootのバージョンとサポート期限の解説を参照してください（各版の最新パッチは公式リリースノートで確認）。

よくある質問

Actuatorのエンドポイントにアクセスできないのはなぜですか？

HTTPで初期公開されるのは health のみだからです。metricsやenvなどを見るには management.endpoints.web.exposure.include に対象IDを列挙します。設定後もパスは /actuator/<id> です。

management.security.enabled を書いても効かないのはなぜですか？

このプロパティはSpring Boot 2.0で廃止され、以降は無視されます。認証やアクセス制御は SecurityFilterChain Beanと EndpointRequest で定義します。

httptraceエンドポイントが見つからないのはなぜですか？

Spring Boot 3.0で httpexchanges に改称されました。加えて InMemoryHttpExchangeRepository などの HttpExchangeRepository Beanを定義しないと有効になりません。

infoエンドポイントにinfo.*の値が出ないのはなぜですか？

Spring Boot 2.6以降、info.* を読むenvコントリビュータが既定で無効なためです。management.info.env.enabled=true を追加すると反映されます。

本番で公開してよいエンドポイントはどれですか？

基本はhealthのみを公開し、それも show-details=when-authorized で内訳を伏せます。env・beans・heapdumpなどは認証必須にするか、外部から到達できないネットワークに限定します。

関連記事

• SecurityFilterChainとは何かをわかりやすく解説
• Spring Securityの仕組みを整理して理解する基本ガイド
• Spring Boot 4の変更点まとめ
• いま選ぶべきSpring Bootのバージョンとサポート期限
• Spring Bootの主要なアノテーション一覧