Spring Boot には、アプリケーションを本番環境にプッシュするときにアプリケーションを監視および管理するのに役立つ多くの追加機能が含まれています。HTTP エンドポイントまたは JMX を使用して、アプリケーションを管理および監視することを選択できます。監査、ヘルス、メトリクスの収集もアプリケーションに自動的に適用できます。

1. 本番対応機能を有効にする

spring-boot-actuator [GitHub] (英語) モジュールは、Spring Boot のすべての本番環境対応機能を提供します。機能を有効にするための推奨される方法は、spring-boot-starter-actuator の「スターター」への依存関係を追加することです。

アクチュエーターの定義

アクチュエーターは、何かを動かしたり制御したりするための機械装置を指す製造用語です。アクチュエーターは、小さな変化から大量のモーションを生成できます。

Maven ベースのプロジェクトにアクチュエーターを追加するには、次の「スターター」依存関係を追加します。

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

Gradle の場合、次の宣言を使用します。

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

2. エンドポイント

アクチュエーターエンドポイントを使用すると、アプリケーションを監視および操作できます。Spring Boot には多数のエンドポイントが組み込まれており、独自のエンドポイントを追加できます。例: health エンドポイントは、基本的なアプリケーション正常性情報を提供します。

個々のエンドポイントは HTTP または JMX 経由で公開（リモートアクセス可能）で有効または無効にできます。エンドポイントが有効で公開されている場合、エンドポイントは使用可能であると見なされます。組み込みのエンドポイントは、使用可能な場合にのみ自動構成されます。ほとんどのアプリケーションは HTTP を介して公開を選択します。エンドポイントの ID と /actuator のプレフィックスが URL にマップされます。例: デフォルトでは、health エンドポイントは /actuator/health にマップされます。

アクチュエーターのエンドポイントとそのリクエストとレスポンスの形式の詳細については、個別の API ドキュメント（HTML または PDF (英語) ）を参照してください。

次のテクノロジーに依存しないエンドポイントが利用可能です。

ID 説明

auditevents

現在のアプリケーションの監査イベント情報を公開します。AuditEventRepository Bean が必要です。

beans

アプリケーション内のすべての Spring Bean の完全なリストを表示します。

caches

利用可能なキャッシュを公開します。

conditions

構成クラスおよび自動構成クラスで評価された条件と、それらが一致したまたは一致しなかった理由を示します。

configprops

すべての @ConfigurationProperties の照合リストを表示します。

env

Spring の ConfigurableEnvironment からプロパティを公開します。

flyway

適用された Flyway データベースの移行を表示します。1 つ以上の Flyway Bean が必要です。

health

アプリケーションの正常性情報を表示します。

httptrace

HTTP トレース情報（デフォルトでは、最後の 100 の HTTP リクエスト / レスポンス交換）を表示します。HttpTraceRepository Bean が必要です。

info

任意のアプリケーション情報を表示します。

integrationgraph

Spring Integration グラフを表示します。spring-integration-core への依存が必要です。

loggers

アプリケーションのロガーの構成を表示および変更します。

liquibase

適用された Liquibase データベースの移行を表示します。1 つ以上の Liquibase Bean が必要です。

metrics

現在のアプリケーションの「メトリクス」情報を表示します。

mappings

すべての @RequestMapping パスの照合リストを表示します。

scheduledtasks

アプリケーションのスケジュールされたタスクを表示します。

sessions

Spring Session-backed セッションストアからのユーザーセッションの取得と削除を許可します。Spring Session を使用したサーブレットベースの Web アプリケーションが必要です。

shutdown

アプリケーションを正常にシャットダウンします。デフォルトでは無効になっています。

threaddump

スレッドダンプを実行します。

アプリケーションが Web アプリケーション (Spring MVC、Spring WebFlux、または Jersey) の場合、次の追加のエンドポイントを使用できます。

ID 説明

heapdump

hprof ヒープダンプファイルを返します。HotSpot JVM が必要です。

jolokia

HTTP 経由で JMX Bean を公開します（Jolokia がクラスパス上にある場合、WebFlux では使用できません）。jolokia-core への依存が必要です。

logfile

ログファイルの内容を返します（logging.file.name または logging.file.path プロパティが設定されている場合）。HTTP Range ヘッダーの使用をサポートして、ログファイルのコンテンツの一部を取得します。

prometheus

Prometheus サーバーによってスクレイピング可能な形式でメトリクスを公開します。micrometer-registry-prometheus への依存が必要です。

2.1. エンドポイントを有効にする

デフォルトでは、shutdown を除くすべてのエンドポイントが有効になっています。エンドポイントの有効化を構成するには、management.endpoint.<id>.enabled プロパティを使用します。次の例では、shutdown エンドポイントを有効にします。

management.endpoint.shutdown.enabled=true

エンドポイントの有効化をオプトアウトではなくオプトインにしたい場合は、management.endpoints.enabled-by-default プロパティを false に設定し、個々のエンドポイント enabled プロパティを使用してオプトインします。次の例では、info エンドポイントを有効にし、他のすべてのエンドポイントを無効にします。

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
無効なエンドポイントは、アプリケーションコンテキストから完全に削除されます。エンドポイントが公開されているテクノロジーのみを変更する場合は、代わりに include および exclude プロパティを使用してください。

2.2. エンドポイントの公開

エンドポイントには機密情報が含まれている場合があるため、エンドポイントを公開するタイミングについて慎重に検討する必要があります。次の表は、組み込みのエンドポイントのデフォルトの露出を示しています。

IDJMXWeb

auditevents

はい

いいえ

beans

はい

いいえ

caches

はい

いいえ

conditions

はい

いいえ

configprops

はい

いいえ

env

はい

いいえ

flyway

はい

いいえ

health

はい

はい

heapdump

なし

いいえ

httptrace

はい

いいえ

info

はい

はい

integrationgraph

はい

いいえ

jolokia

なし

いいえ

logfile

なし

いいえ

loggers

はい

いいえ

liquibase

はい

いいえ

metrics

はい

いいえ

mappings

はい

いいえ

prometheus

なし

いいえ

scheduledtasks

はい

いいえ

sessions

はい

いいえ

shutdown

はい

いいえ

threaddump

はい

いいえ

公開するエンドポイントを変更するには、次のテクノロジー固有の include および exclude プロパティを使用します。

プロパティ デフォルト

management.endpoints.jmx.exposure.exclude

management.endpoints.jmx.exposure.include

*

management.endpoints.web.exposure.exclude

management.endpoints.web.exposure.include

info, health

include プロパティは、公開されているエンドポイントの ID をリストします。exclude プロパティは、公開されるべきではないエンドポイントの ID をリストします。exclude プロパティは、include プロパティよりも優先されます。include プロパティと exclude プロパティの両方に、エンドポイント ID のリストを設定できます。

例: JMX を介したすべてのエンドポイントの公開を停止し、health および info エンドポイントのみを公開するには、次のプロパティを使用します。

management.endpoints.jmx.exposure.include=health,info

* を使用して、すべてのエンドポイントを選択できます。例: env および beans エンドポイント以外のすべてを HTTP で公開するには、次のプロパティを使用します。

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

* は YAML で特別な意味を持つため、次の例に示すように、すべてのエンドポイントを含める（または除外する）場合は必ず引用符を追加してください。

management:
  endpoints:
    web:
      exposure:
        include: "*"
アプリケーションが公開されている場合は、エンドポイントも保護することを強くお勧めします。
エンドポイントが公開されるタイミングについて独自の戦略を実装する場合は、EndpointFilter Bean を登録できます。

2.3. HTTP エンドポイントの保護

他の機密 URL と同じ方法で、HTTP エンドポイントの保護に注意する必要があります。Spring Security が存在する場合、エンドポイントは Spring Security のコンテンツネゴシエーション戦略を使用してデフォルトで保護されます。HTTP エンドポイントにカスタムセキュリティを設定する場合、たとえば特定のロールを持つユーザーのみにアクセスを許可する場合、Spring Boot は Spring Security と組み合わせて使用できる便利な RequestMatcher オブジェクトを提供します。

典型的な Spring Security 構成は、次の例のようになります。

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests((requests) ->
                requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic();
    }

}

上記の例では、EndpointRequest.toAnyEndpoint() を使用してリクエストを任意のエンドポイントに一致させ、すべてが ENDPOINT_ADMIN のロールを持つようにします。EndpointRequest では、他のいくつかのマッチャーメソッドも利用できます。詳細については、API ドキュメント（HTML または PDF (英語) ）を参照してください。

ファイアウォールの背後にアプリケーションをデプロイする場合、認証を必要とせずにすべてのアクチュエーターエンドポイントにアクセスできるようにすることができます。これを行うには、次のように management.endpoints.web.exposure.include プロパティを変更します。

application.properties
management.endpoints.web.exposure.include=*

さらに、Spring Security が存在する場合、次の例に示すように、エンドポイントへの認証されていないアクセスを許可するカスタムセキュリティ構成を追加する必要があります。

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests((requests) ->
            requests.anyRequest().permitAll());
    }

}

2.4. エンドポイントの構成

エンドポイントは、パラメーターを取らない読み取り操作に対するレスポンスを自動的にキャッシュします。エンドポイントがレスポンスをキャッシュする時間を設定するには、cache.time-to-live プロパティを使用します。次の例では、beans エンドポイントのキャッシュの有効期間を 10 秒に設定します。

application.properties
management.endpoint.beans.cache.time-to-live=10s
プレフィックス management.endpoint.<name> は、構成されているエンドポイントを一意に識別するために使用されます。

2.5. アクチュエーター Web エンドポイント用のハイパーメディア

すべてのエンドポイントへのリンクを含む「検出ページ」が追加されます。「ディスカバリページ」は、デフォルトで /actuator で利用可能です。

カスタム管理コンテキストパスが設定されると、「ディスカバリページ」が /actuator から管理コンテキストのルートに自動的に移動します。例: 管理コンテキストパスが /management の場合、ディスカバリページは /management から利用できます。管理コンテキストパスが / に設定されている場合、検出ページは無効になり、他のマッピングとの衝突の可能性を防ぎます。

2.6. CORS サポート

クロスオリジンリソース共有 [Mozilla] (CORS) は、認可されるクロスドメインリクエストの種類を柔軟に指定できる W3C 仕様 (英語) です。Spring MVC または Spring WebFlux を使用する場合、アクチュエーターの Web エンドポイントは、そのようなシナリオをサポートするように構成できます。

CORS サポートはデフォルトで無効になっており、management.endpoints.web.cors.allowed-origins プロパティが設定されると有効になります。次の構成では、example.com ドメインからの GET および POST 呼び出しが許可されます。

management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
オプションの完全なリストについては、CorsEndpointProperties [GitHub] (英語) を参照してください。

2.7. カスタムエンドポイントの実装

@Endpoint でアノテーションが付けられた @Bean を追加すると、@ReadOperation、@WriteOperation、または @DeleteOperation でアノテーションが付けられたメソッドが JMX 上で自動的に公開され、Web アプリケーションでは HTTP 上でも公開されます。エンドポイントは、Jersey、Spring MVC、または Spring WebFlux を使用して HTTP 経由で公開できます。Jersey と Spring MVC の両方が使用可能な場合は、Spring MVC が使用されます。

次の例では、カスタムオブジェクトを返す読み取り操作を公開しています。

@ReadOperation
public CustomData getCustomData() {
    return new CustomData("test", 5);
}

@JmxEndpoint または @WebEndpoint を使用して、テクノロジー固有のエンドポイントを作成することもできます。これらのエンドポイントは、それぞれのテクノロジーに制限されています。例: @WebEndpoint は HTTP でのみ公開され、JMX では公開されません。

@EndpointWebExtension および @EndpointJmxExtension を使用して、テクノロジー固有の拡張機能を作成できます。これらのアノテーションにより、既存のエンドポイントを強化するためのテクノロジー固有の操作を提供できます。

最後に、Web フレームワーク固有の機能へのアクセスが必要な場合は、サーブレットまたは Spring @Controller および @RestController エンドポイントを実装できますが、それらのエンドポイントは JMX 経由では利用できないか、別の Web フレームワークを使用します。

2.7.1. 入力を受け取る

エンドポイントでの操作は、パラメーターを介して入力を受け取ります。Web 経由で公開される場合、これらのパラメーターの値は、URL のクエリパラメーターと JSON リクエスト本文から取得されます。JMX を介して公開されると、パラメーターは MBean の操作のパラメーターにマップされます。デフォルトではパラメーターが必要です。これらは、@javax.annotation.Nullable または @org.springframework.lang.Nullable のいずれかでアノテーションを付けることによってオプションにすることができます。

JSON リクエスト本文の各ルートプロパティは、エンドポイントのパラメーターにマップできます。次の JSON リクエスト本文を検討してください。

{
    "name": "test",
    "counter": 42
}

次の例に示すように、これを使用して、String name および int counter パラメーターを受け取る書き込み操作を呼び出すことができます。

@WriteOperation
public void updateCustomData(String name, int counter) {
    // injects "test" and 42
}
エンドポイントはテクノロジーにとらわれないため、メソッドシグネチャーで指定できるのは単純な型のみです。特に、name および counter プロパティを定義する CustomData 型の単一パラメーターの宣言はサポートされていません。
入力を操作メソッドのパラメーターにマップするには、エンドポイントを実装する Java コードを -parameters でコンパイルし、エンドポイントを実装する Kotlin コードを -java-parameters でコンパイルする必要があります。Spring Boot の Gradle プラグインを使用している場合、または Maven と spring-boot-starter-parent を使用している場合、これは自動的に行われます。
入力型の変換

エンドポイント操作メソッドに渡されるパラメーターは、必要に応じて、必要な型に自動的に変換されます。操作メソッドを呼び出す前に、JMX または HTTP リクエストを介して受信した入力は、ApplicationConversionService のインスタンスと、@EndpointConverter で修飾された Converter または GenericConverter Bean を使用して、必要な型に変換されます。

2.7.2. カスタム Web エンドポイント

@Endpoint、@WebEndpoint、または @EndpointWebExtension の操作は、Jersey、Spring MVC、または Spring WebFlux を使用して HTTP 経由で自動的に公開されます。Jersey と Spring MVC の両方が使用可能な場合は、Spring MVC が使用されます。

Web エンドポイントリクエスト述語

リクエストの述語は、Web に公開されたエンドポイントでの各操作に対して自動的に生成されます。

パス

述語のパスは、エンドポイントの ID と Web に公開されたエンドポイントのベースパスによって決定されます。デフォルトのベースパスは /actuator です。例: ID sessions のエンドポイントは、述語のパスとして /actuator/sessions を使用します。

@Selector を使用して操作メソッドの 1 つ以上のパラメーターにアノテーションを付けることにより、パスをさらにカスタマイズできます。そのようなパラメーターは、パス変数としてパス述語に追加されます。エンドポイント操作が呼び出されると、変数の値が操作メソッドに渡されます。残りのすべてのパス要素をキャプチャーする場合は、@Selector(Match=ALL_REMAINING) を最後のパラメーターに追加し、String[] と互換性のある変換型にすることができます。

HTTP メソッド

次の表に示すように、述語の HTTP メソッドは操作型によって決定されます。

操作 HTTP メソッド

@ReadOperation

GET

@WriteOperation

POST

@DeleteOperation

DELETE

消費する

リクエスト本体を使用する @WriteOperation （HTTP POST）の場合、述語の消費節は application/vnd.spring-boot.actuator.v2+json, application/json です。他のすべての操作では、consumes 句は空です。

生産する

述語の produces 節は、@DeleteOperation、@ReadOperation、@WriteOperation アノテーションの produces 属性によって判別できます。この属性はオプションです。使用しない場合、produces 句は自動的に決定されます。

操作メソッドが void または Void を返す場合、produces 句は空です。操作メソッドが org.springframework.core.io.Resource を返す場合、produces 句は application/octet-stream です。他のすべての操作の場合、produces 句は application/vnd.spring-boot.actuator.v2+json, application/json です。

Web エンドポイントレスポンスステータス

エンドポイント操作のデフォルトのレスポンスステータスは、操作の種類（読み取り、書き込み、削除）と、操作が返すもの（ある場合）によって異なります。

@ReadOperation は値を返し、レスポンスステータスは 200（OK）になります。値を返さない場合、レスポンスステータスは 404（見つかりません）になります。

@WriteOperation または @DeleteOperation が値を返す場合、レスポンスステータスは 200（OK）になります。値を返さない場合、レスポンスステータスは 204（コンテンツなし）になります。

必要なパラメーターなしで、または必要な型に変換できないパラメーターで操作が呼び出された場合、操作メソッドは呼び出されず、レスポンスステータスは 400（不良リクエスト）になります。

Web エンドポイント範囲リクエスト

HTTP 範囲リクエストを使用して、HTTP リソースの一部をリクエストできます。Spring MVC または Spring、Web、Flux を使用する場合、org.springframework.core.io.Resource を返す操作は自動的に範囲リクエストをサポートします。

Jersey を使用する場合、範囲リクエストはサポートされていません。
Web エンドポイントセキュリティ

Web エンドポイントまたは Web 固有のエンドポイント拡張での操作は、メソッドパラメーターとして現在の java.security.Principal または org.springframework.boot.actuate.endpoint.SecurityContext を受け取ることができます。前者は通常、@Nullable と組み合わせて使用され、認証済みユーザーと未認証ユーザーに異なる動作を提供します。後者は通常、isUserInRole(String) メソッドを使用して認可チェックを実行するために使用されます。

2.7.3. サーブレットのエンドポイント

Supplier<EndpointServlet> も実装する @ServletEndpoint アノテーションが付けられたクラスを実装することにより、Servlet をエンドポイントとして公開できます。サーブレットエンドポイントは、サーブレットコンテナーとのより深い統合を提供しますが、移植性を犠牲にします。これらは、既存の Servlet をエンドポイントとして公開するために使用することを目的としています。新しいエンドポイントの場合、可能な限り @Endpoint および @WebEndpoint アノテーションを優先する必要があります。

2.7.4. コントローラーのエンドポイント

@ControllerEndpoint および @RestControllerEndpoint を使用して、Spring MVC または Spring WebFlux によってのみ公開されるエンドポイントを実装できます。メソッドは、Spring MVC および Spring WebFlux の標準アノテーション ( @RequestMapping および @GetMapping など) を使用してマップされ、エンドポイントの ID がパスのプレフィックスとして使用されます。コントローラーエンドポイントは、Spring の Web フレームワークとのより深い統合を提供しますが、移植性が犠牲になります。可能な限り、@Endpoint および @WebEndpoint アノテーションを優先する必要があります。

2.8. ヘルス情報

ヘルス情報を使用して、実行中のアプリケーションのステータスを確認できます。多くの場合、本番システムがダウンしたときに誰かを警告するために、監視ソフトウェアによって使用されます。health エンドポイントによって公開される情報は、management.endpoint.health.show-details および management.endpoint.health.show-components プロパティに依存します。これらのプロパティは、次のいずれかの値で構成できます。

名前 説明

never

詳細は表示されません。

when-authorized

詳細は承認されたユーザーにのみ表示されます。management.endpoint.health.roles を使用して、認可されたロールを構成できます。

always

詳細はすべてのユーザーに表示されます。

デフォルト値は never です。ユーザーは、エンドポイントの 1 つ以上のロールにいるときに承認されていると見なされます。エンドポイントにロールが構成されていない場合（デフォルト）、認証されたすべてのユーザーが承認されたと見なされます。ロールは、management.endpoint.health.roles プロパティを使用して構成できます。

アプリケーションを保護し、always を使用する場合は、セキュリティ構成で、認証済みユーザーと非認証ユーザーの両方のヘルスエンドポイントへのアクセスを許可する必要があります。

ヘルス情報は、HealthContributorRegistry [GitHub] (英語) のコンテンツ（デフォルトでは、ApplicationContext で定義されているすべての HealthContributor [GitHub] (英語) インスタンス）から収集されます。Spring Boot には多数の自動構成 HealthContributors が含まれており、独自に作成することもできます。

HealthContributor は、HealthIndicator または CompositeHealthContributor のいずれかです。HealthIndicator は、Status を含む実際のヘルス情報を提供します。CompositeHealthContributor は、他の HealthContributors の複合を提供します。総合すると、コントリビューターはツリー構造を形成して、システム全体の健全性を表します。

デフォルトでは、最終的なシステムヘルスは、StatusAggregator によって導き出されます。StatusAggregator は、ステータスの順序付きリストに基づいて、各 HealthIndicator からステータスをソートします。ソートされたリストの最初のステータスは、全体的なヘルスステータスとして使用されます。HealthIndicator が StatusAggregator が認識しているステータスを返さない場合、UNKNOWN ステータスが使用されます。

HealthContributorRegistry を使用して、実行時にヘルスインジケータを登録および登録解除できます。

2.8.1. 自動構成された HealthIndicators

以下の HealthIndicators は、必要に応じて Spring Boot によって自動構成されます。management.health.key.enabled を構成して、選択したインジケーターを有効 / 無効にすることもできます。key は以下の表にリストされています。

キー 名前 説明

cassandra

CassandraHealthIndicator [GitHub] (英語)

Cassandra データベースが稼働していることを確認します。

couchbase

CouchbaseHealthIndicator [GitHub] (英語)

Couchbase クラスターが稼働していることを確認します。

db

DataSourceHealthIndicator [GitHub] (英語)

DataSource への接続が取得できることを確認します。

diskspace

DiskSpaceHealthIndicator [GitHub] (英語)

ディスク容量が不足していないか確認します。

elasticsearch

ElasticsearchRestHealthIndicator [GitHub] (英語)

Elasticsearch クラスターが起動していることを確認します。

hazelcast

HazelcastHealthIndicator [GitHub] (英語)

Hazelcast サーバーが稼働していることを確認します。

influxdb

InfluxDbHealthIndicator [GitHub] (英語)

InfluxDB サーバーが起動していることを確認します。

jms

JmsHealthIndicator [GitHub] (英語)

JMS ブローカーが起動していることを確認します。

ldap

LdapHealthIndicator [GitHub] (英語)

LDAP サーバーが起動していることを確認します。

mail

MailHealthIndicator [GitHub] (英語)

メールサーバーが起動していることを確認します。

mongo

MongoHealthIndicator [GitHub] (英語)

Mongo データベースが稼働していることを確認します。

neo4j

Neo4jHealthIndicator [GitHub] (英語)

Neo4j データベースが稼働していることを確認します。

ping

PingHealthIndicator [GitHub] (英語)

常に UP で応答します。

rabbit

RabbitHealthIndicator [GitHub] (英語)

Rabbit サーバーが稼働していることを確認します。

redis

RedisHealthIndicator [GitHub] (英語)

Redis サーバーが稼働していることを確認します。

solr

SolrHealthIndicator [GitHub] (英語)

Solr サーバーが稼働していることを確認します。

management.health.defaults.enabled プロパティを設定することにより、すべて無効にできます。

追加の HealthIndicators が利用可能ですが、デフォルトでは有効になっていません。

キー 名前 説明

livenessstate

LivenessStateHealthIndicator [GitHub] (英語)

「活性」アプリケーションの可用性の状態を公開します。

readinessstate

ReadinessStateHealthIndicator [GitHub] (英語)

「準備」アプリケーションの可用性の状態を公開します。

2.8.2. カスタム HealthIndicators の作成

カスタムのヘルス情報を提供するために、HealthIndicator [GitHub] (英語) インターフェースを実装する Spring Bean を登録できます。health() メソッドの実装を提供し、Health レスポンスを返す必要があります。Health レスポンスにはステータスが含まれている必要があり、オプションで表示される追加の詳細を含めることができます。次のコードは、サンプルの HealthIndicator 実装を示しています。

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

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check(); // perform some specific health check
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

}
特定の HealthIndicator の識別子は、HealthIndicator 接尾辞が存在しない場合は、HealthIndicator の名前を除いた Bean の名前です。上記の例では、ヘルス情報は my という名前のエントリで利用可能です。

Spring Boot の事前定義された Status [GitHub] (英語) 型に加えて、Health は新しいシステム状態を表すカスタム Status を返すこともできます。そのような場合、StatusAggregator [GitHub] (英語) インターフェースのカスタム実装も提供する必要があります。または、management.endpoint.health.status.order 構成プロパティを使用してデフォルトの実装を構成する必要があります。

例: HealthIndicator 実装の 1 つで、コード FATAL の新しい Status が使用されていると仮定します。重大度の順序を構成するには、次のプロパティをアプリケーションプロパティに追加します。

management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up

レスポンスの HTTP ステータスコードは、全体的なヘルスステータスを反映しています。デフォルトでは、OUT_OF_SERVICE および DOWN は 503 にマップされます。UP を含む、マップされていないヘルスステータスはすべて 200 にマップされます。HTTP 経由でヘルスエンドポイントにアクセスする場合は、カスタムステータスマッピングを登録することもできます。カスタムマッピングを構成すると、DOWN および OUT_OF_SERVICE のデフォルトマッピングが無効になります。デフォルトのマッピングを保持する場合は、カスタムマッピングとともに明示的に構成する必要があります。例: 次のプロパティは、FATAL を 503（サービスは利用不可）にマップし、DOWN および OUT_OF_SERVICE のデフォルトのマッピングを保持します。

management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503
さらに制御が必要な場合は、独自の HttpCodeStatusMapper Bean を定義できます。

次の表に、組み込みステータスのデフォルトのステータスマッピングを示します。

ステータス マッピング

DOWN

SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

SERVICE_UNAVAILABLE (503)

UP

デフォルトではマッピングがないため、http ステータスは 200 です

UNKNOWN

デフォルトではマッピングがないため、http ステータスは 200 です

2.8.3. リアクティブヘルスインジケータ

Spring WebFlux を使用するようなリアクティブアプリケーションの場合、ReactiveHealthContributor はアプリケーションの状態を取得するためのノンブロッキング契約を提供します。従来の HealthContributor と同様に、ヘルス情報は ReactiveHealthContributorRegistry [GitHub] (英語) のコンテンツから収集されます（デフォルトでは、ApplicationContext で定義されているすべての HealthContributor [GitHub] (英語) および ReactiveHealthContributor [GitHub] (英語) インスタンス）。リアクティブ API をチェックしない通常の HealthContributors は、エラスティックスケジューラで実行されます。

リアクティブアプリケーションでは、ReactiveHealthContributorRegistry を使用して、実行時にヘルスインジケータを登録および登録解除する必要があります。通常の HealthContributor を登録する必要がある場合は、ReactiveHealthContributor#adapt を使用してラップする必要があります。

リアクティブ API からカスタムヘルス情報を提供するために、ReactiveHealthIndicator [GitHub] (英語) インターフェースを実装する Spring Bean を登録できます。次のコードは、サンプルの ReactiveHealthIndicator 実装を示しています。

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return doHealthCheck() //perform some specific health check that returns a Mono<Health>
            .onErrorResume(ex -> Mono.just(new Health.Builder().down(ex).build()));
    }

}
エラーを自動的に処理するには、AbstractReactiveHealthIndicator から拡張することを検討してください。

2.8.4. 自動構成された ReactiveHealthIndicators

以下の ReactiveHealthIndicators は、必要に応じて Spring Boot によって自動構成されます。

キー 名前 説明

cassandra

CassandraReactiveHealthIndicator [GitHub] (英語)

Cassandra データベースが稼働していることを確認します。

couchbase

CouchbaseReactiveHealthIndicator [GitHub] (英語)

Couchbase クラスターが稼働していることを確認します。

elasticsearch

ElasticsearchReactiveHealthIndicator [GitHub] (英語)

Elasticsearch クラスターが起動していることを確認します。

mongo

MongoReactiveHealthIndicator [GitHub] (英語)

Mongo データベースが稼働していることを確認します。

redis

RedisReactiveHealthIndicator [GitHub] (英語)

Redis サーバーが稼働していることを確認します。

必要に応じて、リアクティブインジケータが通常のインジケータを置き換えます。また、明示的に処理されない HealthIndicator は自動的にラップされます。

2.8.5. ヘルスグループ

ヘルスインジケーターをさまざまな目的に使用できるグループに編成すると便利な場合があります。

ヘルスインジケータグループを作成するには、management.endpoint.health.group.<name> プロパティを使用し、ヘルスインジケータ ID のリストを include または exclude に指定できます。例: データベースインジケーターのみを含むグループを作成するには、以下を定義できます。

management.endpoint.health.group.custom.include=db

localhost:8080/actuator/health/custom を押すと、結果を確認できます。

デフォルトでは、グループはシステムヘルスと同じ StatusAggregator および HttpCodeStatusMapper 設定を継承しますが、これらはグループごとに定義することもできます。必要に応じて、show-details および roles プロパティをオーバーライドすることもできます。

management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
management.endpoint.health.group.custom.status.order=fatal,up
management.endpoint.health.group.custom.status.http-mapping.fatal=500
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500
グループで使用するカスタム StatusAggregator または HttpCodeStatusMapper Bean を登録する必要がある場合は、@Qualifier("groupname") を使用できます。

2.9. Kubernetes プローブ

Kubernetes にデプロイされたアプリケーションは、コンテナープローブ (英語) を使用して内部状態に関する情報を提供できます。Kubernetes 構成 (英語) に応じて、kubelet はそれらのプローブを呼び出し、結果に反応します。

Spring Boot は、アプリケーションの可用性状態を標準で管理します。Kubernetes 環境にデプロイされた場合、アクチュエーターは ApplicationAvailability インターフェースから「活性」および「準備」情報を収集し、その情報を専用ヘルスインジケーター（LivenessStateHealthIndicator および ReadinessStateHealthIndicator）で使用します。これらのインジケーターは、グローバルヘルスエンドポイント（"/actuator/health"）に表示されます。また、ヘルスグループを使用する個別の HTTP プローブとして公開されます: "/actuator/health/liveness" および "/actuator/health/readiness"。

その後、次のエンドポイント情報を使用して Kubernetes インフラストラクチャを構成できます。

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...
<actuator-port> は、アクチュエーターのエンドポイントが利用可能なポートに設定する必要があります。メインの Web サーバーポートか、"management.server.port" プロパティが設定されている場合は別の管理ポートになります。

これらのヘルスグループは、アプリケーションが Kubernetes 環境で実行されている場合にのみ自動的に有効になります。management.endpoint.health.probes.enabled 構成プロパティを使用して、任意の環境で有効にできます。

構成された有効期間よりもアプリケーションの起動に時間がかかる場合、Kubernetes は可能な解決策として "startupProbe" についてメンションしています。すべての起動タスクが完了するまで "readinessProbe" が失敗するため、"startupProbe" は必ずしも必要ではありません。アプリケーションライフサイクル中のプローブの動作を参照してください。
アクチュエーターエンドポイントが別の管理コンテキストにデプロイされている場合は、エンドポイントがメインアプリケーションと同じ Web インフラストラクチャ（ポート、接続プール、フレームワークコンポーネント）を使用していないことに注意してください。この場合、メインアプリケーションが正しく機能しない場合（たとえば、新しい接続を受け入れることができない場合）でも、プローブチェックは成功する可能性があります。

2.9.1. Kubernetes プローブを使用した外部状態の確認

アクチュエーターは、「活性度」および「準備度」プローブをヘルスグループとして構成します。つまり、すべてのヘルスグループの機能が利用可能です。たとえば、追加のヘルスインジケーターを構成できます。

management.endpoint.health.group.readiness.include=readinessState,customCheck

デフォルトでは、Spring Boot はこれらのグループに他のヘルスインジケーターを追加しません。

「活性」プローブは、外部システムのヘルスチェックに依存するべきではありません。アプリケーションの活性状態が壊れている場合、Kubernetes はアプリケーションインスタンスを再起動することでその問題を解決しようとします。つまり、外部システムに障害が発生した場合（データベース、Web API、外部キャッシュなど）、Kubernetes はすべてのアプリケーションインスタンスを再起動し、連鎖的な障害を引き起こす可能性があります。

「準備」プローブについては、外部システムのチェックの選択はアプリケーション開発者が注意深く行う必要があります。つまり、Spring Boot は準備プローブに追加のヘルスチェックを含めません。アプリケーションインスタンスの準備状態の準備ができていない場合、Kubernetes はそのインスタンスにトラフィックをルーティングしません。一部の外部システムは、アプリケーションインスタンスによって共有されない場合があります。その場合、当然、準備プローブに含めることができます。他の外部システムはアプリケーションに不可欠ではない場合があります（アプリケーションにはサーキットブレーカーとフォールバックが含まれる可能性があります）。その場合、絶対に含まれるべきではありません。残念ながら、すべてのアプリケーションインスタンスで共有される外部システムは一般的であり、判断の呼び出しを行う必要があります。それを準備プローブに含め、外部サービスがダウンしたときにアプリケーションがサービスから除外されることを期待するか、そのままにしておきます。スタックの上位の障害を取り出して処理します。たとえば、呼び出し元でサーキットブレーカーを使用します。

アプリケーションのすべてのインスタンスの準備ができていない場合、type=ClusterIP または NodePort を使用する Kubernetes サービスは受信接続を受け入れません。接続がないため、HTTP エラーレスポンス（503 など）はありません。type=LoadBalancer を使用するサービスは、プロバイダーに応じて、接続を受け入れる場合と受け入れない場合があります。明示的な Ingress (英語) を持つサービスも、実装に応じた方法でレスポンスします。入力サービス自体が、ダウンストリームからの「接続拒否」を処理する方法を決定する必要があります。HTTP 503 は、ロードバランサーと Ingress の両方の場合によく発生します。

また、アプリケーションが Kubernetes 自動スケーリング (英語) を使用している場合、そのオートスケーラー構成によっては、ロードバランサーから取り出されるアプリケーションに対する反応が異なる場合があります。

2.9.2. アプリケーションのライフサイクルとプローブの状態

Kubernetes プローブのサポートの重要な側面は、アプリケーションライフサイクルとの一貫性です。Spring Boot は起動およびシャットダウン中のアプリケーションイベントを公開しています。

Spring Boot アプリケーションが起動すると、次のようになります。

アプリケーションの起動フェーズ 活性状態 準備状態 ノート

開始

BROKEN

REFUSING_TRAFFIC

Kubernetes は「活性」プローブをチェックし、時間がかかりすぎる場合はアプリケーションを再起動します。

起動済み

CORRECT

REFUSING_TRAFFIC

アプリケーションコンテキストがリフレッシュされます。アプリケーションは起動タスクを実行し、まだトラフィックを受信していません。

準備完了

CORRECT

ACCEPTING_TRAFFIC

起動タスクが完了しました。アプリケーションはトラフィックを受信しています。

Spring Boot アプリケーションがシャットダウンすると、次のようになります。

アプリケーションのシャットダウン段階 活性状態 準備状態 ノート

実行

ライブ

準備ができて

シャットダウンがリクエストされました。

正常なシャットダウン

ライブ

準備ができていない

有効にすると、正常なシャットダウンが処理中のリクエストを処理します。

シャットダウンが完了しました

壊れた

準備ができていない

アプリケーションコンテキストは閉じられており、アプリケーションはトラフィックを処理できません。

Kubernetes デプロイの詳細については、Kubernetes コンテナーのライフサイクルセクションを参照してください。

2.10. アプリケーション情報

アプリケーション情報は、ApplicationContext で定義されたすべての InfoContributor [GitHub] (英語) Bean から収集されたさまざまな情報を公開します。Spring Boot には多数の自動構成 InfoContributor Bean が含まれており、独自の Bean を作成できます。

2.10.1. 自動構成された InfoContributors

以下の InfoContributor Bean は、必要に応じて Spring Boot によって自動構成されます。

名前 説明

EnvironmentInfoContributor [GitHub] (英語)

info キーの Environment からキーを公開します。

GitInfoContributor [GitHub] (英語)

git.properties ファイルが利用可能な場合、git 情報を公開します。

BuildInfoContributor [GitHub] (英語)

META-INF/build-info.properties ファイルが利用可能な場合、ビルド情報を公開します。

management.info.defaults.enabled プロパティを設定することにより、すべて無効にすることができます。

2.10.2. カスタムアプリケーション情報

info.* Spring プロパティを設定することにより、info エンドポイントによって公開されるデータをカスタマイズできます。info キーのすべての Environment プロパティは自動的に公開されます。例: application.properties ファイルに次の設定を追加できます。

info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8

これらの値をハードコードするのではなく、ビルド時に情報プロパティを展開することもできます。

Maven を使用すると仮定すると、上記の例を次のように書き換えることができます。

[email protected] (英語)  @
[email protected] (英語)  @
[email protected] (英語)  @

2.10.3. Git コミット情報

info エンドポイントのもう 1 つの便利な機能は、プロジェクトがビルドされたときの git ソースコードリポジトリの状態に関する情報を公開する機能です。GitProperties Bean が使用可能な場合、info エンドポイントを使用してこれらのプロパティを公開できます。

git.properties ファイルがクラスパスのルートで利用可能な場合、GitProperties Bean は自動構成されます。詳細については、"Git 情報を生成する" を参照してください。

デフォルトでは、エンドポイントは git.branch、git.commit.id、git.commit.time プロパティ（存在する場合）を公開します。エンドポイントレスポンスでこれらのプロパティのいずれも必要としない場合は、git.properties ファイルから除外する必要があります。完全な git 情報（つまり、git.properties の完全なコンテンツ）を表示する場合は、次のように management.info.git.mode プロパティを使用します。

management.info.git.mode=full

info エンドポイントからの gitcommit 情報を完全に無効にするには、次のように management.info.git.enabled プロパティを false に設定します。

management.info.git.enabled=false

2.10.4. ビルド情報

BuildProperties Bean が使用可能な場合、info エンドポイントはビルドに関する情報も公開できます。これは、META-INF/build-info.properties ファイルがクラスパスで利用可能な場合に発生します。

Maven および Gradle プラグインは両方ともそのファイルを生成できます。詳細については、"ビルド情報を生成する" を参照してください。

2.10.5. カスタム InfoContributors の作成

カスタムアプリケーション情報を提供するために、InfoContributor [GitHub] (英語) インターフェースを実装する Spring Bean を登録できます。

次の例は、単一の値を持つ example エントリを提供します。

import java.util.Collections;

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

@Component
public class ExampleInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example",
                Collections.singletonMap("key", "value"));
    }

}

info エンドポイントに到達すると、次の追加エントリを含むレスポンスが表示されます。

{
    "example": {
        "key" : "value"
    }
}

3. HTTP を介した監視と管理

Web アプリケーションを開発している場合、Spring Boot Actuator はすべての有効なエンドポイントが HTTP 経由で公開されるように自動構成します。デフォルトの規則では、URL パスとして /actuator のプレフィックスを持つエンドポイントの id を使用します。例: health は /actuator/health として公開されます。

アクチュエーターは、Spring MVC、Spring、WebFlux、Jersey でネイティブにサポートされています。Jersey と Spring MVC の両方が使用可能な場合は、Spring MVC が使用されます。
Jackson は、API ドキュメント（HTML または PDF (英語) ）に記載されている正しい JSON レスポンスを取得するために必要な依存関係です。

3.1. 管理エンドポイントパスのカスタマイズ

管理エンドポイントのプレフィックスをカスタマイズすると便利な場合があります。例: アプリケーションは、別の目的で /actuator をすでに使用している場合があります。次の例に示すように、management.endpoints.web.base-path プロパティを使用して、管理エンドポイントのプレフィックスを変更できます。

management.endpoints.web.base-path=/manage

上記の application.properties の例は、エンドポイントを /actuator/{id} から /manage/{id} に変更します（たとえば、/manage/info）。

別の HTTP ポートを使用してエンドポイントを公開するように管理ポートが構成されていない限り、management.endpoints.web.base-path は server.servlet.context-path に相対的です。management.server.port が構成されている場合、management.endpoints.web.base-path は management.server.servlet.context-path に対して相対的です。

エンドポイントを別のパスにマップする場合は、management.endpoints.web.path-mapping プロパティを使用できます。

次の例では、/actuator/health を /healthcheck に再マッピングします。

application.properties
management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck

3.2. 管理サーバーポートのカスタマイズ

デフォルトの HTTP ポートを使用して管理エンドポイントを公開することは、クラウドベースのデプロイにとって実用的な選択です。ただし、アプリケーションが独自のデータセンター内で実行される場合は、別の HTTP ポートを使用してエンドポイントを公開することをお勧めします。

次の例に示すように、management.server.port プロパティを設定して HTTP ポートを変更できます。

management.server.port=8081
Cloud Foundry では、アプリケーションはデフォルトで HTTP と TCP の両方のルーティングに対してポート 8080 でのみリクエストを受信します。Cloud Foundry でカスタム管理ポートを使用する場合は、アプリケーションのルートを明示的に設定して、トラフィックをカスタムポートに転送する必要があります。

3.3. 管理固有の SSL の構成

カスタムポートを使用するように構成されている場合、さまざまな management.server.ssl.* プロパティを使用して、管理サーバーを独自の SSL で構成することもできます。例: これにより、次のプロパティ設定に示すように、メインアプリケーションが HTTPS を使用しているときに、管理サーバーを HTTP 経由で使用できるようになります。

server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:store.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=false

または、メインサーバーと管理サーバーの両方で SSL を使用できますが、次のようにキーストアが異なります。

server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:main.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=true
management.server.ssl.key-store=classpath:management.jks
management.server.ssl.key-password=secret

3.4. 管理サーバーのアドレスのカスタマイズ

management.server.address プロパティを設定することにより、管理エンドポイントが使用可能なアドレスをカスタマイズできます。これは、内部または ops に面したネットワークでのみリッスンする場合、または localhost からの接続のみをリッスンする場合に役立ちます。

ポートがメインサーバーのポートと異なる場合にのみ、別のアドレスでリッスンできます。

次の例 application.properties は、リモート管理接続を許可しません。

management.server.port=8081
management.server.address=127.0.0.1

3.5. HTTP エンドポイントを無効にする

HTTP 経由でエンドポイントを公開したくない場合は、次の例に示すように、管理ポートを -1 に設定できます。

management.server.port=-1

これは、次の例に示すように、management.endpoints.web.exposure.exclude プロパティを使用して実現することもできます。

management.endpoints.web.exposure.exclude=*

4. JMX を介した監視と管理

Java Management Extensions（JMX）は、アプリケーションを監視および管理するための標準メカニズムを提供します。デフォルトでは、この機能は有効になっておらず、構成プロパティ spring.jmx.enabled を true に設定することでオンにできます。Spring Boot は、デフォルトで管理エンドポイントを org.springframework.boot ドメインの JMX MBean として公開します。

4.1. MBean 名のカスタマイズ

通常、MBean の名前はエンドポイントの id から生成されます。例: health エンドポイントは org.springframework.boot:type=Endpoint,name=Health として公開されます。

アプリケーションに複数の Spring ApplicationContext が含まれている場合、名前が衝突することがあります。この問題を解決するには、spring.jmx.unique-names プロパティを true に設定して、MBean 名が常に一意になるようにします。

エンドポイントが公開される JMX ドメインをカスタマイズすることもできます。次の設定は、application.properties で実行する例を示しています。

spring.jmx.unique-names=true
management.endpoints.jmx.domain=com.example.myapp

4.2. JMX エンドポイントの無効化

JMX でエンドポイントを公開したくない場合は、次の例に示すように、management.endpoints.jmx.exposure.exclude プロパティを * に設定できます。

management.endpoints.jmx.exposure.exclude=*

4.3. HTTP を介した JMX での Jolokia の使用

Jolokia は、JMX Bean にアクセスする代替方法を提供する JMX-HTTP ブリッジです。Jolokia を使用するには、org.jolokia:jolokia-core への依存関係を含めます。例: Maven では、次の依存関係を追加します。

<dependency>
    <groupId>org.jolokia</groupId>
    <artifactId>jolokia-core</artifactId>
</dependency>

jolokia または * を management.endpoints.web.exposure.include プロパティに追加することにより、Jolokia エンドポイントを公開できます。その後、管理 HTTP サーバーで /actuator/jolokia を使用してアクセスできます。

Jolokia エンドポイントは、Jolokia のサーブレットをアクチュエーターエンドポイントとして公開します。その結果、これは Spring MVC や Jersey などのサーブレット環境に固有です。エンドポイントは WebFlux アプリケーションでは使用できません。

4.3.1. Jolokia のカスタマイズ

Jolokia には、サーブレットパラメーターを設定することで従来構成していた設定がいくつかあります。Spring Boot を使用すると、application.properties ファイルを使用できます。これを行うには、次の例に示すように、パラメーターの前に management.endpoint.jolokia.config. を付けます。

management.endpoint.jolokia.config.debug=true

4.3.2. Jolokia の無効化

Jolokia を使用しているが、Spring Boot で構成しない場合は、次のように management.endpoint.jolokia.enabled プロパティを false に設定します。

management.endpoint.jolokia.enabled=false

5. ロガー

Spring Boot Actuator には、実行時にアプリケーションのログレベルを表示および構成する機能が含まれています。リスト全体または個々のロガーの設定を表示できます。これは、明示的に設定されたログレベルと、ログフレームワークによって指定された有効なログレベルの両方で構成されます。これらのレベルは次のいずれかです。

  • TRACE

  • DEBUG

  • INFO

  • WARN

  • ERROR

  • FATAL

  • OFF

  • null

null は、明示的な構成がないことを示します。

5.1. ロガーを構成する

特定のロガーを構成するには、次の例に示すように、POST はリソースの URI の部分エンティティです。

{
    "configuredLevel": "DEBUG"
}
ロガーの特定のレベルを「リセット」する（代わりにデフォルトの構成を使用する）には、null の値を configuredLevel として渡すことができます。

6. メトリクス

Spring Boot Actuator は、以下を含む多数のモニタリングシステム (英語) をサポートするアプリケーションメトリクスファサードである Micrometer (英語) の依存関係管理と自動構成を提供します。

Micrometer の機能の詳細については、リファレンスドキュメント (英語) 、特に概念セクション (英語) を参照してください。

6.1. 入門

Spring Boot は、コンポジット MeterRegistry を自動構成し、クラスパスで検出されたサポートされている各実装のレジストリをコンポジットに追加します。Spring Boot がレジストリを設定するには、ランタイムクラスパスで micrometer-registry-{system} に依存していれば十分です。

ほとんどのレジストリは共通の機能を共有しています。たとえば、Micrometer レジストリ実装がクラスパスにある場合でも、特定のレジストリを無効にできます。例: Datadog を無効にするには:

management.metrics.export.datadog.enabled=false

Spring Boot は、次のことを明示的に指示しない限り、Metrics クラスのグローバルな静的複合レジストリに自動構成レジストリを追加します。

management.metrics.use-global-registry=false

メーターをレジストリに登録する前に、MeterRegistryCustomizer Bean をいくつでも登録して、共通タグの適用など、レジストリをさらに設定できます。

@Bean
MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {
    return registry -> registry.config().commonTags("region", "us-east-1");
}

ジェネリクス型をより具体的にすることにより、特定のレジストリ実装にカスタマイズを適用できます。

@Bean
MeterRegistryCustomizer<GraphiteMeterRegistry> graphiteMetricsNamingConvention() {
    return registry -> registry.config().namingConvention(MY_CUSTOM_CONVENTION);
}

Spring Boot は、構成または専用のアノテーションマーカーを介して制御できる組み込みの計測も構成します。

6.2. サポートされている監視システム

6.2.1. AppOptics

デフォルトでは、AppOptics レジストリは定期的にメトリクスを api.appoptics.com/v1/measurements (英語)  にプッシュします。メトリクスを SaaS AppOptics (英語) にエクスポートするには、API トークンを提供する必要があります。

management.metrics.export.appoptics.api-token=YOUR_TOKEN

6.2.2. Atlas

デフォルトでは、メトリクスはローカルマシンで実行されている Atlas (英語) にエクスポートされます。使用する Atlas サーバー [GitHub] (英語) の場所は、以下を使用して提供できます。

management.metrics.export.atlas.uri=https://atlas.example.com:7101/api/v1/publish

6.2.3. Datadog

Datadog レジストリは、メトリクスを datadoghq (英語) に定期的にプッシュします。メトリクスを Datadog (英語) にエクスポートするには、API キーを提供する必要があります。

management.metrics.export.datadog.api-key=YOUR_KEY

メトリクスが Datadog に送信される間隔を変更することもできます。

management.metrics.export.datadog.step=30s

6.2.4. Dynatrace

Dynatrace レジストリは、構成された URI にメトリクスを定期的にプッシュします。メトリクスを Dynatrace (英語) にエクスポートするには、API トークン、デバイス ID、URI を提供する必要があります。

management.metrics.export.dynatrace.api-token=YOUR_TOKEN
management.metrics.export.dynatrace.device-id=YOUR_DEVICE_ID
management.metrics.export.dynatrace.uri=YOUR_URI

メトリクスが Dynatrace に送信される間隔を変更することもできます。

management.metrics.export.dynatrace.step=30s

6.2.5. Elastic

デフォルトでは、メトリクスはローカルマシンで実行されている Elastic (英語) にエクスポートされます。使用する Elastic サーバーの場所は、次のプロパティを使用して提供できます。

management.metrics.export.elastic.host=https://elastic.example.com:8086

6.2.6. Ganglia

デフォルトでは、メトリクスはローカルマシンで実行されている Ganglia (英語) にエクスポートされます。使用する Ganglia サーバー (英語) ホストとポートは、以下を使用して提供できます。

management.metrics.export.ganglia.host=ganglia.example.com
management.metrics.export.ganglia.port=9649

6.2.7. Graphite

デフォルトでは、メトリクスはローカルマシンで実行されている Graphite (英語) にエクスポートされます。使用する Graphite サーバー (英語) ホストとポートは、以下を使用して提供できます。

management.metrics.export.graphite.host=graphite.example.com
management.metrics.export.graphite.port=9004

Micrometer は、次元のメーター ID がフラットな階層名にマップされる (英語) 方法を管理するデフォルトの HierarchicalNameMapper を提供します。

この動作を制御するには、GraphiteMeterRegistry を定義し、独自の HierarchicalNameMapper を提供します。独自に定義しない限り、自動構成された GraphiteConfig および Clock Bean が提供されます。
@Bean
public GraphiteMeterRegistry graphiteMeterRegistry(GraphiteConfig config, Clock clock) {
    return new GraphiteMeterRegistry(config, clock, MY_HIERARCHICAL_MAPPER);
}

6.2.8. Humio

デフォルトでは、Humio レジストリはメトリクスを cloud.humio.com (英語) に定期的にプッシュします。メトリクスを SaaS Humio (英語) にエクスポートするには、API トークンを提供する必要があります。

management.metrics.export.humio.api-token=YOUR_TOKEN

また、1 つ以上のタグを構成して、メトリクスがプッシュされるデータソースを識別する必要があります。

management.metrics.export.humio.tags.alpha=a
management.metrics.export.humio.tags.bravo=b

6.2.9. Influx

デフォルトでは、メトリクスはローカルマシンで実行されている Influx (英語) にエクスポートされます。使用する Influx サーバー (英語) の場所は、以下を使用して提供できます。

management.metrics.export.influx.uri=https://influx.example.com:8086

6.2.10. JMX

Micrometer は、主に安価で移植性の高いメトリクスをローカルで表示する方法として、JMX (英語) への階層マッピングを提供します。デフォルトでは、メトリクスは metrics JMX ドメインにエクスポートされます。使用するドメインは、次を使用して提供できます。

management.metrics.export.jmx.domain=com.example.app.metrics

Micrometer は、次元のメーター ID がフラットな階層名にマップされる (英語) 方法を管理するデフォルトの HierarchicalNameMapper を提供します。

この動作を制御するには、JmxMeterRegistry を定義し、独自の HierarchicalNameMapper を提供します。独自に定義しない限り、自動構成された JmxConfig および Clock Bean が提供されます。
@Bean
public JmxMeterRegistry jmxMeterRegistry(JmxConfig config, Clock clock) {
    return new JmxMeterRegistry(config, clock, MY_HIERARCHICAL_MAPPER);
}

6.2.11. KairosDB

デフォルトでは、メトリクスはローカルマシンで実行されている KairosDB (英語) にエクスポートされます。使用する KairosDB サーバー (英語) の場所は、以下を使用して提供できます。

management.metrics.export.kairos.uri=https://kairosdb.example.com:8080/api/v1/datapoints

6.2.12. New Relic

New Relic レジストリは、メトリクスを New Relic (英語) に定期的にプッシュします。メトリクスを New Relic (英語) にエクスポートするには、API キーとアカウント ID を提供する必要があります。

management.metrics.export.newrelic.api-key=YOUR_KEY
management.metrics.export.newrelic.account-id=YOUR_ACCOUNT_ID

また、メトリクスが New Relic に送信される間隔を変更することもできます。

management.metrics.export.newrelic.step=30s

デフォルトでは、メトリクスは REST 呼び出しを介して公開されますが、クラスパスにある場合は Java AgentAPI を使用することもできます。

management.metrics.export.newrelic.client-provider-type=insights-agent

最後に、独自の NewRelicClientProvider Bean を定義することで、完全に制御できます。

6.2.13. Prometheus

Prometheus (英語) は、メトリクスの個々のアプリインスタンスをスクレイピングまたはポーリングすることを想定しています。Spring Boot は、/actuator/prometheus で利用可能なアクチュエーターエンドポイントを提供して、適切な形式の Prometheus scrape (英語) を提示します。

エンドポイントはデフォルトでは使用できないため、公開する必要があります。詳細については、エンドポイントの公開を参照してください。

以下は、prometheus.yml に追加する scrape_config の例です。

scrape_configs:
  - job_name: 'spring'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['HOST:PORT']

スクレイピングできるほど長く存在しない可能性のある一時的なジョブやバッチジョブの場合、Prometheus Pushgateway [GitHub] (英語) サポートを使用して、そのメトリクスを Prometheus に公開できます。Prometheus Pushgateway サポートを有効にするには、プロジェクトに次の依存関係を追加します。

<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient_pushgateway</artifactId>
</dependency>

クラスパスに Prometheus Pushgateway 依存関係が存在し、management.metrics.export.prometheus.pushgateway.enabled プロパティが true に設定されている場合、PrometheusPushGatewayManager Bean が自動的に構成されます。これにより、メトリクスの Prometheus Pushgateway へのプッシュが管理されます。

PrometheusPushGatewayManager は、management.metrics.export.prometheus.pushgateway のプロパティを使用して調整できます。高度な構成では、独自の PrometheusPushGatewayManager Bean を提供することもできます。

6.2.14. SignalFx

SignalFx レジストリは、メトリクスを定期的に SignalFx (英語) にプッシュします。メトリクスを SignalFx (英語) にエクスポートするには、アクセストークンを提供する必要があります。

management.metrics.export.signalfx.access-token=YOUR_ACCESS_TOKEN

メトリクスが SignalFx に送信される間隔を変更することもできます。

management.metrics.export.signalfx.step=30s

6.2.15. シンプル

Micrometer には、他のレジストリが構成されていない場合に自動的にフォールバックとして使用される単純なメモリ内バックエンドが付属しています。これにより、メトリクスエンドポイントで収集されるメトリクスを確認できます。

メモリ内のバックエンドは、他の利用可能なバックエンドを使用するとすぐに無効になります。明示的に無効にすることもできます:

management.metrics.export.simple.enabled=false

6.2.16. Stackdriver

Stackdriver レジストリは指標を定期的に Stackdriver にプッシュします。メトリクスを SaaS Stackdriver (英語) にエクスポートするには、Google クラウドプロジェクト ID を指定する必要があります。

management.metrics.export.stackdriver.project-id=my-project

また、メトリクスが Stackdriver に送信される間隔を変更することもできます。

management.metrics.export.stackdriver.step=30s

6.2.17. StatsD

StatsD レジストリは、メトリクスを UDP 経由で StatsD エージェントに積極的にプッシュします。デフォルトでは、メトリクスはローカルマシンで実行されている StatsD (英語) エージェントにエクスポートされます。使用する StatsD エージェントのホストとポートは、次を使用して提供できます。

management.metrics.export.statsd.host=statsd.example.com
management.metrics.export.statsd.port=9125

また、使用する StatsD ラインプロトコルを変更できます（デフォルトは Datadog）。

management.metrics.export.statsd.flavor=etsy

6.2.18. Wavefront

Wavefront レジストリはメトリクスを定期的に Wavefront (英語) にプッシュします。メトリクスを Wavefront (英語) に直接エクスポートする場合は、API トークンを提供する必要があります。

management.metrics.export.wavefront.api-token=YOUR_API_TOKEN

あるいは、メトリクスデータを Wavefront API ホストに転送する環境内に設定された Wavefront サイドカーまたは内部プロキシを使用することもできます。

management.metrics.export.wavefront.uri=proxy://localhost:2878
メトリクスを Wavefront プロキシに公開する場合 ( ドキュメント (英語) に従って)、ホストは proxy://HOST:PORT 形式である必要があります。

メトリクスが Wavefront に送信される間隔を変更することもできます。

management.metrics.export.wavefront.step=30s

6.3. サポートされているメトリクス

Spring Boot は、該当する場合、次の主要なメトリクスを登録します

  • JVM メトリクス、レポート使用率:

    • さまざまなメモリおよびバッファプール

    • ガベージコレクションに関連する統計

    • スレッド使用率

    • ロード / アンロードされたクラスの数

  • CPU メトリクス

  • ファイル記述子のメトリクス

  • Kafka コンシューマー、プロデューサー、ストリームのメトリクス

  • Log4j2 メトリクス: 各レベルで Log4j2 に記録されたイベントの数を記録します

  • Logback メトリクス: 各レベルで Logback に記録されたイベントの数を記録します

  • 稼働時間メトリクス: 稼働時間のゲージと、アプリケーションの絶対開始時間を表す固定ゲージを報告する

  • Tomcat メトリクス (すべての Tomcat メトリクスを登録するには、server.tomcat.mbeanregistry.enabled を true に設定する必要があります)

  • Spring Integration メトリクス

6.3.1. Spring MVC メトリクス

自動構成により、Spring MVC によって処理されるリクエストの計測が可能になります。management.metrics.web.server.request.autotime.enabled が true の場合、このインストルメンテーションはすべてのリクエストに対して発生します。または、false に設定すると、リクエスト処理メソッドに @Timed を追加することでインストルメンテーションを有効にすることができます。

@RestController
@Timed (1)
public class MyController {

    @GetMapping("/api/people")
    @Timed(extraTags = { "region", "us-east-1" }) (2)
    @Timed(value = "all.people", longTask = true) (3)
    public List<Person> listPeople() { ... }

}
1 コントローラー内のすべてのリクエストハンドラーでタイミングを有効にするコントローラークラス。
2 個々のエンドポイントを有効にする方法。これはクラスにある場合は必要ありませんが、この特定のエンドポイントのタイマーをさらにカスタマイズするために使用できます。
3 メソッドの長いタスクタイマーを有効にする longTask = true を使用するメソッド。長いタスクタイマーには別のメトリクス名が必要であり、短いタスクタイマーでスタックできます。

デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.metrics.web.server.request.metric-name プロパティを設定することにより、名前をカスタマイズできます。

デフォルトでは、Spring MVC 関連のメトリクスは次の情報でタグ付けされます。

タグ 説明

exception

リクエストの処理中にスローされた例外の単純なクラス名。

method

リクエストの方法 (たとえば、GET または POST)

outcome

レスポンスのステータスコードに基づくリクエストの結果。1xx は INFORMATIONAL、2xx は SUCCESS、3xx は REDIRECTION、4xx CLIENT_ERROR、5xx は SERVER_ERROR です

status

レスポンスの HTTP ステータスコード (たとえば、200 または 500)

uri

可能であれば、変数置換の前のリクエストの URI テンプレート (たとえば、/api/person/{id})

デフォルトのタグに追加するには、WebMvcTagsContributor を実装する 1 つ以上の @Bean を提供します。デフォルトのタグを置き換えるには、WebMvcTagsProvider を実装する @Bean を提供します。

6.3.2. Spring WebFlux メトリクス

自動構成により、WebFlux コントローラーおよび機能ハンドラーによって処理されるすべてのリクエストの計測が可能になります。

デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.metrics.web.server.request.metric-name プロパティを設定して、名前をカスタマイズできます。

デフォルトでは、WebFlux 関連のメトリクスは次の情報でタグ付けされます。

タグ 説明

exception

リクエストの処理中にスローされた例外の単純なクラス名。

method

リクエストの方法 (たとえば、GET または POST)

outcome

レスポンスのステータスコードに基づくリクエストの結果。1xx は INFORMATIONAL、2xx は SUCCESS、3xx は REDIRECTION、4xx CLIENT_ERROR、5xx は SERVER_ERROR です

status

レスポンスの HTTP ステータスコード (たとえば、200 または 500)

uri

可能であれば、変数置換の前のリクエストの URI テンプレート (たとえば、/api/person/{id})

デフォルトのタグに追加するには、WebFluxTagsContributor を実装する 1 つ以上の @Bean を提供します。デフォルトのタグを置き換えるには、WebFluxTagsProvider を実装する @Bean を提供します。

6.3.3. Jersey サーバーメトリクス

Micrometer の micrometer-jersey2 モジュールがクラスパスにある場合、自動構成により、Jersey JAX-RS 実装によって処理されるリクエストの計測が可能になります。management.metrics.web.server.request.autotime.enabled が true の場合、このインスツルメンテーションはすべてのリクエストに対して発生します。あるいは、false に設定されている場合、@Timed をリクエスト処理メソッドに追加することにより、インストルメンテーションを有効にできます。

@Component
@Path("/api/people")
@Timed (1)
public class Endpoint {
    @GET
    @Timed(extraTags = { "region", "us-east-1" }) (2)
    @Timed(value = "all.people", longTask = true) (3)
    public List<Person> listPeople() { ... }
}
1 リソースクラスで、リソース内のすべてのリクエストハンドラーでタイミングを有効にします。
2 個々のエンドポイントを有効にする方法。これはクラスにある場合は必要ありませんが、この特定のエンドポイントのタイマーをさらにカスタマイズするために使用できます。
3longTask = true を使用したメソッドで、メソッドの長いタスクタイマーを有効にします。長いタスクタイマーには別のメトリクス名が必要であり、短いタスクタイマーでスタックできます。

デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.metrics.web.server.request.metric-name プロパティを設定することにより、名前をカスタマイズできます。

デフォルトでは、Jersey サーバーメトリクスは次の情報でタグ付けされます。

タグ 説明

exception

リクエストの処理中にスローされた例外の単純なクラス名。

method

リクエストの方法 (たとえば、GET または POST)

outcome

レスポンスのステータスコードに基づくリクエストの結果。1xx は INFORMATIONAL、2xx は SUCCESS、3xx は REDIRECTION、4xx CLIENT_ERROR、5xx は SERVER_ERROR です

status

レスポンスの HTTP ステータスコード (たとえば、200 または 500)

uri

可能であれば、変数置換の前のリクエストの URI テンプレート (たとえば、/api/person/{id})

タグをカスタマイズするには、JerseyTagsProvider を実装する @Bean を提供します。

6.3.4. HTTP クライアントメトリクス

Spring Boot Actuator は、RestTemplate と WebClient の両方のインストルメンテーションを管理します。そのためには、自動構成されたビルダーを挿入し、それを使用してインスタンスを作成する必要があります。

  •  RestTemplate 用 RestTemplateBuilder 

  •  WebClient 用 WebClient.Builder 

このインスツルメンテーションを担当するカスタマイザー、つまり MetricsRestTemplateCustomizer および MetricsWebClientCustomizer を手動で適用することもできます。

デフォルトでは、メトリクスは http.client.requests という名前で生成されます。management.metrics.web.client.request.metric-name プロパティを設定することにより、名前をカスタマイズできます。

デフォルトでは、インストルメントされたクライアントによって生成されたメトリクスには、次の情報がタグ付けされます。

タグ 説明

clientName

URI のホスト部分

method

リクエストの方法 (たとえば、GET または POST)

outcome

レスポンスのステータスコードに基づくリクエストの結果。1xx は INFORMATIONAL、2xx は SUCCESS、3xx は REDIRECTION、4xx CLIENT_ERROR、5xx は SERVER_ERROR、UNKNOWN です

status

レスポンスの HTTP ステータスコード（利用可能な場合）（例: 200 または 500）、または I/O の課題の場合は IO_ERROR、それ以外の場合は CLIENT_ERROR 

uri

可能であれば、変数置換の前のリクエストの URI テンプレート (たとえば、/api/person/{id})

タグをカスタマイズし、選択したクライアントに応じて、RestTemplateExchangeTagsProvider または WebClientExchangeTagsProvider を実装する @Bean を提供できます。RestTemplateExchangeTags および WebClientExchangeTags には便利な静的関数があります。

6.3.5. キャッシュメトリクス

自動構成により、起動時に使用可能なすべての Cache のインストルメンテーションが可能になり、メトリクスの先頭に cache が付きます。キャッシュインスツルメンテーションは、メトリクスの基本セットに対して標準化されています。追加のキャッシュ固有のメトリクスも利用できます。

次のキャッシュライブラリがサポートされています。

  • Caffeine

  • EhCache 2

  • Hazelcast

  • 準拠する JCache（JSR-107）実装

メトリクスは、キャッシュの名前と、Bean 名から派生した CacheManager の名前でタグ付けされます。

起動時に設定されるキャッシュのみがレジストリにバインドされます。キャッシュの構成で定義されていないキャッシュの場合、たとえばオンザフライで、起動段階後にプログラムで作成されたキャッシュの場合、明示的な登録が必要です。CacheMetricsRegistrar Bean は、そのプロセスを簡単にするために利用可能になります。

6.3.6. DataSource メトリクス

自動構成により、jdbc.connections のプレフィックスが付いたメトリクスを使用して、使用可能なすべての DataSource オブジェクトのインスツルメンテーションが可能になります。データソースのインスツルメンテーションにより、プール内の現在アクティブな接続、アイドル接続、最大許容接続、最小許容接続を表すゲージが作成されます。

メトリクスは、Bean 名に基づいて計算された DataSource の名前でもタグ付けされます。

デフォルトでは、Spring Boot はサポートされているすべてのデータソースのメタデータを提供します。お気に入りのデータソースがすぐにサポートされない場合は、DataSourcePoolMetadataProvider Bean を追加できます。例については、DataSourcePoolMetadataProvidersConfiguration を参照してください。

また、Hikari 固有のメトリクスは、hikaricp プレフィックスで公開されます。各メトリクスは、プールの名前でタグ付けされます（spring.datasource.name で制御できます）。

6.3.7. Hibernate メトリクス

自動構成により、hibernate という名前のメトリクスで統計が有効になっているすべての使用可能な Hibernate EntityManagerFactory インスタンスのインストルメンテーションが可能になります。

メトリクスは、Bean 名から派生した EntityManagerFactory の名前でもタグ付けされます。

統計を有効にするには、標準の JPA プロパティ hibernate.generate_statistics を true に設定する必要があります。次の例に示すように、自動構成された EntityManagerFactory でそれを有効にできます。

spring.jpa.properties.hibernate.generate_statistics=true

6.3.8. RabbitMQ メトリクス

自動構成により、rabbitmq という名前のメトリクスを使用して、使用可能なすべての RabbitMQ 接続ファクトリのインスツルメンテーションが有効になります。

6.3.9. Kafka メトリクス

自動構成では、自動構成されたコンシューマーファクトリとプロデューサーファクトリにそれぞれ MicrometerConsumerListener と MicrometerProducerListener が登録されます。また、StreamsBuilderFactoryBean の KafkaStreamsMicrometerListener も登録します。詳細については、Spring Kafka ドキュメントの Micrometer ネイティブメトリクスセクションを参照してください。

6.4. カスタムメトリクスの登録

カスタムメトリクスを登録するには、次の例に示すように、MeterRegistry をコンポーネントに挿入します。

class Dictionary {

    private final List<String> words = new CopyOnWriteArrayList<>();

    Dictionary(MeterRegistry registry) {
        registry.gaugeCollectionSize("dictionary.size", Tags.empty(), this.words);
    }

    // …

}

メトリクスが他の Bean に依存している場合は、次の例に示すように、MeterBinder を使用して登録することをお勧めします。

@Bean
MeterBinder queueSize(Queue queue) {
    return (registry) -> Gauge.builder("queueSize", queue::size).register(registry);
}

MeterBinder を使用すると、正しい依存関連が設定され、メトリクスの値が取得されたときに Bean が使用可能になります。MeterBinder の実装は、コンポーネントまたはアプリケーション全体で一連のメトリクスを繰り返し計測する場合にも役立ちます。

デフォルトでは、すべての MeterBinder Bean のメトリクスは、Spring が管理する MeterRegistry に自動的にバインドされます。

6.5. 個々のメトリクスのカスタマイズ

特定の Meter インスタンスにカスタマイズを適用する必要がある場合は、io.micrometer.core.instrument.config.MeterFilter インターフェースを使用できます。

例: com.example で始まるすべてのメーター ID の mytag.region タグの名前を mytag.area に変更する場合、次の操作を実行できます。

@Bean
public MeterFilter renameRegionTagMeterFilter() {
    return MeterFilter.renameTag("com.example", "mytag.region", "mytag.area");
}
デフォルトでは、すべての MeterFilter Bean は、Spring が管理する MeterRegistry に自動的にバインドされます。Metrics の静的メソッドではなく、Spring が管理する MeterRegistry を使用してメトリクスを登録してください。これらは、Spring が管理していないグローバルレジストリを使用します。

6.5.1. 一般的なタグ

一般に、共通タグは、ホスト、インスタンス、リージョン、スタックなどの動作環境でのディメンションのドリルダウンに使用されます。共通タグはすべてのメーターに適用され、次の例に示すように構成できます。

management.metrics.tags.region=us-east-1
management.metrics.tags.stack=prod

上記の例では、region および stack タグを、それぞれ us-east-1 および prod の値を持つすべてのメーターに追加します。

Graphite を使用している場合、共通タグの順序は重要です。このアプローチでは共通タグの順序を保証できないため、Graphite ユーザーは代わりにカスタム MeterFilter を定義することをお勧めします。

6.5.2. メーター別のプロパティ

MeterFilter Bean に加えて、プロパティを使用して、メーター別で限られたカスタマイズセットを適用することもできます。メーターごとのカスタマイズは、指定された名前で始まるすべてのメーター ID に適用されます。例: 以下は、example.remote で始まる ID を持つメーターを無効にします 

management.metrics.enable.example.remote=false

次のプロパティでは、メーターごとのカスタマイズが可能です。

表 1: メーターごとのカスタマイズ
プロパティ 説明

management.metrics.enable

メーターによるメトリクスの出力を拒否するかどうか。

management.metrics.distribution.percentiles-histogram

集計可能な（ディメンション間）パーセンタイル近似の計算に適したヒストグラムを公開するかどうか。

management.metrics.distribution.minimum-expected-value, management.metrics.distribution.maximum-expected-value

期待値の範囲を制限することにより、少ないヒストグラムバケットを公開します。

management.metrics.distribution.percentiles

アプリケーションで計算されたパーセンタイル値を公開する

management.metrics.distribution.slo

サービスレベルゴールによって定義されたバケットを含む累積ヒストグラムを公開します。

percentiles-histogram、percentiles、slo の背景となる概念の詳細については、micrometer ドキュメントの「ヒストグラムとパーセンタイル」セクション (英語) を参照してください。

6.6. メトリクスエンドポイント

Spring Boot は、アプリケーションによって収集されたメトリクスを検査するために診断的に使用できる metrics エンドポイントを提供します。エンドポイントはデフォルトでは使用できないため、公開する必要があります。詳細については、エンドポイントの公開を参照してください。

/actuator/metrics に移動すると、使用可能なメーター名のリストが表示されます。セレクターとして名前を指定することにより、特定のメーターに関する情報を表示するためにドリルダウンできます。/actuator/metrics/jvm.memory.max

ここで使用する名前は、コードで使用される名前と一致する必要があります。提供先の監視システム用に正規化された命名規則に準拠した名前ではありません。つまり、スネークケースの命名規則のために jvm.memory.max が Prometheus で jvm_memory_max として表示される場合、metrics エンドポイントでメーターをインスペクションするときにセレクタとして jvm.memory.max を使用する必要があります。

また、URL の末尾に任意の数の tag=KEY:VALUE クエリパラメーターを追加して、メーターなどのディメンションをドリルダウンすることもできます。/actuator/metrics/jvm.memory.max?tag=area:nonheap

報告される測定値は、メーター名と適用されているタグに一致するすべてのメーターの統計の合計です。上記の例では、返される「値」統計は、ヒープの「コードキャッシュ」、「圧縮クラススペース」、「メタスペース」領域の最大メモリフットプリントの合計です。「メタスペース」の最大サイズのみを確認したい場合は、tag=id:Metaspace、つまり /actuator/metrics/jvm.memory.max?tag=area:nonheap&tag=id:Metaspace を追加できます。

7. 監査

Spring Security が動作すると、Spring Boot Actuator にはイベント（デフォルトでは「認証成功」、「失敗」、「アクセス拒否」の例外）を公開する柔軟な監査フレームワークがあります。この機能は、レポートおよび認証失敗に基づいたロックアウトポリシーの実装に非常に役立ちます。

監査を有効にするには、アプリケーションの構成で型 AuditEventRepository の Bean を提供します。便宜上、Spring Boot は InMemoryAuditEventRepository を提供します。InMemoryAuditEventRepository の機能は限られているため、開発環境でのみ使用することをお勧めします。本番環境では、独自の代替 AuditEventRepository 実装を作成することを検討してください。

7.1. カスタム監査

公開されたセキュリティイベントをカスタマイズするには、AbstractAuthenticationAuditListener および AbstractAuthorizationAuditListener の独自の実装を提供できます。

独自のビジネスイベントに監査サービスを使用することもできます。そのためには、AuditEventRepository Bean を独自のコンポーネントに挿入して直接使用するか、AuditApplicationEvent を Spring ApplicationEventPublisher で公開します（ApplicationEventPublisherAware を実装することにより）。

8. HTTP トレース

HTTP トレースは、アプリケーションの構成で HttpTraceRepository 型の Bean を指定することで有効にできます。便宜上、Spring Boot はデフォルトで、過去 100 回のリクエストとレスポンスの交換のトレースを保存する InMemoryHttpTraceRepository を提供します。InMemoryHttpTraceRepository は他のトレースソリューションと比べて制限があるため、開発環境でのみ使用することをお勧めします。本番環境の場合は、Zipkin や Spring Cloud Sleuth など、本番対応のトレースまたは可観測性ソリューションを使用することをお勧めします。あるいは、ニーズを満たす独自の HttpTraceRepository を作成します。

httptrace エンドポイントを使用して、HttpTraceRepository に格納されているリクエストとレスポンスの交換に関する情報を取得できます。

8.1. カスタム HTTP トレース

各トレースに含まれるアイテムをカスタマイズするには、management.trace.http.include 構成プロパティを使用します。高度なカスタマイズについては、独自の HttpExchangeTracer 実装の登録を検討してください。

9. プロセス監視

spring-boot モジュールには、プロセスの監視に役立つことが多いファイルを作成するための 2 つのクラスがあります。

  • ApplicationPidFileWriter は、アプリケーション PID を含むファイルを作成します（デフォルトでは、ファイル名が application.pid のアプリケーションディレクトリにあります）。

  • WebServerPortFileWriter は、実行中の Web サーバーのポートを含むファイル（またはファイル）を作成します（デフォルトでは、ファイル名が application.port のアプリケーションディレクトリにあります）。

デフォルトでは、これらのライターはアクティブ化されていませんが、次を有効にできます。

9.1. 設定の拡張

META-INF/spring.factories ファイルでは、次の例に示すように、PID ファイルを書き込むリスナーをアクティブにできます。

org.springframework.context.ApplicationListener=\
org.springframework.boot.context.ApplicationPidFileWriter,\
org.springframework.boot.web.context.WebServerPortFileWriter

9.2. プログラム

SpringApplication.addListeners(…​) メソッドを呼び出して適切な Writer オブジェクトを渡すことにより、リスナーをアクティブにすることもできます。このメソッドでは、Writer コンストラクターでファイル名とパスをカスタマイズすることもできます。

10. Cloud Foundry サポート

Spring Boot のアクチュエーターモジュールには、互換性のある Cloud Foundry インスタンスにデプロイするときにアクティブになる追加のサポートが含まれています。/cloudfoundryapplication パスは、すべての @Endpoint Bean への安全な代替ルートを提供します。

拡張サポートにより、Cloud Foundry 管理 UI（デプロイされたアプリケーションの表示に使用できる Web アプリケーションなど）を Spring Boot アクチュエーター情報で強化できます。例: アプリケーションステータスページには、通常の「実行中」または「停止」ステータスではなく、完全なヘルス情報が含まれる場合があります。

/cloudfoundryapplication パスには、通常のユーザーは直接アクセスできません。エンドポイントを使用するには、有効な UAA トークンをリクエストと共に渡す必要があります。

10.1. 拡張 Cloud Foundry アクチュエーターサポートの無効化

/cloudfoundryapplication エンドポイントを完全に無効にする場合は、application.properties ファイルに次の設定を追加できます。

application.properties
management.cloudfoundry.enabled=false

10.2. Cloud Foundry 自己署名証明書

デフォルトでは、/cloudfoundryapplication エンドポイントのセキュリティ検証は、さまざまな Cloud Foundry サービスへの SSL 呼び出しを行います。Cloud Foundry UAA または Cloud Controller サービスが自己署名証明書を使用する場合、次のプロパティを設定する必要があります。

application.properties
management.cloudfoundry.skip-ssl-validation=true

10.3. カスタムコンテキストパス

サーバーのコンテキストパスが / 以外に設定されている場合、Cloud Foundry エンドポイントはアプリケーションのルートで利用できません。例: server.servlet.context-path=/app の場合、Cloud Foundry エンドポイントは /app/cloudfoundryapplication/* で利用可能になります。

サーバーのコンテキストパスに関係なく、/cloudfoundryapplication/* で Cloud Foundry エンドポイントが常に使用できると予想される場合は、アプリケーションで明示的に構成する必要があります。構成は、使用中の Web サーバーによって異なります。Tomcat の場合、次の構成を追加できます。

@Bean
public TomcatServletWebServerFactory servletWebServerFactory() {
    return new TomcatServletWebServerFactory() {

        @Override
        protected void prepareContext(Host host, ServletContextInitializer[] initializers) {
            super.prepareContext(host, initializers);
            StandardContext child = new StandardContext();
            child.addLifecycleListener(new Tomcat.FixContextListener());
            child.setPath("/cloudfoundryapplication");
            ServletContainerInitializer initializer = getServletContextInitializer(getContextPath());
            child.addServletContainerInitializer(initializer, Collections.emptySet());
            child.setCrossContext(true);
            host.addChild(child);
        }

    };
}

private ServletContainerInitializer getServletContextInitializer(String contextPath) {
    return (c, context) -> {
        Servlet servlet = new GenericServlet() {

            @Override
            public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
                ServletContext context = req.getServletContext().getContext(contextPath);
                context.getRequestDispatcher("/cloudfoundryapplication").forward(req, res);
            }

        };
        context.addServlet("cloudfoundry", servlet).addMapping("/*");
    };
}

11. 次のステップ

Graphite (英語) などのグラフ作成ツールについて参照してください。

それ以外の場合は、続けて「デプロイオプション」について読んだり、Spring Boot のビルドツールプラグインに関する詳細情報を読んだりすることができます。