エンドポイント

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

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

Actuator のエンドポイントとそのリクエストおよびレスポンスの形式の詳細については、"API ドキュメント" を参照してください。

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

ID 説明

auditevents

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

beans

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

caches

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

conditions

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

configprops

サニタイズするすべての @ConfigurationProperties (Javadoc) . サブジェクトの照合リストを表示します。

env

Spring の ConfigurableEnvironment (Javadoc) . サブジェクトのプロパティをサニタイズに公開します。

flyway

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

health

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

httpexchanges

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

info

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

integrationgraph

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

loggers

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

liquibase

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

metrics

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

mappings

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

quartz

Quartz スケジューラージョブに関する情報を表示します。サブジェクトをサニタイズします。

scheduledtasks

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

sessions

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

shutdown

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

startup

ApplicationStartup (Javadoc) によって収集された起動手順データを表示します。SpringApplication (Javadoc) を BufferingApplicationStartup (Javadoc) とともに構成する必要があります。

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 への依存が必要です。

エンドポイントへのアクセスの制御

デフォルトでは、shutdown を除くすべてのエンドポイントへのアクセスは制限されません。エンドポイントへの許可されたアクセスを構成するには、その management.endpoint.<id>.access プロパティを使用します。次の例では、shutdown エンドポイントへの無制限のアクセスを許可します。

  • プロパティ

  • YAML

management.endpoint.shutdown.access=unrestricted
management:
  endpoint:
    shutdown:
      access: unrestricted

アクセスをオプトアウトではなくオプトインにしたい場合は、management.endpoints.access.default プロパティを none に設定し、個々のエンドポイント access プロパティを使用してオプトインに戻します。次の例では、loggers エンドポイントへの読み取り専用アクセスを許可し、他のすべてのエンドポイントへのアクセスを拒否します。

  • プロパティ

  • YAML

management.endpoints.access.default=none
management.endpoint.loggers.access=read-only
management:
  endpoints:
    access:
      default: none
  endpoint:
    loggers:
      access: read-only
アクセスできないエンドポイントは、アプリケーションコンテキストから完全に削除されます。エンドポイントが公開されるテクノロジのみを変更する場合は、代わりに include および exclude プロパティを使用します。

アクセス制限

アプリケーション全体のエンドポイントアクセスは、management.endpoints.access.max-permitted プロパティを使用して制限できます。このプロパティは、既定のアクセスまたは個々のエンドポイントのアクセスレベルよりも優先されます。すべてのエンドポイントにアクセスできないようにするには、none に設定します。エンドポイントへの読み取りアクセスのみを許可するには、read-only に設定します。

@Endpoint (Javadoc) 、@JmxEndpoint (Javadoc) 、@WebEndpoint (Javadoc) の場合、読み取りアクセスは、@ReadOperation (Javadoc) でアノテーションが付けられたエンドポイントメソッドに相当します。@ControllerEndpoint (Javadoc) および @RestControllerEndpoint (Javadoc) の場合、読み取りアクセスは、GET および HEAD リクエストを処理できるリクエストマッピングに相当します。@ServletEndpoint (Javadoc) の場合、読み取りアクセスは、GET および HEAD リクエストに相当します。

エンドポイントの公開

デフォルトでは、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 エンドポイントのみを公開するには、次のプロパティを使用します。

  • プロパティ

  • YAML

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

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

  • プロパティ

  • YAML

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

セキュリティ

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

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

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

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

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

  • Java

  • 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;

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();
	}

}
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 (Javadoc) では、他のいくつかのマッチャーメソッドも使用できます。詳細については、API ドキュメントを参照してください。

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

  • プロパティ

  • YAML

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

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

  • Java

  • 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)
public class MySecurityConfiguration {

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

}
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 (Javadoc) Bean が存在すると完全に無効になるため、アプリケーションの残りの部分に適用されるルールを使用して追加の SecurityFilterChain (Javadoc) Bean を構成する必要があります。

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

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

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

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

エンドポイントの構成

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

  • プロパティ

  • YAML

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

機密値を無害化する

/env、/configprops、/quartz エンドポイントによって返される情報は機密性が高い場合があるため、デフォルト値は常に完全にサニタイズされます ( ****** に置き換えられます)。

値は、次の場合にのみ、サニタイズされていない形式で表示できます。

  • show-values プロパティが never 以外に設定されています

  • カスタム SanitizingFunction Bean は適用されません

show-values プロパティは、サニタイズ可能なエンドポイントに対して次のいずれかの値に構成できます。

  • never - 値は常に完全にサニタイズされます (****** に置き換えられました)

  • always - 値はすべてのユーザーに表示されます (SanitizingFunction (Javadoc) Bean が適用されない限り)

  • when-authorized - 値は認可されたユーザーにのみ表示されます (SanitizingFunction (Javadoc) Bean が適用されない限り)

HTTP エンドポイントの場合、ユーザーは認証されており、エンドポイントのロールプロパティによってロールが構成されている場合、承認されているとみなされます。デフォルトでは、認証されたユーザーはすべて認可されます。

JMX エンドポイントの場合、すべてのユーザーが常に認可されます。

次の例では、admin ロールを持つすべてのユーザーが、/env エンドポイントからの値を元の形式で表示できるようにします。権限のないユーザー、または admin ロールを持たないユーザーには、サニタイズされた値のみが表示されます。

  • プロパティ

  • YAML

management.endpoint.env.show-values=when-authorized
management.endpoint.env.roles=admin
management:
  endpoint:
    env:
      show-values: when-authorized
      roles: "admin"
この例では、SanitizingFunction Bean が定義されていないことを前提としています。

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

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

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

  • プロパティ

  • YAML

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

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

CORS サポート

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

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

  • プロパティ

  • YAML

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

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

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

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

  • Java

  • Kotlin

	@ReadOperation
	public CustomData getData() {
		return new CustomData("test", 5);
	}
	@ReadOperation
	fun getData(): CustomData {
		return CustomData("test", 5)
	}

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

@EndpointWebExtension (Javadoc) と @EndpointJmxExtension (Javadoc) を使用して、テクノロジ固有の拡張機能を記述できます。これらのアノテーションを使用すると、既存のエンドポイントを拡張するためのテクノロジ固有の操作を提供できます。

最後に、Web フレームワーク固有の機能にアクセスする必要がある場合は、JMX 経由または別の Web フレームワークを使用する場合には利用できないというデメリットはありますが、サーブレットまたは Spring、@Controller (Javadoc) 、@RestController (Javadoc) エンドポイントを実装できます。

入力を受け取る

エンドポイントの操作は、パラメーターを通じて入力を受け取ります。Web 上で公開される場合、これらのパラメーターの値は URL のクエリパラメーターと JSON リクエスト本文から取得されます。JMX 上で公開される場合、パラメーターは MBean の操作のパラメーターにマップされます。パラメーターはデフォルトで必須です。パラメーターに @javax.annotation.Nullable または @Nullable (Javadoc) のアノテーションを付けることで、オプションにすることができます。

JSON リクエスト本文の各ルートプロパティをエンドポイントのパラメーターにマップできます。次の JSON リクエスト本文について考えてみます。

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

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

  • Java

  • Kotlin

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

入力型変換

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

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

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

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

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

パス

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

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

HTTP メソッド

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

操作 HTTP メソッド

@ReadOperation (Javadoc)

GET

@WriteOperation (Javadoc)

POST

@DeleteOperation (Javadoc)

DELETE

消費する

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

生産する

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

操作メソッドが void または Void (標準 Javadoc) を返す場合、produces 句は空になります。操作メソッドが Resource (Javadoc) を返す場合、produces 句は application/octet-stream になります。その他のすべての操作の場合、produces 句は application/vnd.spring-boot.actuator.v2+json, application/json になります。

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

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

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

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

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

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

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

Jersey を使用する場合、範囲リクエストはサポートされていません。

Web エンドポイントセキュリティ

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

ヘルス情報

ヘルス情報を使用して、実行中のアプリケーションのステータスを確認できます。これは、本番システムがダウンしたときに誰かに警告するために監視ソフトウェアによってよく使用されます。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 (Javadoc) のコンテンツから収集されます (デフォルトでは、ApplicationContext (Javadoc) で定義されているすべての HealthContributor (Javadoc) インスタンス)。Spring Boot には、自動構成された HealthContributor (Javadoc) Bean が多数含まれており、独自の Bean を作成することもできます。

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

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

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

自動構成された HealthIndicators

適切な場合、Spring Boot は次の表にリストされている HealthIndicator (Javadoc) Bean を自動構成します。また、次の表にリストされている key を使用して management.health.key.enabled を構成することで、選択したインジケーターを有効または無効にすることもできます。

キー 名前 説明

cassandra

CassandraDriverHealthIndicator (Javadoc)

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

couchbase

CouchbaseHealthIndicator (Javadoc)

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

db

DataSourceHealthIndicator (Javadoc)

DataSource (標準 Javadoc) への接続が取得できるかどうかを確認します。

diskspace

DiskSpaceHealthIndicator (Javadoc)

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

elasticsearch

ElasticsearchRestClientHealthIndicator (Javadoc)

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

hazelcast

HazelcastHealthIndicator (Javadoc)

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

jms

JmsHealthIndicator (Javadoc)

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

ldap

LdapHealthIndicator (Javadoc)

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

mail

MailHealthIndicator (Javadoc)

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

mongo

MongoHealthIndicator (Javadoc)

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

neo4j

Neo4jHealthIndicator (Javadoc)

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

ping

PingHealthIndicator (Javadoc)

常に UP で応答します。

rabbit

RabbitHealthIndicator (Javadoc)

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

redis

RedisHealthIndicator (Javadoc)

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

ssl

SslHealthIndicator (Javadoc)

SSL 証明書が正常であることを確認します。

management.health.defaults.enabled プロパティを設定することにより、すべて無効にできます。
ssl HealthIndicator (Javadoc) には、management.health.ssl.certificate-validity-warning-threshold という「警告しきい値」プロパティがあります。このしきい値で定義された時間内に SSL 証明書が無効になると、HealthIndicator (Javadoc) は警告しますが、アプリケーションを中断しないように HTTP 200 を返します。このしきい値を使用して、期限切れが近づいている証明書をローテーションするのに十分なリードタイムを確保できます。

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

キー 名前 説明

livenessstate

LivenessStateHealthIndicator (Javadoc)

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

readinessstate

ReadinessStateHealthIndicator (Javadoc)

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

カスタム HealthIndicators の作成

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

  • Java

  • Kotlin

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 ...
	}

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

Spring Boot の定義済み Status (Javadoc) 型に加えて、Health (Javadoc) は新しいシステム状態を表すカスタム Status (Javadoc) を返すことができます。このような場合、StatusAggregator (Javadoc) インターフェースのカスタム実装も提供するか、management.endpoint.health.status.order 構成プロパティを使用して既定の実装を構成する必要があります。

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

  • プロパティ

  • YAML

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

  • プロパティ

  • YAML

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
management:
  endpoint:
    health:
      status:
        http-mapping:
          down: 503
          fatal: 503
          out-of-service: 503
さらに制御が必要な場合は、独自の HttpCodeStatusMapper (Javadoc) Bean を定義できます。

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

ステータス マッピング

DOWN

SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

SERVICE_UNAVAILABLE (503)

UP

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

UNKNOWN

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

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

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

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

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

  • Java

  • Kotlin

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 ...
	}

}
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 (Javadoc) から拡張することを検討してください。

自動構成された ReactiveHealthIndicators

適切な場合、Spring Boot は次の ReactiveHealthIndicator (Javadoc) Bean を自動構成します。

キー 名前 説明

cassandra

CassandraDriverReactiveHealthIndicator (Javadoc)

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

couchbase

CouchbaseReactiveHealthIndicator (Javadoc)

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

elasticsearch

ElasticsearchReactiveHealthIndicator (Javadoc)

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

mongo

MongoReactiveHealthIndicator (Javadoc)

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

neo4j

Neo4jReactiveHealthIndicator (Javadoc)

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

redis

RedisReactiveHealthIndicator (Javadoc)

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

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

ヘルスグループ

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

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

  • プロパティ

  • YAML

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

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

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

  • プロパティ

  • YAML

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

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

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

  • プロパティ

  • YAML

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

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

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

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

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

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

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

DataSource ヘルス

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

Kubernetes プローブ

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

デフォルトでは、Spring Boot がアプリケーションの可用性の状態を管理します。Kubernetes 環境にデプロイされている場合、アクチュエーターは ApplicationAvailability (Javadoc) インターフェースから "Liveness" および "Readiness" 情報を収集し、その情報を専用のヘルスインジケーターである LivenessStateHealthIndicator (Javadoc) および ReadinessStateHealthIndicator (Javadoc) で使用します。これらのインジケーターは、グローバルヘルスエンドポイント ("/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 プロパティを使用してカスタマイズできます。詳細については、ヘルスグループを参照してください。

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

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

  • プロパティ

  • YAML

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

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

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

"readiness" プローブに関しては、アプリケーション開発者は外部システムをチェックする選択を慎重に行う必要があります。このため、Spring Boot には Readiness Probe に追加のヘルスチェックが含まれていません。アプリケーションインスタンスの準備状態が準備完了でない場合、Kubernetes はトラフィックをそのインスタンスにルーティングしません。一部の外部システムはアプリケーションインスタンスによって共有されない場合があります。その場合は、readiness プローブに含めることができます。他の外部システムはアプリケーションにとって必須ではない可能性があります (アプリケーションにはサーキットブレーカーやフォールバックがある可能性があります)。その場合、絶対に含めるべきではありません。残念ながら、すべてのアプリケーションインスタンスで共有される外部システムが一般的であるため、それを Readiness Probe に含めて、外部サービスがダウンしたときにアプリケーションがサービスから外されることを期待するか、外部サービスを除外するかを判断する必要があります。そして、おそらく呼び出し側でサーキットブレーカーを使用して、スタックの上位で障害に対処します。

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

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

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

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

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

次の表は、さまざまな段階での AvailabilityState (Javadoc) と 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 コンテナーライフサイクルを参照してください。

アプリケーション情報

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

自動構成された InfoContributors

適切な場合、Spring は次の InfoContributor (Javadoc) Bean を自動構成します。

ID 名前 説明 前提条件

build

BuildInfoContributor (Javadoc)

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

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

env

EnvironmentInfoContributor (Javadoc)

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

なし。

git

GitInfoContributor (Javadoc)

git 情報を公開します。

git.properties リソース。

java

JavaInfoContributor (Javadoc)

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

なし。

os

OsInfoContributor (Javadoc)

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

なし。

process

ProcessInfoContributor (Javadoc)

プロセス情報を公開します。

なし。

ssl

SslInfoContributor (Javadoc)

SSL 証明書情報を公開します。

SSL バンドルが構成されました。

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

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

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

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

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

  • プロパティ

  • YAML

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

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

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

  • プロパティ

  • YAML

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

Git コミット情報

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

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

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

  • プロパティ

  • YAML

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

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

  • プロパティ

  • YAML

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

ビルド情報

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

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

Java 情報

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

OS 情報

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

プロセス情報

info エンドポイントはプロセスに関する情報を公開します。詳細については、ProcessInfo (Javadoc) を参照してください。

SSL 情報

info エンドポイントは、SSL 証明書 (SSL バンドルを通じて構成される) に関する情報を公開します。詳細については、SslInfo (Javadoc) を参照してください。このエンドポイントは、SslHealthIndicator (Javadoc) の「警告しきい値」プロパティを再利用します。このしきい値で定義された時間枠内に SSL 証明書が無効になると、警告がトリガーされます。management.health.ssl.certificate-validity-warning-threshold プロパティを参照してください。

カスタム InfoContributors の作成

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

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

  • Java

  • Kotlin

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"));
	}

}
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"
	}
}

ソフトウェア部品表 (SBOM)

sbom エンドポイントはソフトウェア部品表 [Wikipedia] (英語) を公開します。CycloneDX SBOM は自動検出できますが、他の形式も手動で構成できます。

sbom アクチュエーターエンドポイントは、アプリケーションの内容を記述する「アプリケーション」と呼ばれる SBOM を公開します。

プロジェクトのビルド時に CycloneDX SBOM を自動的に生成するには、CycloneDX SBOM を生成するセクションを参照してください。

その他の SBOM 形式

SBOM を別の形式で公開する場合は、使用できる構成プロパティがいくつかあります。

構成プロパティ management.endpoint.sbom.application.location は、アプリケーション SBOM の場所を設定します。例: これを classpath:sbom.json に設定すると、クラスパス上の /sbom.json リソースの内容が使用されます。

CycloneDX、SPDX、Syft 形式の SBOM のメディア型は自動的に検出されます。自動検出されたメディア型をオーバーライドするには、構成プロパティ management.endpoint.sbom.application.media-type を使用します。

追加の SBOM

アクチュエーターエンドポイントは複数の SBOM を処理できます。SBOM を追加するには、次の例に示すように、構成プロパティ management.endpoint.sbom.additional を使用します。

  • プロパティ

  • YAML

management.endpoint.sbom.additional.system.location=optional:file:/system.spdx.json
management.endpoint.sbom.additional.system.media-type=application/spdx+json
management:
  endpoint:
    sbom:
      additional:
        system:
          location: "optional:file:/system.spdx.json"
          media-type: "application/spdx+json"

これにより、"system" と呼ばれる SBOM が追加され、/system.spdx.json に保存されます。optional: プレフィックスを使用すると、ファイルが存在しない場合に起動エラーを防ぐことができます。