エンドポイント

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

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

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

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

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

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

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

  • プロパティ

  • YAML

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

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

  • プロパティ

  • YAML

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

エンドポイントの公開

デフォルトでは、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 Bean を登録できます。

セキュリティ

セキュリティ上の理由から、デフォルトでは /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

  • 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 では、他のいくつかのマッチャーメソッドも利用できます。詳細は 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 Bean が存在する場合は完全にバックオフするため、アプリケーションの残りの部分に適用されるルールを使用して、追加の SecurityFilterChain 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 Bean が適用されない限り)

  • WHEN_AUTHORIZED - 値は認可されたユーザーにのみ表示されます (SanitizingFunction 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 アノテーションが付けられた @Bean を追加すると、@ReadOperation、@WriteOperation、@DeleteOperation アノテーションが付けられたメソッドはすべて、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 または @WebEndpoint を使用して、テクノロジー固有のエンドポイントを作成することもできます。これらのエンドポイントは、それぞれのテクノロジーに制限されています。例: @WebEndpoint は HTTP でのみ公開され、JMX では公開されません。

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

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

入力を受け取る

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

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 コードを -java-parameters でコンパイルする必要があります。これは、Spring Boot の Gradle プラグインを使用する場合、または Maven と spring-boot-starter-parent を使用する場合に自動的に発生します。

入力型変換

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

カスタム 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 フラックスを使用する場合、org.springframework.core.io.Resource を返す操作は自動的に範囲リクエストをサポートします。

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

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

Web エンドポイントまたは Web 固有のエンドポイント拡張での操作は、メソッドパラメーターとして現在の java.security.Principal または org.springframework.boot.actuate.endpoint.SecurityContext を受け取ることができます。前者は通常、@Nullable と組み合わせて使用され、認証されたユーザーと認証されていないユーザーに異なる動作を提供します。後者は通常、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 で定義されているすべての HealthContributor (Javadoc) インスタンス）。Spring Boot には、自動構成された HealthContributors が多数含まれており、独自に作成することもできます。

HealthContributor は、HealthIndicator または CompositeHealthContributor のいずれかです。HealthIndicator は、Status を含む実際のヘルス情報を提供します。CompositeHealthContributor は、他の HealthContributors のコンポジットを提供します。一緒に取られて、コントリビューターは全体的なシステムのヘルスを表すためにツリー構造を形成します。

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

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

自動構成された HealthIndicators

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

キー 名前 説明

cassandra

CassandraDriverHealthIndicator (Javadoc)

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

couchbase

CouchbaseHealthIndicator (Javadoc)

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

db

DataSourceHealthIndicator (Javadoc)

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

diskspace

DiskSpaceHealthIndicator (Javadoc)

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

elasticsearch

ElasticsearchRestClientHealthIndicator (Javadoc)

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

hazelcast

HazelcastHealthIndicator (Javadoc)

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

influxdb

InfluxDbHealthIndicator (Javadoc)

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

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

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

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

キー 名前 説明

livenessstate

LivenessStateHealthIndicator (Javadoc)

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

readinessstate

ReadinessStateHealthIndicator (Javadoc)

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

カスタム HealthIndicators の作成

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

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

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

例: FATAL のコードを持つ新しい Status が HealthIndicator 実装の 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 Bean を定義できます。

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

ステータス マッピング

DOWN

SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

SERVICE_UNAVAILABLE (503)

UP

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

UNKNOWN

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

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

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

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

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

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

自動構成された ReactiveHealthIndicators

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

キー 名前 説明

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 は自動的にラップされます。

ヘルスグループ

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

ヘルスインジケーターグループを作成するには、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 および HttpCodeStatusMapper 設定を継承します。ただし、これらをグループごとに定義することもできます。必要に応じて、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 または 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: （構成されている場合は管理ポートを表す）のいずれかである必要があります。パスは単一のパスセグメントである必要があります。

DataSource ヘルス

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

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 プロパティを使用してカスタマイズできます。詳細については、ヘルスグループを参照してください。

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 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 コンテナーのライフサイクルセクションを参照してください。

アプリケーション情報

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

自動構成された InfoContributors

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

ID 名前 説明 前提条件

build

BuildInfoContributor (Javadoc)

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

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

env

EnvironmentInfoContributor (Javadoc)

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

なし。

git

GitInfoContributor (Javadoc)

git 情報を公開します。

git.properties リソース。

java

JavaInfoContributor (Javadoc)

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

なし。

os

OsInfoContributor (Javadoc)

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

なし。

process

ProcessInfoContributor (Javadoc)

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

なし。

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

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

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

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

env コントリビューターが有効になっている場合、info.* Spring プロパティを設定することにより、info エンドポイントによって公開されるデータをカスタマイズできます。info キーにあるすべての Environment プロパティは自動的に公開されます。例: 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 Bean が使用可能な場合は、info エンドポイントを使用してこれらのプロパティを公開できます。

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

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

Java 情報

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

OS 情報

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

プロセス情報

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

カスタム 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 は自動検出できますが、他の形式も手動で構成できます。

spring-boot-starter-parent Maven 親と Spring Boot Gradle プラグインはそれぞれ CycloneDX Maven プラグイン [GitHub] (英語) と CycloneDX Gradle プラグイン [GitHub] (英語) を構成します。

CycloneDX SBOM を入手するには、Maven ビルドに以下を追加する必要があります。

<build>
    <plugins>
        <plugin>
            <groupId>org.cyclonedx</groupId>
            <artifactId>cyclonedx-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Gradle の場合は、CycloneDX Gradle プラグインを適用する必要があります。

plugins {
    id 'org.cyclonedx.bom' version '1.8.2'
}

sbom アクチュエーターエンドポイントは、アプリケーションの内容を記述する「アプリケーション」と呼ばれる 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: プレフィックスを使用すると、ファイルが存在しない場合に起動エラーを防ぐことができます。