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

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

httpexchanges

HTTP 交換情報を表示します (デフォルトでは、最後の 100 件の HTTP リクエストとレスポンスの交換)。HttpExchangeRepository Bean が必要です。

info

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

integrationgraph

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

loggers

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

liquibase

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

metrics

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

mappings

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

quartz

Quartz スケジューラジョブに関する情報を表示します。

scheduledtasks

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

sessions

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

shutdown

アプリケーションを正常にシャットダウンできるようにします。jar パッケージを使用している場合にのみ機能します。デフォルトでは無効です。

startup

ApplicationStartup によって収集された起動ステップデータを表示します。SpringApplication を BufferingApplicationStartup で構成する必要があります。

threaddump

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

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

ID 説明

heapdump

ヒープダンプファイルを返します。HotSpot JVM では、HPROF -format ファイルが返されます。OpenJ9 JVM では、PHD -format ファイルが返されます。

logfile

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

prometheus

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

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

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

Properties
management.endpoint.shutdown.enabled=true
Yaml
management:
  endpoint:
    shutdown:
      enabled: true

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

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

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

デフォルトでは、Health エンドポイントのみが HTTP および JMX 経由で公開されます。エンドポイントには機密情報が含まれている可能性があるため、エンドポイントをいつ公開するかを慎重に検討する必要があります。

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

プロパティ デフォルト

management.endpoints.jmx.exposure.exclude

management.endpoints.jmx.exposure.include

health

management.endpoints.web.exposure.exclude

management.endpoints.web.exposure.include

health

include プロパティは、公開されているエンドポイントの ID を一覧表示します。exclude プロパティは、公開してはならないエンドポイントの ID を一覧表示します。exclude プロパティは、include プロパティよりも優先されます。エンドポイント ID のリストを使用して、include プロパティと exclude プロパティの両方を構成できます。

例: JMX 経由で health および info エンドポイントのみを公開するには、次のプロパティを使用します。

Properties
management.endpoints.jmx.exposure.include=health,info
Yaml
management:
  endpoints:
    jmx:
      exposure:
        include: "health,info"

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

Properties
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
Yaml
management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"
* は YAML で特別な意味を持っているため、すべてのエンドポイントを含める（または除外する）場合は、必ず引用符を追加してください。
アプリケーションが公開されている場合は、エンドポイントも保護することを強くお勧めします。
エンドポイントが公開されるタイミングについて独自の戦略を実装する場合は、EndpointFilter Bean を登録できます。

2.3. セキュリティ

セキュリティ上の理由から、デフォルトでは /health エンドポイントのみが HTTP 経由で公開されます。management.endpoints.web.exposure.include プロパティを使用して、公開されるエンドポイントを構成できます。

management.endpoints.web.exposure.include を設定する前に、公開されたアクチュエーターに機密情報が含まれていないこと、ファイアウォールの背後に配置して保護されていること、または Spring Security などによって保護されていることを確認してください。

Spring Security がクラスパス上にあり、他の SecurityFilterChain Bean が存在しない場合、/health 以外のすべてのアクチュエーターは Spring Boot 自動構成によって保護されます。カスタム SecurityFilterChain Bean を定義すると、Spring Boot 自動構成がバックオフし、アクチュエーターアクセスルールを完全に制御できるようになります。

HTTP エンドポイントのカスタムセキュリティを構成する場合（たとえば、特定のロールを持つユーザーのみにアクセスを許可する場合）、Spring Boot は、Spring Security と組み合わせて使用できる便利な RequestMatcher オブジェクトをいくつか提供します。

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

Java
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.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic(withDefaults());
        return http.build();
    }

}
Kotlin
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.withDefaults
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
            requests.anyRequest().hasRole("ENDPOINT_ADMIN")
        }
        http.httpBasic(withDefaults())
        return http.build()
    }

}

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

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

Properties
management.endpoints.web.exposure.include=*
Yaml
management:
  endpoints:
    web:
      exposure:
        include: "*"

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

Java
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.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests.anyRequest().permitAll());
        return http.build();
    }

}
Kotlin
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.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
            requests.anyRequest().permitAll()
        }
        return http.build()
    }

}
上記の両方の例で、構成はアクチュエーターのエンドポイントにのみ適用されます。Spring Boot のセキュリティ構成は、SecurityFilterChain Bean が存在する場合は完全にバックオフするため、アプリケーションの残りの部分に適用されるルールを使用して、追加の SecurityFilterChain Bean を構成する必要があります。

2.3.1. クロスサイトリクエストフォージェリ保護

Spring Boot は Spring Security のデフォルトに依存しているため、CSRF 保護はデフォルトでオンになっています。これは、POST （シャットダウンおよびロガーエンドポイント）、PUT、DELETE を必要とするアクチュエーターエンドポイントが、デフォルトのセキュリティ構成が使用されている場合に 403（禁止）エラーを受け取ることを意味します。

非ブラウザークライアントによって使用されるサービスを作成している場合にのみ、CSRF 保護を完全に無効にすることをお勧めします。

CSRF 保護に関する追加情報は、Spring Security リファレンスガイドにあります。

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

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

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

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

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

「検出ページ」を無効にするには、アプリケーションのプロパティに次のプロパティを追加します。

Properties
management.endpoints.web.discovery.enabled=false
Yaml
management:
  endpoints:
    web:
      discovery:
        enabled: false

カスタム管理コンテキストパスが構成されている場合、「検出ページ」は /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 呼び出しが許可されます。

Properties
management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
Yaml
management:
  endpoints:
    web:
      cors:
        allowed-origins: "https://example.com"
        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 が使用されます。

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

Java
@ReadOperation
public CustomData getData() {
    return new CustomData("test", 5);
}
Kotlin
@ReadOperation
fun getData(): CustomData {
    return 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 パラメーターを受け取る書き込み操作を呼び出すことができます。

Java
@WriteOperation
public void updateData(String name, int counter) {
    // injects "test" and 42
}
Kotlin
@WriteOperation
fun updateData(name: String?, counter: Int) {
    // 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 を使用します。

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

HTTP メソッド

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

操作 HTTP メソッド

@ReadOperation

GET

@WriteOperation

POST

@DeleteOperation

DELETE

消費する

リクエスト本文を使用する @WriteOperation （HTTP POST）の場合、述語の consumes 節は 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 アノテーションが付けられたクラスを実装することにより、エンドポイントとして公開できます。サーブレットエンドポイントは、サーブレットコンテナーとのより深い統合を提供しますが、移植性が犠牲になります。これらは、既存のサーブレットをエンドポイントとして公開するために使用することを目的としています。新しいエンドポイントの場合、可能な限り @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 によって導出されます。これは、ステータスの順序付きリストに基づいて、各 HealthIndicator からのステータスをソートします。ソートされたリストの最初のステータスは、全体的なヘルスステータスとして使用されます。HealthIndicator が StatusAggregator に認識されているステータスを返さない場合は、UNKNOWN ステータスが使用されます。

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

2.8.1. 自動構成された HealthIndicators

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

キー 名前 説明

cassandra

CassandraDriverHealthIndicator [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 サーバーが稼働していることを確認します。

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

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

キー 名前 説明

livenessstate

LivenessStateHealthIndicator [GitHub] (英語)

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

readinessstate

ReadinessStateHealthIndicator [GitHub] (英語)

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

2.8.2. カスタム HealthIndicators の作成

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

Java
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();
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        // perform some specific health check
        return ...
    }

}
Kotlin
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.HealthIndicator
import org.springframework.stereotype.Component

@Component
class MyHealthIndicator : HealthIndicator {

    override fun health(): Health {
        val errorCode = check()
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build()
        }
        return Health.up().build()
    }

    private fun check(): Int {
        // perform some specific health check
        return  ...
    }

}
特定の HealthIndicator の識別子は、HealthIndicator 接尾辞が存在しない場合は、HealthIndicator の名前を除いた Bean の名前です。上記の例では、ヘルス情報は my という名前のエントリで利用可能です。
ヘルスインジケータは通常 HTTP を介して呼び出され、接続がタイムアウトする前に応答する必要があります。Spring Boot は、応答に 10 秒以上かかるヘルスインジケーターの警告メッセージをログに記録します。このしきい値を構成する場合は、management.endpoint.health.logging.slow-indicator-threshold プロパティを使用できます。

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

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

Properties
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
Yaml
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 のデフォルトのマッピングを保持します。

Properties
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
Yaml
management:
  endpoint:
    health:
      status:
        http-mapping:
          down: 503
          fatal: 503
          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 は、ElasticScheduler で実行されます。

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

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

Java
import reactor.core.publisher.Mono;

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

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return doHealthCheck().onErrorResume((exception) ->
            Mono.just(new Health.Builder().down(exception).build()));
    }

    private Mono<Health> doHealthCheck() {
        // perform some specific health check
        return ...
    }

}
Kotlin
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.ReactiveHealthIndicator
import org.springframework.stereotype.Component
import reactor.core.publisher.Mono

@Component
class MyReactiveHealthIndicator : ReactiveHealthIndicator {

    override fun health(): Mono<Health> {
        return doHealthCheck()!!.onErrorResume { exception: Throwable? ->
            Mono.just(Health.Builder().down(exception).build())
        }
    }

    private fun doHealthCheck(): Mono<Health>? {
        // perform some specific health check
        return  ...
    }

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

2.8.4. 自動構成された ReactiveHealthIndicators

必要に応じて、Spring Boot は次の ReactiveHealthIndicators を自動構成します。

キー 名前 説明

cassandra

CassandraDriverReactiveHealthIndicator [GitHub] (英語)

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

couchbase

CouchbaseReactiveHealthIndicator [GitHub] (英語)

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

elasticsearch

ElasticsearchReactiveHealthIndicator [GitHub] (英語)

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

mongo

MongoReactiveHealthIndicator [GitHub] (英語)

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

neo4j

Neo4jReactiveHealthIndicator [GitHub] (英語)

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

redis

RedisReactiveHealthIndicator [GitHub] (英語)

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

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

2.8.5. ヘルスグループ

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

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

Properties
management.endpoint.health.group.custom.include=db
Yaml
management:
  endpoint:
    health:
      group:
        custom:
          include: "db"

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

同様に、データベースインジケーターをグループから除外し、他のすべてのインジケーターを含むグループを作成するには、以下を定義できます。

Properties
management.endpoint.health.group.custom.exclude=db
Yaml
management:
  endpoint:
    health:
      group:
        custom:
          exclude: "db"

デフォルトでは、存在しないヘルスインジケーターがヘルスグループに含まれているか除外されている場合、起動は失敗します。この動作を無効にするには、management.endpoint.health.validate-group-membership を false に設定します。

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

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

ヘルスグループは、CompositeHealthContributor を含める / 除外することもできます。CompositeHealthContributor の特定のコンポーネントのみを含める / 除外することもできます。これは、次のようにコンポーネントの完全修飾名を使用して実行できます。

management.endpoint.health.group.custom.include="test/primary"
management.endpoint.health.group.custom.exclude="test/primary/b"

上記の例では、custom グループには、複合 test のコンポーネントである primary という名前の HealthContributor が含まれます。ここで、primary 自体はコンポジットであり、b という名前の HealthContributor は custom グループから除外されます。

ヘルスグループは、メインポートまたは管理ポートのいずれかの追加パスで使用可能にすることができます。これは、セキュリティの目的でアクチュエーターエンドポイントに個別の管理ポートを使用することが非常に一般的である Kubernetes などのクラウド環境で役立ちます。別のポートがあると、ヘルスチェックが成功した場合でもメインアプリケーションが正しく機能しない可能性があるため、ヘルスチェックの信頼性が低下する可能性があります。ヘルスグループは、次のように追加のパスで構成できます。

management.endpoint.health.group.live.additional-path="server:/healthz"

これにより、live ヘルスグループが /healthz のメインサーバーポートで使用できるようになります。プレフィックスは必須であり、server: （メインサーバーポートを表す）または management: （構成されている場合は管理ポートを表す）のいずれかである必要があります。パスは単一のパスセグメントである必要があります。

2.8.6. DataSource ヘルス

DataSource ヘルスインジケーターは、標準データソースとルーティングデータソース Bean の両方のヘルスを示します。ルーティングデータソースの正常性には、その各ターゲットデータソースの正常性が含まれます。ヘルスエンドポイントのレスポンスでは、ルーティングデータソースの各ターゲットは、そのルーティングキーを使用して名前が付けられます。インジケータの出力にルーティングデータソースを含めたくない場合は、management.health.db.ignore-routing-data-sources を true に設定します。

2.9. Kubernetes プローブ

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

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

その後、次のエンドポイント情報を使用して 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> は、アクチュエーターのエンドポイントが使用可能なポートに設定する必要があります。"management.server.port" プロパティが設定されている場合は、メインの Web サーバーポートまたは別の管理ポートである可能性があります。

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

構成された有効期間よりもアプリケーションの起動に時間がかかる場合、Kubernetes は "startupProbe" を可能な解決策として挙げます。一般的に言えば、"readinessProbe" はすべての起動タスクが完了するまで失敗するため、ここでは "startupProbe" は必ずしも必要ではありません。これは、アプリケーションが準備が整うまでトラフィックを受信しないことを意味します。ただし、アプリケーションの起動に時間がかかる場合は、"startupProbe" を使用して、起動中に Kubernetes がアプリケーションを強制終了しないようにすることを検討してください。アプリケーションのライフサイクル中にプローブがどのように動作するかについて説明しているセクションを参照してください。

Actuator エンドポイントが別の管理コンテキストにデプロイされている場合、エンドポイントはメインアプリケーションと同じ Web インフラストラクチャ（ポート、接続プール、フレームワークコンポーネント）を使用しません。この場合、メインアプリケーションが正しく機能しない（たとえば、新しい接続を受け入れることができない）場合でも、プローブチェックは成功する可能性があります。このため、liveness および readiness ヘルスグループをメインサーバーポートで使用できるようにすることをお勧めします。これは、次のプロパティを設定することで実行できます。

management.endpoint.health.probes.add-additional-paths=true

これにより、メインサーバーポート上の /livez で liveness グループが使用可能になり、/readyz で readiness グループが使用可能になります。パスは各グループの additional-path プロパティを使用してカスタマイズできます。詳細については、ヘルスグループを参照してください。

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

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

Properties
management.endpoint.health.group.readiness.include=readinessState,customCheck
Yaml
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 を使用するサービスは、プロバイダーに応じて、接続を受け入れる場合と受け入れない場合があります。明示的な入力 (英語) があるサービスも、実装に応じた方法でレスポンスします。入力サービス自体が、ダウンストリームからの「接続拒否」の処理方法を決定する必要があります。ロードバランサーと入力の両方の場合、HTTP503 が発生する可能性が非常に高くなります。

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

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

Kubernetes Probes サポートの重要な側面は、アプリケーションライフサイクルとの一貫性です。AvailabilityState （アプリケーションのメモリ内の内部状態）と実際のプローブ（その状態を公開する）の間には大きな違いがあります。アプリケーションライフサイクルのフェーズによっては、プローブが使用できない場合があります。

Spring Boot は、起動時とシャットダウン時にアプリケーションイベントを公開し、プローブはそのようなイベントをリッスンして AvailabilityState 情報を公開できます。

次の表は、さまざまな段階での AvailabilityState と HTTP コネクターの状態を示しています。

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

スタートアップフェーズ LivenessStateReadinessStateHttp サーバー ノート

開始

BROKEN

REFUSING_TRAFFIC

未起動

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

起動済み

CORRECT

REFUSING_TRAFFIC

リクエストを拒否します

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

準備完了

CORRECT

ACCEPTING_TRAFFIC

リクエストを受け付けます

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

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

シャットダウンフェーズ 活性状態 準備状態 Http サーバー ノート

実行

CORRECT

ACCEPTING_TRAFFIC

リクエストを受け付けます

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

正常なシャットダウン

CORRECT

REFUSING_TRAFFIC

新しいリクエストは拒否されます

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

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

なし

なし

サーバーがシャットダウンされます

アプリケーションコンテキストが閉じられ、アプリケーションがシャットダウンされます。

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

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

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

2.10.1. 自動構成された InfoContributors

必要に応じて、Spring は次の InfoContributor Bean を自動構成します。

ID 名前 説明 前提条件

build

BuildInfoContributor [GitHub] (英語)

ビルド情報を公開します。

META-INF/build-info.properties リソース。

env

EnvironmentInfoContributor [GitHub] (英語)

名前が info. で始まる Environment からすべてのプロパティを公開します。

なし。

git

GitInfoContributor [GitHub] (英語)

git 情報を公開します。

git.properties リソース。

java

JavaInfoContributor [GitHub] (英語)

Java ランタイム情報を公開します。

なし。

os

OsInfoContributor [GitHub] (英語)

オペレーティングシステム情報を公開します。

なし。

個々のコントリビューターが有効になっているかどうかは、その management.info.<id>.enabled プロパティによって制御されます。コントリビューターが異なれば、その前提条件と公開する情報の性質に応じて、このプロパティのデフォルトも異なります。

有効にする必要があることを示す前提条件がないため、env、java、os コントリビューターはデフォルトで無効になっています。それぞれを有効にするには、management.info.<id>.enabled プロパティを true に設定します。

build および git 情報コントリビューターはデフォルトで有効になっています。management.info.<id>.enabled プロパティを false に設定することで、それぞれを無効にできます。または、通常はデフォルトで有効になっているすべてのコントリビューターを無効にするには、management.info.defaults.enabled プロパティを false に設定します。

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

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

Properties
info.app.encoding=UTF-8
info.app.java.source=17
info.app.java.target=17
Yaml
info:
  app:
    encoding: "UTF-8"
    java:
      source: "17"
      target: "17"

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

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

Properties
[email protected] (英語)  @
[email protected] (英語)  @
[email protected] (英語)  @
Yaml
info:
  app:
    encoding: "@project.build.sourceEncoding@"
    java:
      source: "@java.version@"
      target: "@java.version@"

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 プロパティを使用します。

Properties
management.info.git.mode=full
Yaml
management:
  info:
    git:
      mode: "full"

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

Properties
management.info.git.enabled=false
Yaml
management:
  info:
    git:
      enabled: false

2.10.4. ビルド情報

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

Maven プラグインと Gradle プラグインはどちらもそのファイルを生成できます。詳細については、「ビルド情報の生成方法」を参照してください。

2.10.5. Java 情報

info エンドポイントは、Java ランタイム環境に関する情報を公開します。詳細については、JavaInfo (Javadoc) を参照してください。

2.10.6. OS 情報

info エンドポイントは、オペレーティングシステムに関する情報を公開します。詳細については、OsInfo (Javadoc) を参照してください。

2.10.7. カスタム InfoContributors の作成

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

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

Java
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 MyInfoContributor implements InfoContributor {

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

}
Kotlin
import org.springframework.boot.actuate.info.Info
import org.springframework.boot.actuate.info.InfoContributor
import org.springframework.stereotype.Component
import java.util.Collections

@Component
class MyInfoContributor : InfoContributor {

    override fun contribute(builder: Info.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 プロパティを使用して、管理エンドポイントのプレフィックスを変更できます。

Properties
management.endpoints.web.base-path=/manage
Yaml
management:
  endpoints:
    web:
      base-path: "/manage"

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

別の HTTP ポートを使用してエンドポイントを公開するように管理ポートが構成されていない限り、management.endpoints.web.base-path は server.servlet.context-path （サーブレット Web アプリケーションの場合）または spring.webflux.base-path （リアクティブ Web アプリケーションの場合）に関連しています。management.server.port が構成されている場合、management.endpoints.web.base-path は management.server.base-path を基準にしています。

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

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

Properties
management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck
Yaml
management:
  endpoints:
    web:
      base-path: "/"
      path-mapping:
        health: "healthcheck"

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

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

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

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

3.3. 管理固有の SSL の構成

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

Properties
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
Yaml
server:
  port: 8443
  ssl:
    enabled: true
    key-store: "classpath:store.jks"
    key-password: "secret"
management:
  server:
    port: 8080
    ssl:
      enabled: false

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

Properties
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
Yaml
server:
  port: 8443
  ssl:
    enabled: true
    key-store: "classpath:main.jks"
    key-password: "secret"
management:
  server:
    port: 8080
    ssl:
      enabled: true
      key-store: "classpath:management.jks"
      key-password: "secret"

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

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

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

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

Properties
management.server.port=8081
management.server.address=127.0.0.1
Yaml
management:
  server:
    port: 8081
    address: "127.0.0.1"

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

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

Properties
management.server.port=-1
Yaml
management:
  server:
    port: -1

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

Properties
management.endpoints.web.exposure.exclude=*
Yaml
management:
  endpoints:
    web:
      exposure:
        exclude: "*"

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

Java Management Extensions（JMX）は、アプリケーションを監視および管理するための標準メカニズムを提供します。デフォルトでは、この機能は有効になっていません。spring.jmx.enabled 構成プロパティを true に設定することでオンにできます。Spring Boot は、最も適切な MBeanServer を ID が mbeanServer の Bean として公開します。Spring JMX アノテーション（@ManagedResource、@ManagedAttribute、@ManagedOperation）でアノテーションが付けられた Bean はすべてそれに公開されます。

プラットフォームが標準の MBeanServer を提供している場合、Spring Boot はそれを使用し、必要に応じてデフォルトで VM MBeanServer になります。それがすべて失敗した場合、新しい MBeanServer が作成されます。

詳細については、JmxAutoConfiguration [GitHub] (英語) クラスを参照してください。

デフォルトでは、Spring Boot は管理エンドポイントを org.springframework.boot ドメインの JMXMBean としても公開します。JMX ドメインでのエンドポイント登録を完全に制御するには、独自の EndpointObjectNameFactory 実装を登録することを検討してください。

4.1. MBean 名のカスタマイズ

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

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

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

Properties
spring.jmx.unique-names=true
management.endpoints.jmx.domain=com.example.myapp
Yaml
spring:
  jmx:
    unique-names: true
management:
  endpoints:
    jmx:
      domain: "com.example.myapp"

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

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

Properties
management.endpoints.jmx.exposure.exclude=*
Yaml
management:
  endpoints:
    jmx:
      exposure:
        exclude: "*"

5. 可観測性

可観測性 (オブザーバビリティ) とは、実行中のシステムの内部状態を外部から観測する機能です。これは、ロギング、メトリクス、トレースの 3 つの柱で構成されます。

メトリクスとトレースの場合、Spring Boot は Micrometer Observation (英語) を使用します。独自の観測結果 (メトリクスとトレースにつながる) を作成するには、ObservationRegistry を注入できます。

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
public class MyCustomObservation {

    private final ObservationRegistry observationRegistry;

    public MyCustomObservation(ObservationRegistry observationRegistry) {
        this.observationRegistry = observationRegistry;
    }

    public void doSomething() {
        Observation.createNotStarted("doSomething", this.observationRegistry)
            .lowCardinalityKeyValue("locale", "en-US")
            .highCardinalityKeyValue("userId", "42")
            .observe(() -> {
                // Execute business logic here
            });
    }

}
カーディナリティの低いタグはメトリクスとトレースに追加されますが、カーディナリティの高いタグはトレースにのみ追加されます。

型 ObservationPredicate、GlobalObservationConvention、ObservationHandler の Bean は ObservationRegistry に自動的に登録されます。レジストリをさらに構成するために、任意の数の ObservationRegistryCustomizer Bean を追加登録できます。

詳細については、Micrometer 観測資料 (英語) を参照してください。

JDBC と R2DBC の可観測性は、個別のプロジェクトを使用して構成できます。JDBC の場合、データソース Micrometer プロジェクト [GitHub] (英語) は、JDBC 操作が呼び出されたときに監視を自動的に作成する Spring Boot スターターを提供します。詳細については、リファレンスドキュメントを参照してください (英語) 。R2DBC の場合、R2DBC 観測用の Spring Boot 自動構成 [GitHub] (英語) は R2DBC クエリ呼び出しの監視を作成します。

次のセクションでは、ロギング、メトリクス、トレースについて詳しく説明します。

6. ロガー

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

  • TRACE

  • DEBUG

  • INFO

  • WARN

  • ERROR

  • FATAL

  • OFF

  • null

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

6.1. ロガーを構成する

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

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

7. メトリクス

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

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

7.1. 入門

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

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

Properties
management.datadog.metrics.export.enabled=false
Yaml
management:
  datadog:
    metrics:
      export:
        enabled: false

次の例に示すように、レジストリ固有のプロパティで特に指定されていない限り、すべてのレジストリを無効にすることもできます。

Properties
management.defaults.metrics.export.enabled=false
Yaml
management:
  defaults:
    metrics:
      export:
        enabled: false

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

Properties
management.metrics.use-global-registry=false
Yaml
management:
  metrics:
    use-global-registry: false

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

Java
import io.micrometer.core.instrument.MeterRegistry;

import org.springframework.boot.actuate.autoconfigure.metrics.MeterRegistryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyMeterRegistryConfiguration {

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

}
Kotlin
import io.micrometer.core.instrument.MeterRegistry
import org.springframework.boot.actuate.autoconfigure.metrics.MeterRegistryCustomizer
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyMeterRegistryConfiguration {

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

}

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

Java
import io.micrometer.core.instrument.Meter;
import io.micrometer.core.instrument.config.NamingConvention;
import io.micrometer.graphite.GraphiteMeterRegistry;

import org.springframework.boot.actuate.autoconfigure.metrics.MeterRegistryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyMeterRegistryConfiguration {

    @Bean
    public MeterRegistryCustomizer<GraphiteMeterRegistry> graphiteMetricsNamingConvention() {
        return (registry) -> registry.config().namingConvention(this::name);
    }

    private String name(String name, Meter.Type type, String baseUnit) {
        return ...
    }

}
Kotlin
import io.micrometer.core.instrument.Meter
import io.micrometer.core.instrument.config.NamingConvention
import io.micrometer.graphite.GraphiteMeterRegistry
import org.springframework.boot.actuate.autoconfigure.metrics.MeterRegistryCustomizer
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyMeterRegistryConfiguration {

    @Bean
    fun graphiteMetricsNamingConvention(): MeterRegistryCustomizer<GraphiteMeterRegistry> {
        return MeterRegistryCustomizer { registry: GraphiteMeterRegistry ->
            registry.config().namingConvention(this::name)
        }
    }

    private fun name(name: String, type: Meter.Type, baseUnit: String?): String {
        return  ...
    }

}

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

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

このセクションでは、サポートされている各監視システムについて簡単に説明します。

7.2.1. AppOptics

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

Properties
management.appoptics.metrics.export.api-token=YOUR_TOKEN
Yaml
management:
  appoptics:
    metrics:
      export:
        api-token: "YOUR_TOKEN"

7.2.2. Atlas

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

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

7.2.3. Datadog

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

Properties
management.datadog.metrics.export.api-key=YOUR_KEY
Yaml
management:
  datadog:
    metrics:
      export:
        api-key: "YOUR_KEY"

アプリケーションキー（オプション）を追加で指定すると、メーターの説明、型、ベースユニットなどのメタデータもエクスポートされます。

Properties
management.datadog.metrics.export.api-key=YOUR_API_KEY
management.datadog.metrics.export.application-key=YOUR_APPLICATION_KEY
Yaml
management:
  datadog:
    metrics:
      export:
        api-key: "YOUR_API_KEY"
        application-key: "YOUR_APPLICATION_KEY"

デフォルトでは、メトリクスは Datadog US サイト (英語) （api.datadoghq.com (英語) ）に送信されます。Datadog プロジェクトが他のサイトの 1 つでホストされている場合、またはプロキシを介してメトリクスを送信する必要がある場合は、それに応じて URI を構成します。

Properties
management.datadog.metrics.export.uri=https://api.datadoghq.eu
Yaml
management:
  datadog:
    metrics:
      export:
        uri: "https://api.datadoghq.eu"

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

Properties
management.datadog.metrics.export.step=30s
Yaml
management:
  datadog:
    metrics:
      export:
        step: "30s"

7.2.4. Dynatrace

Dynatrace は 2 つのメトリクス取り込み API を提供し、どちらも Micrometer (英語) 用に実装されています。Micrometer メトリクスの取り込みに関する Dynatrace のドキュメントは ​ ここ (英語) にあります。v1 名前空間の構成プロパティは、Timeseries v1 API (英語) にエクスポートする場合にのみ適用されます。v2 名前空間の構成プロパティは、Metrics v2 API (英語) にエクスポートする場合にのみ適用されます。この統合は、一度に v1 または v2 バージョンの API のいずれかにのみエクスポートできることに注意してください。ただし、v2 が推奨されます。device-id （v1 に必要だが、v2 では使用されない）が v1 名前空間に設定されている場合、メトリクスは v1 エンドポイントにエクスポートされます。それ以外の場合は、v2 が想定されます。

v2 API

v2API は 2 つの方法で使用できます。

自動構成

Dynatrace の自動構成は、OneAgent または Dynatrace OperatorforKubernetes によって監視されるホストで使用できます。

ローカル OneAgent : OneAgent がホストで実行されている場合、メトリクスはローカルの OneAgent 取り込みエンドポイント (英語) に自動的にエクスポートされます。取り込みエンドポイントは、メトリクスを Dynatrace バックエンドに転送します。

DynatraceKubernetes オペレーター : Dynatrace オペレーターがインストールされた Kubernetes で実行すると、レジストリは代わりにオペレーターからエンドポイント URI と API トークンを自動的に取得します。

これはデフォルトの動作であり、io.micrometer:micrometer-registry-dynatrace への依存以外に特別な設定は必要ありません。

手動構成

自動構成が使用できない場合は、Metrics v2 API (英語) のエンドポイントと API トークンが必要です。API トークン (英語) には、「メトリクスの取り込み」（metrics.ingest）権限が設定されている必要があります。トークンの範囲をこの 1 つの権限に制限することをお勧めします。エンドポイント URI にパス（たとえば、/api/v2/metrics/ingest）が含まれていることを確認する必要があります。

Metrics API v2 取り込みエンドポイントの URL は、デプロイオプションによって異なります。

  • SaaS: https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest

  • マネージドデプロイ: https://{your-domain}/e/{your-environment-id}/api/v2/metrics/ingest

以下の例では、example 環境 ID を使用してメトリクスのエクスポートを構成します。

Properties
management.dynatrace.metrics.export.uri=https://example.live.dynatrace.com/api/v2/metrics/ingest
management.dynatrace.metrics.export.api-token=YOUR_TOKEN
Yaml
management:
  dynatrace:
    metrics:
      export:
        uri: "https://example.live.dynatrace.com/api/v2/metrics/ingest"
        api-token: "YOUR_TOKEN"

Dynatrace v2 API を使用する場合、次のオプション機能を使用できます（詳細については、Dynatrace のドキュメント (英語) を参照してください）。

  • メトリクスキープレフィックス: エクスポートされたすべてのメトリクスキーの前に付加されるプレフィックスを設定します。

  • Dynatrace メタデータで強化する: OneAgent または Dynatrace オペレーターが実行されている場合は、追加のメタデータ（たとえば、ホスト、プロセス、pod に関する）でメトリクスを強化します。

  • デフォルトの寸法: エクスポートされたすべてのメトリクスに追加されるキーと値のペアを指定します。同じキーのタグが Micrometer で指定されている場合、デフォルトの寸法を上書きします。

  • Dynatrace サマリー機器を使用する: 場合によっては、Micrometer Dynatrace レジストリが拒否されたメトリクスを作成しました。Micrometer 1.9.x では、これは Dynatrace 固有のサマリーインスツルメントを導入することで修正されました。このトグルを false に設定すると、Micrometer は 1.9.x 以前のデフォルトの動作にフォールバックします。Micrometer 1.8.x から 1.9.x への移行中に問題が発生した場合にのみ使用してください。

次の例に示すように、URI と API トークンを指定しないことは可能です。このシナリオでは、自動的に構成されたエンドポイントが使用されます。

Properties
management.dynatrace.metrics.export.v2.metric-key-prefix=your.key.prefix
management.dynatrace.metrics.export.v2.enrich-with-dynatrace-metadata=true
management.dynatrace.metrics.export.v2.default-dimensions.key1=value1
management.dynatrace.metrics.export.v2.default-dimensions.key2=value2
management.dynatrace.metrics.export.v2.use-dynatrace-summary-instruments=true
Yaml
management:
  dynatrace:
    metrics:
      export:
        # Specify uri and api-token here if not using the local OneAgent endpoint.
        v2:
          metric-key-prefix: "your.key.prefix"
          enrich-with-dynatrace-metadata: true
          default-dimensions:
            key1: "value1"
            key2: "value2"
          use-dynatrace-summary-instruments: true # (default: true)
v1 API (既存)

Dynatrace v1 API メトリクスレジストリは、Timeseries v1 API (英語) を使用して、設定された URI にメトリクスを定期的にプッシュします。既存の設定との下位互換性のために、device-id が設定されている場合（v1 には必須ですが、v2 では使用されません）、メトリクスは Timeseries v1 エンドポイントにエクスポートされます。メトリクスを Dynatrace (英語) にエクスポートするには、API トークン、デバイス ID、URI を指定する必要があります。

Properties
management.dynatrace.metrics.export.uri=https://{your-environment-id}.live.dynatrace.com
management.dynatrace.metrics.export.api-token=YOUR_TOKEN
management.dynatrace.metrics.export.v1.device-id=YOUR_DEVICE_ID
Yaml
management:
  dynatrace:
    metrics:
      export:
        uri: "https://{your-environment-id}.live.dynatrace.com"
        api-token: "YOUR_TOKEN"
        v1:
          device-id: "YOUR_DEVICE_ID"

v1 API の場合、v1 エンドポイントパスが自動的に追加されるため、パスなしで基本環境 URI を指定する必要があります。

バージョンに依存しない設定

API エンドポイントとトークンに加えて、メトリクスが Dynatrace に送信される間隔を変更することもできます。デフォルトのエクスポート間隔は 60s です。次の例では、エクスポート間隔を 30 秒に設定します。

Properties
management.dynatrace.metrics.export.step=30s
Yaml
management:
  dynatrace:
    metrics:
      export:
        step: "30s"

Micrometer ドキュメント (英語) および Dynatrace のドキュメント (英語) で Micrometer 用の Dynatrace エクスポーターをセットアップする方法の詳細については、こちらを参照してください。

7.2.5. Elastic

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

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

7.2.6. Ganglia

デフォルトでは、メトリクスはローカルマシンで実行されている Ganglia (英語) にエクスポートされます。次の例に示すように、Ganglia サーバー (英語) ホストとポートを指定できます。

Properties
management.ganglia.metrics.export.host=ganglia.example.com
management.ganglia.metrics.export.port=9649
Yaml
management:
  ganglia:
    metrics:
      export:
        host: "ganglia.example.com"
        port: 9649

7.2.7. Graphite

デフォルトでは、メトリクスはローカルマシンで実行されている Graphite (英語) にエクスポートされます。次の例に示すように、Graphite サーバー (英語) ホストとポートを指定できます。

Properties
management.graphite.metrics.export.host=graphite.example.com
management.graphite.metrics.export.port=9004
Yaml
management:
  graphite:
    metrics:
      export:
         host: "graphite.example.com"
         port: 9004

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

この動作を制御するには、GraphiteMeterRegistry を定義し、独自の HierarchicalNameMapper を提供します。独自に定義しない限り、自動構成された GraphiteConfig および Clock Bean が提供されます。

Java
import io.micrometer.core.instrument.Clock;
import io.micrometer.core.instrument.Meter;
import io.micrometer.core.instrument.config.NamingConvention;
import io.micrometer.core.instrument.util.HierarchicalNameMapper;
import io.micrometer.graphite.GraphiteConfig;
import io.micrometer.graphite.GraphiteMeterRegistry;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyGraphiteConfiguration {

    @Bean
    public GraphiteMeterRegistry graphiteMeterRegistry(GraphiteConfig config, Clock clock) {
        return new GraphiteMeterRegistry(config, clock, this::toHierarchicalName);
    }

    private String toHierarchicalName(Meter.Id id, NamingConvention convention) {
        return ...
    }

}
Kotlin
import io.micrometer.core.instrument.Clock
import io.micrometer.core.instrument.Meter
import io.micrometer.core.instrument.config.NamingConvention
import io.micrometer.core.instrument.util.HierarchicalNameMapper
import io.micrometer.graphite.GraphiteConfig
import io.micrometer.graphite.GraphiteMeterRegistry
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyGraphiteConfiguration {

    @Bean
    fun graphiteMeterRegistry(config: GraphiteConfig, clock: Clock): GraphiteMeterRegistry {
        return GraphiteMeterRegistry(config, clock, this::toHierarchicalName)
    }
    private fun toHierarchicalName(id: Meter.Id, convention: NamingConvention): String {
        return  ...
    }

}

7.2.8. Humio

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

Properties
management.humio.metrics.export.api-token=YOUR_TOKEN
Yaml
management:
  humio:
    metrics:
      export:
        api-token: "YOUR_TOKEN"

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

Properties
management.humio.metrics.export.tags.alpha=a
management.humio.metrics.export.tags.bravo=b
Yaml
management:
  humio:
    metrics:
      export:
        tags:
          alpha: "a"
          bravo: "b"

7.2.9. Influx

デフォルトでは、メトリクスは、デフォルト構成でローカルマシンで実行されている Influx (英語) v1 インスタンスにエクスポートされます。メトリクスを InfluxDBv2 にエクスポートするには、メトリクスを書き込むための org、bucket、認証 token を構成します。以下を使用して、使用する Influx サーバー (英語) の場所を指定できます。

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

7.2.10. JMX

Micrometer は、JMX (英語) への階層マッピングを提供します。これは主に、メトリクスをローカルで表示するための安価でポータブルなメソッドです。デフォルトでは、メトリクスは metrics JMX ドメインにエクスポートされます。以下を使用して、使用するドメインを指定できます。

Properties
management.jmx.metrics.export.domain=com.example.app.metrics
Yaml
management:
  jmx:
    metrics:
      export:
        domain: "com.example.app.metrics"

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

この動作を制御するには、JmxMeterRegistry を定義し、独自の HierarchicalNameMapper を提供します。独自に定義しない限り、自動構成された JmxConfig および Clock Bean が提供されます。

Java
import io.micrometer.core.instrument.Clock;
import io.micrometer.core.instrument.Meter;
import io.micrometer.core.instrument.config.NamingConvention;
import io.micrometer.core.instrument.util.HierarchicalNameMapper;
import io.micrometer.jmx.JmxConfig;
import io.micrometer.jmx.JmxMeterRegistry;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyJmxConfiguration {

    @Bean
    public JmxMeterRegistry jmxMeterRegistry(JmxConfig config, Clock clock) {
        return new JmxMeterRegistry(config, clock, this::toHierarchicalName);
    }

    private String toHierarchicalName(Meter.Id id, NamingConvention convention) {
        return ...
    }

}
Kotlin
import io.micrometer.core.instrument.Clock
import io.micrometer.core.instrument.Meter
import io.micrometer.core.instrument.config.NamingConvention
import io.micrometer.core.instrument.util.HierarchicalNameMapper
import io.micrometer.jmx.JmxConfig
import io.micrometer.jmx.JmxMeterRegistry
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyJmxConfiguration {

    @Bean
    fun jmxMeterRegistry(config: JmxConfig, clock: Clock): JmxMeterRegistry {
        return JmxMeterRegistry(config, clock, this::toHierarchicalName)
    }

    private fun toHierarchicalName(id: Meter.Id, convention: NamingConvention): String {
        return  ...
    }

}

7.2.11. KairosDB

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

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

7.2.12. New Relic

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

Properties
management.newrelic.metrics.export.api-key=YOUR_KEY
management.newrelic.metrics.export.account-id=YOUR_ACCOUNT_ID
Yaml
management:
  newrelic:
    metrics:
      export:
        api-key: "YOUR_KEY"
        account-id: "YOUR_ACCOUNT_ID"

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

Properties
management.newrelic.metrics.export.step=30s
Yaml
management:
  newrelic:
    metrics:
      export:
        step: "30s"

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

Properties
management.newrelic.metrics.export.client-provider-type=insights-agent
Yaml
management:
  newrelic:
    metrics:
      export:
        client-provider-type: "insights-agent"

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

7.2.13. OpenTelemetry

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

Properties
management.otlp.metrics.export.url=https://otlp.example.com:4318/v1/metrics
Yaml
management:
  otlp:
    metrics:
      export:
        url: "https://otlp.example.com:4318/v1/metrics"

7.2.14. Prometheus

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

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

次の例の scrape_config は prometheus.yml に追加されます。

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

Prometheus Exemplars (英語) もサポートされています。この機能を有効にするには、SpanContextSupplier Bean が必要です。Micrometer トレース (英語) を使用する場合、これは自動構成されますが、必要に応じていつでも独自に作成できます。Prometheus ドキュメント (英語) を確認してください。この機能は Prometheus 側で明示的に有効にする必要があり、OpenMetrics [GitHub] (英語) 形式を使用した場合にのみサポートされます。

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

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

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

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

7.2.15. SignalFx

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

Properties
management.signalfx.metrics.export.access-token=YOUR_ACCESS_TOKEN
Yaml
management:
  signalfx:
    metrics:
      export:
        access-token: "YOUR_ACCESS_TOKEN"

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

Properties
management.signalfx.metrics.export.step=30s
Yaml
management:
  signalfx:
    metrics:
      export:
        step: "30s"

7.2.16. シンプル

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

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

Properties
management.simple.metrics.export.enabled=false
Yaml
management:
  simple:
    metrics:
      export:
        enabled: false

7.2.17. Stackdriver

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

Properties
management.stackdriver.metrics.export.project-id=my-project
Yaml
management:
  stackdriver:
    metrics:
      export:
        project-id: "my-project"

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

Properties
management.stackdriver.metrics.export.step=30s
Yaml
management:
  stackdriver:
    metrics:
      export:
        step: "30s"

7.2.18. StatsD

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

Properties
management.statsd.metrics.export.host=statsd.example.com
management.statsd.metrics.export.port=9125
management.statsd.metrics.export.protocol=udp
Yaml
management:
  statsd:
    metrics:
      export:
        host: "statsd.example.com"
        port: 9125
        protocol: "udp"

使用する StatsD 回線プロトコルを変更することもできます（デフォルトは Datadog です）。

Properties
management.statsd.metrics.export.flavor=etsy
Yaml
management:
  statsd:
    metrics:
      export:
        flavor: "etsy"

7.2.19. Wavefront

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

Properties
management.wavefront.api-token=YOUR_API_TOKEN
Yaml
management:
  wavefront:
    api-token: "YOUR_API_TOKEN"

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

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

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

Properties
management.wavefront.metrics.export.step=30s
Yaml
management:
  wavefront:
    metrics:
      export:
        step: "30s"

7.3. サポートされているメトリクスとメーター

Spring Boot は、さまざまなテクノロジーの自動メーター登録を提供します。ほとんどの場合、デフォルトは、サポートされている監視システムのいずれかに公開できる実用的なメトリクスを提供します。

7.3.1. JVM メトリクス

自動構成により、コア Micrometer クラスを使用して JVM メトリクスが有効になります。JVM メトリクスは、jvm. メーター名で公開されます。

次の JVM メトリクスが提供されます。

  • さまざまなメモリとバッファプールの詳細

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

  • スレッドの使用率

  • ロードおよびアンロードされたクラスの数

  • JVM バージョン情報

  • JIT コンパイル時間

7.3.2. システムメトリクス

自動構成により、コア Micrometer クラスを使用してシステムメトリクスが有効になります。システムメトリクスは、system.、process.、disk. メーター名で公開されます。

次のシステムメトリクスが提供されます。

  • CPU メトリクス

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

  • 稼働時間メトリクス (アプリケーションが実行されている時間と絶対開始時間の固定ゲージの両方)

  • 利用可能なディスク容量

7.3.3. アプリケーションの起動メトリクス

自動構成により、アプリケーションの起動時間メトリクスが公開されます。

  • application.started.time: アプリケーションの起動にかかる時間。

  • application.ready.time: アプリケーションがリクエストを処理する準備ができるまでにかかる時間。

メトリクスは、アプリケーションクラスの完全修飾名でタグ付けされます。

7.3.4. ロガーメトリクス

自動構成により、Logback と Log4J2 の両方のイベントメトリクスが有効になります。詳細は、log4j2.events. または logback.events. メーター名で公開されています。

7.3.5. タスクの実行とスケジューリングの指標

自動構成により、基盤となる ThreadPoolExecutor が使用可能である限り、使用可能なすべての ThreadPoolTaskExecutor および ThreadPoolTaskScheduler Bean のインスツルメンテーションが可能になります。メトリクスは、Bean 名から派生したエグゼキュータの名前でタグ付けされます。

7.3.6. Spring MVC メトリクス

自動構成により、Spring MVC コントローラーおよび機能ハンドラーによって処理されるすべてのリクエストのインストルメンテーションが可能になります。デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.observations.http.server.requests.name プロパティを設定することにより、名前をカスタマイズできます。

生成された観測の詳細については、Spring Framework リファレンスドキュメントを参照してください。

デフォルトのタグに追加するには、org.springframework.http.server.observation パッケージから DefaultServerRequestObservationConvention を継承する @Bean を提供します。デフォルトのタグを置き換えるには、ServerRequestObservationConvention を実装する @Bean を提供します。

場合によっては、Web コントローラーで処理される例外は、リクエストメトリクスタグとして記録されません。アプリケーションは、処理された例外をリクエスト属性として設定することにより、オプトインして例外を記録できます。

デフォルトでは、すべてのリクエストが処理されます。フィルターをカスタマイズするには、FilterRegistrationBean<WebMvcMetricsFilter> を実装する @Bean を提供します。

7.3.7. Spring WebFlux メトリクス

自動構成により、Spring WebFlux コントローラーおよび機能ハンドラーによって処理されるすべてのリクエストのインストルメンテーションが可能になります。デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.observations.http.server.requests.name プロパティを設定することにより、名前をカスタマイズできます。

生成された観測の詳細については、Spring Framework リファレンスドキュメントを参照してください。

デフォルトのタグに追加するには、org.springframework.http.server.reactive.observation パッケージから DefaultServerRequestObservationConvention を継承する @Bean を提供します。デフォルトのタグを置き換えるには、ServerRequestObservationConvention を実装する @Bean を提供します。

場合によっては、コントローラーおよびハンドラー関数で処理される例外は、リクエストメトリクスタグとして記録されません。アプリケーションは、処理された例外をリクエスト属性として設定することにより、オプトインして例外を記録できます。

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

自動構成により、Jersey JAX-RS 実装によって処理されるすべてのリクエストのインストルメンテーションが可能になります。デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.observations.http.server.requests.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 を提供します。

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

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

  •  RestTemplate 用 RestTemplateBuilder 

  •  WebClient 用 WebClient.Builder 

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

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

生成された観測の詳細については、Spring Framework リファレンスドキュメントを参照してください。

RestTemplate の使用時にタグをカスタマイズするには、org.springframework.http.client.observation パッケージから ClientRequestObservationConvention を実装する @Bean を提供します。WebClient の使用時にタグをカスタマイズするには、org.springframework.web.reactive.function.client パッケージから ClientRequestObservationConvention を実装する @Bean を提供します。

7.3.10. Tomcat メトリクス

自動構成により、MBeanRegistry が有効になっている場合にのみ Tomcat のインストルメンテーションが有効になります。デフォルトでは、MBeanRegistry は無効になっていますが、server.tomcat.mbeanregistry.enabled を true に設定することで有効にできます。

Tomcat メトリクスは、tomcat. メーター名で公開されています。

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

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

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

  • Cache2k

  • Caffeine

  • Hazelcast

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

  • Redis

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

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

7.3.12. Spring Batch メトリクス

Spring Batch リファレンスドキュメントを参照してください。

7.3.13. Spring GraphQL メトリクス

Spring GraphQL リファレンスドキュメントを参照してください。

7.3.14. DataSource メトリクス

自動構成により、jdbc.connections で始まるメトリクスを使用して、使用可能なすべての DataSource オブジェクトをインストルメント化できます。データソースインストルメンテーションは、プール内の現在アクティブ、アイドル、最大許容、最小許容接続を表すゲージになります。

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

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

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

7.3.15. Hibernate メトリクス

org.hibernate.orm:hibernate-micrometer がクラスパス上にある場合、統計が有効になっている使用可能なすべての Hibernate EntityManagerFactory インスタンスは、hibernate という名前のメトリクスで計測されます。

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

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

Properties
spring.jpa.properties[hibernate.generate_statistics]=true
Yaml
spring:
  jpa:
    properties:
      "[hibernate.generate_statistics]": true

7.3.16. Spring Data リポジトリメトリクス

自動構成により、すべての Spring Data Repository メソッド呼び出しのインストルメンテーションが可能になります。デフォルトでは、メトリクスは spring.data.repository.invocations という名前で生成されます。management.metrics.data.repository.metric-name プロパティを設定することにより、名前をカスタマイズできます。

io.micrometer.core.annotation パッケージの @Timed アノテーションは、Repository インターフェースとメソッドでサポートされています。すべての Repository 呼び出しのメトリクスを記録したくない場合は、management.metrics.data.repository.autotime.enabled を false に設定し、代わりに @Timed アノテーションのみを使用できます。

longTask = true を使用した @Timed アノテーションにより、メソッドの長いタスクタイマーが有効になります。長いタスクタイマーには個別のメトリクス名が必要であり、短いタスクタイマーとスタックできます。

デフォルトでは、リポジトリ呼び出し関連のメトリクスは次の情報でタグ付けされています。

タグ 説明

repository

ソース Repository の単純なクラス名。

method

呼び出された Repository メソッドの名前。

state

結果の状態（SUCCESS、ERROR、CANCELED、または RUNNING）。

exception

呼び出しからスローされた例外の単純なクラス名。

デフォルトのタグを置き換えるには、RepositoryTagsProvider を実装する @Bean を提供します。

7.3.17. RabbitMQ メトリクス

自動構成により、rabbitmq という名前のメトリクスを使用して、使用可能なすべての RabbitMQ 接続ファクトリをインストルメント化できます。

7.3.18. Spring Integration メトリクス

Spring Integration は、MeterRegistry Bean が使用可能な場合は常に、Micrometer サポートを自動的に提供します。メトリクスは、spring.integration. メーター名で公開されています。

7.3.19. Kafka メトリクス

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

7.3.20. MongoDB メトリクス

このセクションでは、MongoDB で使用可能なメトリクスについて簡単に説明します。

MongoDB コマンドメトリクス

自動構成は、MongoMetricsCommandListener を自動構成された MongoClient に登録します。

基礎となる MongoDB ドライバーに発行されたコマンドごとに、mongodb.driver.commands という名前のタイマーメトリクスが作成されます。各メトリクスには、デフォルトで次の情報がタグ付けされています。

タグ 説明

command

発行されたコマンドの名前。

cluster.id

コマンドの送信先のクラスターの ID。

server.address

コマンドの送信先のサーバーのアドレス。

status

コマンドの結果（SUCCESS または FAILED）。

次の例に示すように、デフォルトのメトリクスタグを置き換えるには、MongoCommandTagsProvider Bean を定義します。

Java
import io.micrometer.core.instrument.binder.mongodb.MongoCommandTagsProvider;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyCommandTagsProviderConfiguration {

    @Bean
    public MongoCommandTagsProvider customCommandTagsProvider() {
        return new CustomCommandTagsProvider();
    }

}
Kotlin
import io.micrometer.core.instrument.binder.mongodb.MongoCommandTagsProvider
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyCommandTagsProviderConfiguration {

    @Bean
    fun customCommandTagsProvider(): MongoCommandTagsProvider? {
        return CustomCommandTagsProvider()
    }

}

自動構成されたコマンドメトリクスを無効にするには、次のプロパティを設定します。

Properties
management.metrics.mongo.command.enabled=false
Yaml
management:
  metrics:
    mongo:
      command:
        enabled: false
MongoDB 接続プールメトリクス

自動構成は、MongoMetricsConnectionPoolListener を自動構成された MongoClient に登録します。

次のゲージメトリクスが接続プール用に作成されます。

  • mongodb.driver.pool.size は、アイドル状態のメンバーと使用中のメンバーを含む、接続プールの現在のサイズを報告します。

  • mongodb.driver.pool.checkedout は、現在使用されている接続の数を報告します。

  • mongodb.driver.pool.waitqueuesize は、プールからの接続の待機キューの現在のサイズを報告します。

各メトリクスには、デフォルトで次の情報がタグ付けされています。

タグ 説明

cluster.id

接続プールが対応するクラスターの ID。

server.address

接続プールが対応するサーバーのアドレス。

デフォルトのメトリクスタグを置き換えるには、MongoConnectionPoolTagsProvider Bean を定義します。

Java
import io.micrometer.core.instrument.binder.mongodb.MongoConnectionPoolTagsProvider;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyConnectionPoolTagsProviderConfiguration {

    @Bean
    public MongoConnectionPoolTagsProvider customConnectionPoolTagsProvider() {
        return new CustomConnectionPoolTagsProvider();
    }

}
Kotlin
import io.micrometer.core.instrument.binder.mongodb.MongoConnectionPoolTagsProvider
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyConnectionPoolTagsProviderConfiguration {

    @Bean
    fun customConnectionPoolTagsProvider(): MongoConnectionPoolTagsProvider {
        return CustomConnectionPoolTagsProvider()
    }

}

自動構成された接続プールメトリクスを無効にするには、次のプロパティを設定します。

Properties
management.metrics.mongo.connectionpool.enabled=false
Yaml
management:
  metrics:
    mongo:
      connectionpool:
        enabled: false

7.3.21. Jetty メトリクス

自動構成は、Micrometer の JettyServerThreadPoolMetrics を使用して、Jetty の ThreadPool のメトリクスをバインドします。Jetty の Connector インスタンスのメトリクスは、Micrometer の JettyConnectionMetrics を使用してバインドされ、server.ssl.enabled が true に設定されている場合は、Micrometer の JettySslHandshakeMetrics にバインドされます。

7.3.22. @Timed アノテーションのサポート

Spring Boot で直接サポートされていない @Timed を使用するには、Micrometer ドキュメント (英語) を参照してください。

7.3.23. Redis メトリクス

自動構成は、自動構成された LettuceConnectionFactory の MicrometerCommandLatencyRecorder を登録します。詳細については、Lettuce ドキュメントの Micrometer メトリクスセクション (英語) を参照してください。

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

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

Java
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Tags;

import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final Dictionary dictionary;

    public MyBean(MeterRegistry registry) {
        this.dictionary = Dictionary.load();
        registry.gauge("dictionary.size", Tags.empty(), this.dictionary.getWords().size());
    }

}
Kotlin
import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Tags
import org.springframework.stereotype.Component

@Component
class MyBean(registry: MeterRegistry) {

    private val dictionary: Dictionary

    init {
        dictionary = Dictionary.load()
        registry.gauge("dictionary.size", Tags.empty(), dictionary.words.size)
    }

}

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

Java
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.binder.MeterBinder;

import org.springframework.context.annotation.Bean;

public class MyMeterBinderConfiguration {

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

}
Kotlin
import io.micrometer.core.instrument.Gauge
import io.micrometer.core.instrument.binder.MeterBinder
import org.springframework.context.annotation.Bean

class MyMeterBinderConfiguration {

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

}

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

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

7.5. 個々の指標のカスタマイズ

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

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

Java
import io.micrometer.core.instrument.config.MeterFilter;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyMetricsFilterConfiguration {

    @Bean
    public MeterFilter renameRegionTagMeterFilter() {
        return MeterFilter.renameTag("com.example", "mytag.region", "mytag.area");
    }

}
Kotlin
import io.micrometer.core.instrument.config.MeterFilter
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyMetricsFilterConfiguration {

    @Bean
    fun renameRegionTagMeterFilter(): MeterFilter {
        return MeterFilter.renameTag("com.example", "mytag.region", "mytag.area")
    }

}
デフォルトでは、すべての MeterFilter Bean は、Spring が管理する MeterRegistry に自動的にバインドされます。Metrics の静的メソッドではなく、Spring が管理する MeterRegistry を使用してメトリクスを登録してください。これらは、Spring が管理していないグローバルレジストリを使用します。

7.5.1. 共通タグ

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

Properties
management.metrics.tags.region=us-east-1
management.metrics.tags.stack=prod
Yaml
management:
  metrics:
    tags:
      region: "us-east-1"
      stack: "prod"

前の例では、region タグと stack タグを、それぞれ us-east-1 と prod の値ですべてのメーターに追加します。

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

7.5.2. メーターごとのプロパティ

MeterFilter Bean に加えて、プロパティを使用してメーターごとに限定されたカスタマイズセットを適用できます。メーターごとのカスタマイズは、Spring Boot の PropertiesMeterFilter を使用して、指定された名前で始まるすべてのメーター ID に適用されます。次の例では、ID が example.remote で始まるすべてのメーターを除外します。

Properties
management.metrics.enable.example.remote=false
Yaml
management:
  metrics:
    enable:
      example:
        remote: false

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

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

management.metrics.enable

特定の ID を持つメーターを受け入れるかどうか。受け入れられないメーターは MeterRegistry からフィルタリングされます。

management.metrics.distribution.percentiles-histogram

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

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

期待値の範囲をクランプすることにより、公開するヒストグラムバケットの数を減らします。

management.metrics.distribution.percentiles

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

management.metrics.distribution.expiry, management.metrics.distribution.buffer-length

構成可能な有効期限の後に回転するリングバッファーに、構成可能なバッファー長で蓄積することにより、最近のサンプルにより大きな重みを与えます。

management.metrics.distribution.slo

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

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

7.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）。

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

7.7. Micrometer Observation との統合

DefaultMeterObservationHandler は ObservationRegistry に自動的に登録され、完了した観測ごとにメトリクスが作成されます。

8. トレース

Spring Boot Actuator は、一般的なトレーサーライブラリのファサードである Micrometer トレース (英語) の依存関係管理と自動構成を提供します。

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

8.1. サポートされているトレーサー

Spring Boot には、次のトレーサーの自動構成が同梱されています。

8.2. 入門

トレースを開始するために使用できるサンプルアプリケーションが必要です。私たちの目的では、単純な "Hello World!" です。"getting-started.html" セクションで説明されている Web アプリケーションで十分です。OpenTelemetry トレーサーと Zipkin をトレースバックエンドとして使用します。

要約すると、メインのアプリケーションコードは次のようになります。

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@SpringBootApplication
public class MyApplication {

    private static final Log logger = LogFactory.getLog(MyApplication.class);

    @RequestMapping("/")
    String home() {
        logger.info("home() has been called");
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}
home() メソッドには logger ステートメントが追加されていますが、これは後で重要になります。

次に、次の依存関係を追加する必要があります。

  • org.springframework.boot:spring-boot-starter-actuator

  • io.micrometer:micrometer-tracing-bridge-otel - Micrometer Observation API を OpenTelemetry にブリッジします。

  • io.opentelemetry:opentelemetry-exporter-zipkin - トレース (英語) を Zipkin に報告します。

次のアプリケーションプロパティを追加します。

Properties
management.tracing.sampling.probability=1.0
Yaml
management:
  tracing:
    sampling:
      probability: 1.0

デフォルトでは、Spring Boot はリクエストの 10% のみをサンプリングして、トレースバックエンドがオーバーロードになるのを防ぎます。このプロパティは、すべてのリクエストがトレースバックエンドに送信されるように、100% に切り替えます。

トレースを収集して視覚化するには、実行中のトレースバックエンドが必要です。ここではトレースバックエンドとして Zipkin を使用します。Zipkin クイックスタートガイド (英語) は、Zipkin をローカルで開始する方法を説明します。

Zipkin が実行されたら、アプリケーションを開始できます。

Web ブラウザーを localhost:8080 で開くと、次の出力が表示されるはずです。

Hello World!

バックグラウンドで HTTP リクエストの監視が作成され、そのリクエストが OpenTelemetry にブリッジされ、OpenTelemetry が新しいトレースを Zipkin に報告します。

次に、localhost:9411 で Zipkin UI を開き、クエリの実行 ボタンを押して、収集されたすべてのトレースを一覧表示します。トレースが 1 つ表示されるはずです。「表示」ボタンを押すと、そのトレースの詳細が表示されます。

logging.pattern.level プロパティを %5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}] に設定することにより、現在のトレースとスパン ID をログに含めることができます。

8.3. トレースの伝播

ネットワーク上でトレースを自動的に伝播するには、自動構成された RestTemplateBuilder または WebClient.Builder を使用してクライアントを構築します。

自動構成ビルダーを使用せずに WebClient または RestTemplate を作成すると、自動トレース伝播は機能しません。

8.4. トレーサーの実装

Micrometer トレーサーは複数のトレーサーの実装をサポートしているため、Spring Boot では複数の依存関係の組み合わせが可能です。

すべてのトレーサーの実装には、org.springframework.boot:spring-boot-starter-actuator 依存関係が必要です。

8.4.1. OpenTelemetry と Zipkin

OpenTelemetry を使用したトレースと Zipkin へのレポートには、次の依存関係が必要です。

  • io.micrometer:micrometer-tracing-bridge-otel - Micrometer Observation API を OpenTelemetry にブリッジします。

  • io.opentelemetry:opentelemetry-exporter-zipkin - トレースを Zipkin に報告します。

management.zipkin.tracing.* 構成プロパティを使用して、Zipkin へのレポートを構成します。

8.4.2. OpenTelemetry と Wavefront

OpenTelemetry を使用したトレースと Wavefront へのレポートには、次の依存関係が必要です。

  • io.micrometer:micrometer-tracing-bridge-otel - Micrometer Observation API を OpenTelemetry にブリッジします。

  • io.micrometer:micrometer-tracing-reporter-wavefront - トレースを Wavefront に報告します。

management.wavefront.* 構成プロパティを使用して、Wavefront へのレポートを構成します。

8.4.3. OpenTelemetry と OTLP

OpenTelemetry を使用したトレースと OTLP を使用したレポートには、次の依存関係が必要です。

  • io.micrometer:micrometer-tracing-bridge-otel - Micrometer Observation API を OpenTelemetry にブリッジします。

  • io.opentelemetry:opentelemetry-exporter-otlp - OTLP を受け入れることができるコレクターにトレースを報告します。

management.otlp.tracing.* 構成プロパティを使用して、OTLP を使用したレポートを構成します。

8.4.4. OpenZipkin Brave と Zipkin

OpenZipkin Brave を使用したトレースと Zipkin へのレポートには、次の依存関係が必要です。

  • io.micrometer:micrometer-tracing-bridge-brave - Micrometer Observation API を Brave にブリッジします。

  • io.zipkin.reporter2:zipkin-reporter-brave - トレースを Zipkin に報告します。

プロジェクトで Spring MVC または Spring WebFlux を使用しない場合は、io.zipkin.reporter2:zipkin-sender-urlconnection 依存関係も必要です。

management.zipkin.tracing.* 構成プロパティを使用して、Zipkin へのレポートを構成します。

8.4.5. OpenZipkin Brave と Wavefront

OpenZipkin Brave を使用したトレースと Wavefront へのレポートには、次の依存関係が必要です。

  • io.micrometer:micrometer-tracing-bridge-brave - Micrometer Observation API を Brave にブリッジします。

  • io.micrometer:micrometer-tracing-reporter-wavefront - トレースを Wavefront に報告します。

management.wavefront.* 構成プロパティを使用して、Wavefront へのレポートを構成します。

8.5. Micrometer Observation との統合

TracingAwareMeterObservationHandler は ObservationRegistry に自動的に登録され、完了した観測ごとにスパンが作成されます。

8.6. カスタムスパンの作成

観測を開始することで、独自のスパンを作成できます。このために、コンポーネントに ObservationRegistry を注入します。

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
class CustomObservation {

    private final ObservationRegistry observationRegistry;

    CustomObservation(ObservationRegistry observationRegistry) {
        this.observationRegistry = observationRegistry;
    }

    void someOperation() {
        Observation observation = Observation.createNotStarted("some-operation", this.observationRegistry);
        observation.lowCardinalityKeyValue("some-tag", "some-value");
        observation.observe(() -> {
            // Business logic ...
        });
    }

}

これにより、タグ "some-tag=some-value" を持つ "some-operation" という名前の観測が作成されます。

メトリクスを作成せずにスパンを作成する場合は、Micrometer の下位レベルの Tracer API (英語) を使用する必要があります。

8.7. バゲッジ

Tracer API を使用してバゲッジを作成できます。

import io.micrometer.tracing.BaggageInScope;
import io.micrometer.tracing.Tracer;

import org.springframework.stereotype.Component;

@Component
class CreatingBaggage {

    private final Tracer tracer;

    CreatingBaggage(Tracer tracer) {
        this.tracer = tracer;
    }

    void doSomething() {
        try (BaggageInScope scope = this.tracer.createBaggageInScope("baggage1", "value1")) {
            // Business logic
        }
    }

}

この例では、値 value1 を持つ baggage1 という名前のバゲッジを作成します。W3C 伝播を使用している場合、バゲッジはネットワーク上で自動的に伝播されます。B3 伝播を使用している場合、バゲッジは自動的には伝播されません。ネットワーク上でバゲージを手動で伝播するには、management.tracing.baggage.remote-fields 構成プロパティを使用します (これは W3C にも機能します)。上の例では、このプロパティを baggage1 に設定すると、HTTP ヘッダー baggage1: value1 が生成されます。

バゲージを MDC に伝播する場合は、management.tracing.baggage.correlation.fields 構成プロパティを使用します。上の例では、このプロパティを baggage1 に設定すると、baggage1 という名前の MDC エントリが作成されます。

9. 監査

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

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

9.1. カスタム監査

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

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

10. HTTP 交換の記録

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

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

10.1. カスタム HTTP 交換記録

記録された各交換に含まれる項目をカスタマイズするには、management.httpexchanges.recording.include 構成プロパティを使用します。

再コーディングを完全に無効にするには、management.httpexchanges.recording.enabled を false に設定します。

11. プロセス監視

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

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

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

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

11.1. 設定の拡張

META-INF/spring.factories ファイルでは、PID ファイルを書き込む 1 つまたは複数のリスナーをアクティブ化できます。

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

11.2. プログラムによるプロセス監視の有効化

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

12. Cloud Foundry サポート

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

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

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

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

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

Properties
management.cloudfoundry.enabled=false
Yaml
management:
  cloudfoundry:
    enabled: false

12.2. Cloud Foundry 自己署名証明書

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

Properties
management.cloudfoundry.skip-ssl-validation=true
Yaml
management:
  cloudfoundry:
    skip-ssl-validation: true

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

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

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

Java
import java.io.IOException;
import java.util.Collections;

import jakarta.servlet.GenericServlet;
import jakarta.servlet.Servlet;
import jakarta.servlet.ServletContainerInitializer;
import jakarta.servlet.ServletContext;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import org.apache.catalina.Host;
import org.apache.catalina.core.StandardContext;
import org.apache.catalina.startup.Tomcat;

import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.servlet.ServletContextInitializer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyCloudFoundryConfiguration {

    @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 (classes, 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("/*");
        };
    }

}
Kotlin
import jakarta.servlet.GenericServlet
import jakarta.servlet.Servlet
import jakarta.servlet.ServletContainerInitializer
import jakarta.servlet.ServletContext
import jakarta.servlet.ServletException
import jakarta.servlet.ServletRequest
import jakarta.servlet.ServletResponse
import org.apache.catalina.Host
import org.apache.catalina.core.StandardContext
import org.apache.catalina.startup.Tomcat.FixContextListener
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory
import org.springframework.boot.web.servlet.ServletContextInitializer
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import java.io.IOException
import java.util.Collections.emptySet

@Configuration(proxyBeanMethods = false)
class MyCloudFoundryConfiguration {

    @Bean
    fun servletWebServerFactory(): TomcatServletWebServerFactory {
        return object : TomcatServletWebServerFactory() {

            override fun prepareContext(host: Host, initializers: Array<ServletContextInitializer>) {
                super.prepareContext(host, initializers)
                val child = StandardContext()
                child.addLifecycleListener(FixContextListener())
                child.path = "/cloudfoundryapplication"
                val initializer = getServletContextInitializer(contextPath)
                child.addServletContainerInitializer(initializer, emptySet())
                child.crossContext = true
                host.addChild(child)
            }

        }
    }

    private fun getServletContextInitializer(contextPath: String): ServletContainerInitializer {
        return ServletContainerInitializer { classes: Set<Class<*>?>?, context: ServletContext ->
            val servlet: Servlet = object : GenericServlet() {

                @Throws(ServletException::class, IOException::class)
                override fun service(req: ServletRequest, res: ServletResponse) {
                    val servletContext = req.servletContext.getContext(contextPath)
                    servletContext.getRequestDispatcher("/cloudfoundryapplication").forward(req, res)
                }

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

13. 次のステップ

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

それ以外の場合は、「デプロイオプション」について読み続けるか、Spring Boot のビルドツールプラグインに関する詳細な情報を先に参照してください。