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 にマップされます。
次のテクノロジーに依存しないエンドポイントが利用可能です。
| ID | 説明 |
|---|---|
| 現在のアプリケーションの監査イベント情報を公開します。 |
| アプリケーション内のすべての Spring Bean の完全なリストを表示します。 |
| 利用可能なキャッシュを公開します。 |
| 構成クラスおよび自動構成クラスで評価された条件と、それらが一致したまたは一致しなかった理由を示します。 |
| すべての |
| Spring の |
| 適用された Flyway データベースの移行を表示します。1 つ以上の |
| アプリケーションの正常性情報を表示します。 |
| HTTP トレース情報（デフォルトでは、最後の 100 の HTTP リクエスト / レスポンス交換）を表示します。 |
| 任意のアプリケーション情報を表示します。 |
| Spring Integration グラフを表示します。 |
| アプリケーションのロガーの構成を表示および変更します。 |
| 適用された Liquibase データベースの移行を表示します。1 つ以上の |
| 現在のアプリケーションの「メトリクス」情報を表示します。 |
| すべての |
| Quartz スケジューラジョブに関する情報を表示します。 |
| アプリケーションのスケジュールされたタスクを表示します。 |
| Spring セッションによるセッションストアからのユーザーセッションの取得と削除を許可します。Spring Session を使用するサーブレットベースの Web アプリケーションが必要です。 |
| アプリケーションを正常にシャットダウンできるようにします。jar パッケージを使用している場合にのみ機能します。デフォルトでは無効です。 |
|
|
| スレッドダンプを実行します。 |
アプリケーションが Web アプリケーション (Spring MVC、Spring WebFlux、または Jersey) の場合、次の追加のエンドポイントを使用できます。
| ID | 説明 |
|---|---|
| ヒープダンプファイルを返します。HotSpot JVM では、 |
| Jolokia がクラスパス上にある場合（WebFlux では使用不可）、HTTP を介して JMXBean を公開します。 |
| ログファイルの内容を返します（ |
| Prometheus サーバーによってスクレイピング可能な形式でメトリクスを公開します。 |
2.1. エンドポイントを有効にする
デフォルトでは、shutdown を除くすべてのエンドポイントが有効になっています。エンドポイントの有効化を構成するには、management.endpoint.<id>.enabled プロパティを使用します。次の例では、shutdown エンドポイントを有効にします。
management.endpoint.shutdown.enabled=truemanagement:
endpoint:
shutdown:
enabled: true エンドポイントの有効化をオプトアウトではなくオプトインにしたい場合は、management.endpoints.enabled-by-default プロパティを false に設定し、個々のエンドポイント enabled プロパティを使用してオプトインします。次の例では、info エンドポイントを有効にし、他のすべてのエンドポイントを無効にします。
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=truemanagement:
endpoints:
enabled-by-default: false
endpoint:
info:
enabled: true 無効なエンドポイントは、アプリケーションコンテキストから完全に削除されます。エンドポイントが公開されているテクノロジーのみを変更する場合は、代わりに include および exclude プロパティを使用してください。 |
2.2. エンドポイントの公開
エンドポイントには機密情報が含まれている可能性があるため、エンドポイントをいつ公開するかを慎重に検討する必要があります。次の表は、組み込みエンドポイントのデフォルトの露出を示しています。
| ID | JMX | Web |
|---|---|---|
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | はい |
| なし | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| なし | いいえ |
| なし | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| なし | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
| はい | いいえ |
公開するエンドポイントを変更するには、次のテクノロジー固有の include および exclude プロパティを使用します。
| プロパティ | デフォルト |
|---|---|
| |
|
|
| |
|
|
include プロパティは、公開されているエンドポイントの ID を一覧表示します。exclude プロパティは、公開してはならないエンドポイントの ID を一覧表示します。exclude プロパティは、include プロパティよりも優先されます。エンドポイント ID のリストを使用して、include プロパティと exclude プロパティの両方を構成できます。
例: JMX を介したすべてのエンドポイントの公開を停止し、health および info エンドポイントのみを公開するには、次のプロパティを使用します。
management.endpoints.jmx.exposure.include=health,infomanagement:
endpoints:
jmx:
exposure:
include: "health,info"* を使用して、すべてのエンドポイントを選択できます。例: env および beans エンドポイント以外のすべてを HTTP で公開するには、次のプロパティを使用します。
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beansmanagement:
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 がクラスパス上にあり、他の WebSecurityConfigurerAdapter または SecurityFilterChain Bean が存在しない場合、/health 以外のすべてのアクチュエーターは Spring Boot 自動構成によって保護されます。カスタム WebSecurityConfigurerAdapter または SecurityFilterChain Bean を定義すると、Spring Boot 自動構成がバックオフし、アクチュエーターのアクセス規則を完全に制御できるようになります。
HTTP エンドポイントのカスタムセキュリティを構成する場合（たとえば、特定のロールを持つユーザーのみにアクセスを許可する場合）、Spring Boot は、Spring Security と組み合わせて使用できる便利な RequestMatcher オブジェクトをいくつか提供します。
典型的な Spring Security 構成は、次の例のようになります。
@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint());
http.authorizeRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
http.httpBasic(withDefaults());
return http.build();
}
}
@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests { requests ->
requests.anyRequest().hasRole("ENDPOINT_ADMIN")
}
http.httpBasic()
return http.build()
}
}
上記の例では、EndpointRequest.toAnyEndpoint() を使用してリクエストを任意のエンドポイントに一致させ、すべてが ENDPOINT_ADMIN のロールを持つようにします。EndpointRequest では、他のいくつかのマッチャーメソッドも利用できます。詳細については、API ドキュメント（HTML (英語) または PDF (英語) ）を参照してください。
ファイアウォールの背後にアプリケーションをデプロイする場合、認証を必要とせずにすべてのアクチュエーターエンドポイントにアクセスできるようにすることができます。これを行うには、次のように management.endpoints.web.exposure.include プロパティを変更します。
management.endpoints.web.exposure.include=*management:
endpoints:
web:
exposure:
include: "*"さらに、Spring Security が存在する場合は、次の例に示すように、エンドポイントへの認証されていないアクセスを許可するカスタムセキュリティ構成を追加する必要があります。
@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint());
http.authorizeRequests((requests) -> requests.anyRequest().permitAll());
return http.build();
}
}
@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests {
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 秒に設定します。
management.endpoint.beans.cache.time-to-live=10smanagement:
endpoint:
beans:
cache:
time-to-live: "10s"management.endpoint.<name> プレフィックスは、構成されているエンドポイントを一意に識別します。 |
2.5. アクチュエーター Web エンドポイント用のハイパーメディア
すべてのエンドポイントへのリンクを含む「検出ページ」が追加されます。「ディスカバリページ」は、デフォルトで /actuator で利用可能です。
「検出ページ」を無効にするには、アプリケーションのプロパティに次のプロパティを追加します。
management.endpoints.web.discovery.enabled=falsemanagement:
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 呼び出しが許可されます。
management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POSTmanagement:
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 が使用されます。
次の例では、カスタムオブジェクトを返す読み取り操作を公開しています。
@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 フレームワークを使用している場合に使用できます。
2.7.1. 入力を受け取る
エンドポイントでの操作は、パラメーターを介して入力を受け取ります。Web で公開される場合、これらのパラメーターの値は、URL のクエリパラメーターと JSON リクエスト本文から取得されます。JMX を介して公開されると、パラメーターは MBean の操作のパラメーターにマップされます。デフォルトではパラメーターが必要です。@javax.annotation.Nullable または @org.springframework.lang.Nullable のいずれかでアノテーションを付けることにより、オプションにすることができます。
JSON リクエスト本文の各ルートプロパティをエンドポイントのパラメーターにマップできます。次の JSON リクエスト本文について考えてみます。
{
"name": "test",
"counter": 42
} 次の例に示すように、これを使用して、String name および int counter パラメーターを受け取る書き込み操作を呼び出すことができます。
@WriteOperation
public void 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 を使用する場合に自動的に発生します。 |
2.7.2. カスタム Web エンドポイント
@Endpoint、@WebEndpoint、@EndpointWebExtension の操作は、Jersey、Spring MVC、または Spring WebFlux を使用して HTTP 経由で自動的に公開されます。Jersey と Spring MVC の両方が使用可能な場合は、Spring MVC が使用されます。
パス
述語のパスは、エンドポイントの ID と Web に公開されたエンドポイントのベースパスによって決定されます。デフォルトのベースパスは /actuator です。例: ID が sessions のエンドポイントは、述語のパスとして /actuator/sessions を使用します。
操作メソッドの 1 つ以上のパラメーターに @Selector のアノテーションを付けることにより、パスをさらにカスタマイズできます。このようなパラメーターは、パス変数としてパス述語に追加されます。変数の値は、エンドポイント操作が呼び出されたときに操作メソッドに渡されます。残りのすべてのパス要素をキャプチャーする場合は、最後のパラメーターに @Selector(Match=ALL_REMAINING) を追加して、String[] と変換互換の型にすることができます。
HTTP メソッド
次の表に示すように、述語の HTTP メソッドは操作型によって決定されます。
| 操作 | HTTP メソッド |
|---|---|
|
|
|
|
|
|
消費する
リクエスト本文を使用する @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（間違ったリクエスト）になります。
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 です。ユーザーが 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 データベースが稼働していることを確認します。 | |
| Couchbase クラスターが稼働していることを確認します。 | |
|
| |
| ディスク容量が不足していないか確認します。 | |
| Elasticsearch クラスターが起動していることを確認します。 | |
| Hazelcast サーバーが稼働していることを確認します。 | |
| InfluxDB サーバーが起動していることを確認します。 | |
| JMS ブローカーが起動していることを確認します。 | |
| LDAP サーバーが起動していることを確認します。 | |
| メールサーバーが起動していることを確認します。 | |
| Mongo データベースが稼働していることを確認します。 | |
| Neo4j データベースが稼働していることを確認します。 | |
| 常に | |
| Rabbit サーバーが稼働していることを確認します。 | |
| Redis サーバーが稼働していることを確認します。 | |
| Solr サーバーが稼働していることを確認します。 |
management.health.defaults.enabled プロパティを設定することにより、すべて無効にできます。 |
追加の HealthIndicators が利用可能ですが、デフォルトでは有効になっていません。
| キー | 名前 | 説明 |
|---|---|---|
| 「活性」アプリケーションの可用性状態を公開します。 | |
| 「準備完了」アプリケーションの可用性状態を公開します。 |
2.8.2. カスタム HealthIndicators の作成
カスタムのヘルス情報を提供するために、HealthIndicator [GitHub] (英語) インターフェースを実装する Spring Bean を登録できます。health() メソッドの実装を提供し、Health レスポンスを返す必要があります。Health レスポンスにはステータスが含まれている必要があり、オプションで表示される追加の詳細を含めることができます。次のコードは、サンプルの HealthIndicator 実装を示しています。
@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 ...
}
}
@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 つで使用されていると想定します。重大度の順序を構成するには、アプリケーションのプロパティに次のプロパティを追加します。
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,upmanagement:
endpoint:
health:
status:
order: "fatal,down,out-of-service,unknown,up" レスポンスの HTTP ステータスコードは、全体的なヘルスステータスを反映しています。デフォルトでは、OUT_OF_SERVICE と DOWN は 503 にマップされます。UP を含むマップされていないヘルスステータスは 200 にマップされます。HTTP 経由でヘルスエンドポイントにアクセスする場合は、カスタムステータスマッピングを登録することもできます。カスタムマッピングを構成すると、DOWN および OUT_OF_SERVICE のデフォルトのマッピングが無効になります。デフォルトのマッピングを保持する場合は、カスタムマッピングと一緒に明示的に構成する必要があります。例: 次のプロパティは FATAL を 503（サービスは利用できません）にマップし、DOWN および OUT_OF_SERVICE のデフォルトのマッピングを保持します。
management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503management:
endpoint:
health:
status:
http-mapping:
down: 503
fatal: 503
out-of-service: 503 さらに制御が必要な場合は、独自の HttpCodeStatusMapper Bean を定義できます。 |
次の表に、組み込みステータスのデフォルトのステータスマッピングを示します。
| ステータス | マッピング |
|---|---|
|
|
|
|
| デフォルトではマッピングがないため、HTTP ステータスは |
| デフォルトではマッピングがないため、HTTP ステータスは |
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 実装を示しています。
@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 ...
}
}
@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 データベースが稼働していることを確認します。 | |
| Couchbase クラスターが稼働していることを確認します。 | |
| Elasticsearch クラスターが起動していることを確認します。 | |
| Mongo データベースが稼働していることを確認します。 | |
| Neo4j データベースが稼働していることを確認します。 | |
| Redis サーバーが稼働していることを確認します。 |
必要に応じて、リアクティブインジケータが通常のインジケータを置き換えます。また、明示的に処理されない HealthIndicator は自動的にラップされます。 |
2.8.5. ヘルスグループ
さまざまな目的に使用できるグループにヘルスインジケーターを整理すると便利な場合があります。
ヘルスインジケーターグループを作成するには、management.endpoint.health.group.<name> プロパティを使用して、ヘルスインジケーター ID のリストを include または exclude に指定できます。例: データベースインジケーターのみを含むグループを作成するには、以下を定義できます。
management.endpoint.health.group.custom.include=dbmanagement:
endpoint:
health:
group:
custom:
include: "db"localhost:8080/actuator/health/custom を押すと、結果を確認できます。
同様に、データベースインジケーターをグループから除外し、他のすべてのインジケーターを含むグループを作成するには、以下を定義できます。
management.endpoint.health.group.custom.exclude=dbmanagement:
endpoint:
health:
group:
custom:
exclude: "db" デフォルトでは、グループはシステムヘルスと同じ StatusAggregator および HttpCodeStatusMapper 設定を継承します。ただし、これらをグループごとに定義することもできます。必要に応じて、show-details および roles プロパティをオーバーライドすることもできます。
management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
management.endpoint.health.group.custom.status.order=fatal,up
management.endpoint.health.group.custom.status.http-mapping.fatal=500
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500management:
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.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 これにより、liveness は /livez で使用可能になり、readiness はメインサーバーポートの readyz で使用可能になります。
2.9.1. Kubernetes プローブを使用した外部状態の確認
アクチュエーターは、「活性」および「準備」プローブをヘルスグループとして構成します。これは、すべてのヘルスグループ機能が利用できることを意味します。たとえば、追加のヘルスインジケータを設定できます。
management.endpoint.health.group.readiness.include=readinessState,customCheckmanagement:
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 アプリケーションが起動すると、次のようになります。
| スタートアップフェーズ | LivenessState | ReadinessState | Http サーバー | ノート |
|---|---|---|---|---|
開始 |
|
| 未起動 | Kubernetes は「活性」プローブをチェックし、時間がかかりすぎる場合はアプリケーションを再起動します。 |
起動済み |
|
| リクエストを拒否します | アプリケーションコンテキストがリフレッシュされます。アプリケーションは起動タスクを実行し、まだトラフィックを受信していません。 |
準備完了 |
|
| リクエストを受け付けます | 起動タスクが完了しました。アプリケーションはトラフィックを受信しています。 |
Spring Boot アプリケーションがシャットダウンすると、次のようになります。
| シャットダウンフェーズ | 活性状態 | 準備状態 | Http サーバー | ノート |
|---|---|---|---|---|
実行 |
|
| リクエストを受け付けます | シャットダウンがリクエストされました。 |
正常なシャットダウン |
|
| 新しいリクエストは拒否されます | 有効にすると、正常なシャットダウンが処理中のリクエストを処理します。 |
シャットダウンが完了しました | なし | なし | サーバーがシャットダウンされます | アプリケーションコンテキストが閉じられ、アプリケーションがシャットダウンされます。 |
| Kubernetes デプロイの詳細については、Kubernetes コンテナーのライフサイクルセクションを参照してください。 |
2.10. アプリケーション情報
アプリケーション情報は、ApplicationContext で定義されたすべての InfoContributor [GitHub] (英語) Bean から収集されたさまざまな情報を公開します。Spring Boot には多数の自動構成 InfoContributor Bean が含まれており、独自の Bean を作成できます。
2.10.1. 自動構成された InfoContributors
必要に応じて、Spring は次の InfoContributor Bean を自動構成します。
| ID | 名前 | 説明 | 前提条件 |
|---|---|---|---|
| ビルド情報を公開します。 |
| |
| 名前が | なし。 | |
| git 情報を公開します。 |
| |
| Java ランタイム情報を公開します。 | なし。 | |
| オペレーティングシステム情報を公開します。 | なし。 |
個々のコントリビューターが有効になっているかどうかは、その 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 ファイルに次の設定を追加できます。
info.app.encoding=UTF-8
info.app.java.source=11
info.app.java.target=11info:
app:
encoding: "UTF-8"
java:
source: "11"
target: "11"これらの値をハードコードするのではなく、ビルド時に情報プロパティを展開することもできます。 Maven を使用すると仮定すると、上記の例を次のように書き換えることができます。 Properties Yaml |
2.10.3. Git コミット情報
info エンドポイントのもう 1 つの便利な機能は、プロジェクトがビルドされたときの git ソースコードリポジトリの状態に関する情報を公開する機能です。GitProperties Bean が使用可能な場合は、info エンドポイントを使用してこれらのプロパティを公開できます。
クラスパスのルートで git.properties ファイルが使用可能な場合、GitProperties Bean は自動構成されます。詳細については、「git 情報を生成する方法」を参照してください。 |
デフォルトでは、エンドポイントは git.branch、git.commit.id、git.commit.time プロパティが存在する場合はそれを公開します。エンドポイントレスポンスでこれらのプロパティのいずれも必要としない場合は、git.properties ファイルから除外する必要があります。完全な git 情報（つまり、git.properties の完全なコンテンツ）を表示する場合は、次のように management.info.git.mode プロパティを使用します。
management.info.git.mode=fullmanagement:
info:
git:
mode: "full"info エンドポイントからの gitcommit 情報を完全に無効にするには、次のように management.info.git.enabled プロパティを false に設定します。
management.info.git.enabled=falsemanagement:
info:
git:
enabled: false2.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 エントリを提供します。
@Component
public class MyInfoContributor implements InfoContributor {
@Override
public void contribute(Info.Builder builder) {
builder.withDetail("example", Collections.singletonMap("key", "value"));
}
}
@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 が使用されます。 |
3.1. 管理エンドポイントパスのカスタマイズ
管理エンドポイントのプレフィックスをカスタマイズすると便利な場合があります。例: アプリケーションがすでに別の目的で /actuator を使用している可能性があります。次の例に示すように、management.endpoints.web.base-path プロパティを使用して、管理エンドポイントのプレフィックスを変更できます。
management.endpoints.web.base-path=/managemanagement:
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 に再マッピングします。
management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheckmanagement:
endpoints:
web:
base-path: "/"
path-mapping:
health: "healthcheck"3.2. 管理サーバーポートのカスタマイズ
デフォルトの HTTP ポートを使用して管理エンドポイントを公開することは、クラウドベースのデプロイにとって実用的な選択です。ただし、アプリケーションが独自のデータセンター内で実行される場合は、別の HTTP ポートを使用してエンドポイントを公開することをお勧めします。
次の例に示すように、management.server.port プロパティを設定して HTTP ポートを変更できます。
management.server.port=8081management:
server:
port: 8081| Cloud Foundry では、デフォルトで、アプリケーションは HTTP ルーティングと TCP ルーティングの両方についてポート 8080 でのみリクエストを受信します。Cloud Foundry でカスタム管理ポートを使用する場合は、アプリケーションのルートを明示的に設定して、トラフィックをカスタムポートに転送する必要があります。 |
3.3. 管理固有の SSL の構成
カスタムポートを使用するように構成されている場合は、さまざまな management.server.ssl.* プロパティを使用して、独自の SSL を使用して管理サーバーを構成することもできます。例: 次のプロパティ設定が示すように、そうすることで、メインアプリケーションが HTTPS を使用している間、管理サーバーを HTTP 経由で使用できるようになります。
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:store.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=falseserver:
port: 8443
ssl:
enabled: true
key-store: "classpath:store.jks"
key-password: "secret"
management:
server:
port: 8080
ssl:
enabled: falseまたは、メインサーバーと管理サーバーの両方で SSL を使用できますが、次のようにキーストアが異なります。
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:main.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=true
management.server.ssl.key-store=classpath:management.jks
management.server.ssl.key-password=secretserver:
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 は、リモート管理接続を許可しません。
management.server.port=8081
management.server.address=127.0.0.1management:
server:
port: 8081
address: "127.0.0.1"3.5. HTTP エンドポイントを無効にする
HTTP を介してエンドポイントを公開したくない場合は、次の例に示すように、管理ポートを -1 に設定できます。
management.server.port=-1management:
server:
port: -1 次の例に示すように、management.endpoints.web.exposure.exclude プロパティを使用してこれを実現することもできます。
management.endpoints.web.exposure.exclude=*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 で実行する例を示しています。
spring.jmx.unique-names=true
management.endpoints.jmx.domain=com.example.myappspring:
jmx:
unique-names: true
management:
endpoints:
jmx:
domain: "com.example.myapp"4.2. JMX エンドポイントの無効化
JMX を介してエンドポイントを公開したくない場合は、次の例に示すように、management.endpoints.jmx.exposure.exclude プロパティを * に設定できます。
management.endpoints.jmx.exposure.exclude=*management:
endpoints:
jmx:
exposure:
exclude: "*"4.3. HTTP を介した JMX での Jolokia の使用
Jolokia は、JMX Bean にアクセスする代替方法を提供する JMX-HTTP ブリッジです。Jolokia を使用するには、org.jolokia:jolokia-core への依存関係を含めます。例: Maven では、次の依存関係を追加します。
<dependency>
<groupId>org.jolokia</groupId>
<artifactId>jolokia-core</artifactId>
</dependency> 次に、jolokia または * を management.endpoints.web.exposure.include プロパティに追加することにより、Jolokia エンドポイントを公開できます。その後、管理 HTTP サーバーで /actuator/jolokia を使用してアクセスできます。
| Jolokia エンドポイントは、Jolokia のサーブレットをアクチュエーターエンドポイントとして公開します。その結果、Spring MVC や Jersey などのサーブレット環境に固有のものになります。エンドポイントは、WebFlux アプリケーションでは使用できません。 |
4.3.1. Jolokia のカスタマイズ
Jolokia には、サーブレットパラメーターを設定することによって従来から構成する多くの設定があります。Spring Boot を使用すると、application.properties ファイルを使用できます。これを行うには、次の例に示すように、パラメーターの前に management.endpoint.jolokia.config. を付けます。
management.endpoint.jolokia.config.debug=truemanagement:
endpoint:
jolokia:
config:
debug: true5. ロガー
Spring Boot Actuator には、実行時にアプリケーションのログレベルを表示および構成する機能が含まれています。リスト全体または個々のロガーの設定を表示できます。これは、明示的に設定されたログレベルと、ログフレームワークによって指定された有効なログレベルの両方で構成されます。これらのレベルは次のいずれかです。
TRACEDEBUGINFOWARNERRORFATALOFFnull
null は、明示的な構成がないことを示します。
6. メトリクス
Spring Boot Actuator は、以下を含む多数のモニタリングシステム (英語) をサポートするアプリケーションメトリクスファサードである Micrometer (英語) の依存関係管理と自動構成を提供します。
| Micrometer の機能の詳細については、そのリファレンスドキュメント (英語) 、特に概念のセクションを参照してください (英語) 。 |
6.1. 入門
Spring Boot は、コンポジット MeterRegistry を自動構成し、クラスパスで検出されたサポートされている各実装のレジストリをコンポジットに追加します。Spring Boot がレジストリを設定するには、ランタイムクラスパスで micrometer-registry-{system} に依存していれば十分です。
ほとんどのレジストリは共通の機能を共有しています。たとえば、Micrometer レジストリの実装がクラスパス上にある場合でも、特定のレジストリを無効にすることができます。次の例では、Datadog を無効にします。
management.metrics.export.datadog.enabled=falsemanagement:
metrics:
export:
datadog:
enabled: false次の例に示すように、レジストリ固有のプロパティで特に指定されていない限り、すべてのレジストリを無効にすることもできます。
management.metrics.export.defaults.enabled=falsemanagement:
metrics:
export:
defaults:
enabled: falseSpring Boot は、次のように明示的に指示しない限り、自動構成されたレジストリを Metrics クラスのグローバル静的複合レジストリにも追加します。
management.metrics.use-global-registry=falsemanagement:
metrics:
use-global-registry: false メーターをレジストリに登録する前に、MeterRegistryCustomizer Bean をいくつでも登録して、共通タグの適用など、レジストリをさらに設定できます。
@Configuration(proxyBeanMethods = false)
public class MyMeterRegistryConfiguration {
@Bean
public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {
return (registry) -> registry.config().commonTags("region", "us-east-1");
}
}
@Configuration(proxyBeanMethods = false)
class MyMeterRegistryConfiguration {
@Bean
fun metricsCommonTags(): MeterRegistryCustomizer<MeterRegistry> {
return MeterRegistryCustomizer { registry ->
registry.config().commonTags("region", "us-east-1")
}
}
}
ジェネリクス型をより具体的にすることにより、特定のレジストリ実装にカスタマイズを適用できます。
@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 ...
}
}
@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 は、構成または専用のアノテーションマーカーを介して制御できる組み込みのインストルメンテーションも構成します。
6.2. サポートされている監視システム
このセクションでは、サポートされている各監視システムについて簡単に説明します。
6.2.1. AppOptics
デフォルトでは、AppOptics レジストリは定期的にメトリクスを api.appoptics.com/v1/measurements (英語) にプッシュします。メトリクスを SaaS AppOptics (英語) にエクスポートするには、API トークンを提供する必要があります。
management.metrics.export.appoptics.api-token=YOUR_TOKENmanagement:
metrics:
export:
appoptics:
api-token: "YOUR_TOKEN"6.2.2. Atlas
デフォルトでは、メトリクスはローカルマシンで実行されている Atlas (英語) にエクスポートされます。Atlas サーバー [GitHub] (英語) の場所を指定できます。
management.metrics.export.atlas.uri=https://atlas.example.com:7101/api/v1/publishmanagement:
metrics:
export:
atlas:
uri: "https://atlas.example.com:7101/api/v1/publish"6.2.3. Datadog
Datadog レジストリは定期的にメトリクスを datadoghq (英語) にプッシュします。メトリクスを Datadog (英語) にエクスポートするには、API キーを指定する必要があります。
management.metrics.export.datadog.api-key=YOUR_KEYmanagement:
metrics:
export:
datadog:
api-key: "YOUR_KEY"アプリケーションキー（オプション）を追加で指定すると、メーターの説明、型、ベースユニットなどのメタデータもエクスポートされます。
management.metrics.export.datadog.api-key=YOUR_API_KEY
management.metrics.export.datadog.application-key=YOUR_APPLICATION_KEYmanagement:
metrics:
export:
datadog:
api-key: "YOUR_API_KEY"
application-key: "YOUR_APPLICATION_KEY" デフォルトでは、メトリクスは Datadog US サイト (英語) （api.datadoghq.com (英語) ）に送信されます。Datadog プロジェクトが他のサイトの 1 つでホストされている場合、またはプロキシを介してメトリクスを送信する必要がある場合は、それに応じて URI を構成します。
management.metrics.export.datadog.uri=https://api.datadoghq.eumanagement:
metrics:
export:
datadog:
uri: "https://api.datadoghq.eu"メトリクスが Datadog に送信される間隔を変更することもできます。
management.metrics.export.datadog.step=30smanagement:
metrics:
export:
datadog:
step: "30s"6.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 を使用してメトリクスのエクスポートを構成します。
management.metrics.export.dynatrace.uri=https://example.live.dynatrace.com/api/v2/metrics/ingest
management.metrics.export.dynatrace.api-token=YOUR_TOKENmanagement:
metrics:
export:
dynatrace:
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 トークンを指定しないことは可能です。このシナリオでは、自動的に構成されたエンドポイントが使用されます。
management.metrics.export.dynatrace.v2.metric-key-prefix=your.key.prefix
management.metrics.export.dynatrace.v2.enrich-with-dynatrace-metadata=true
management.metrics.export.dynatrace.v2.default-dimensions.key1=value1
management.metrics.export.dynatrace.v2.default-dimensions.key2=value2
management.metrics.export.dynatrace.v2.use-dynatrace-summary-instruments=truemanagement:
metrics:
export:
dynatrace:
# 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 を指定する必要があります。
management.metrics.export.dynatrace.uri=https://{your-environment-id}.live.dynatrace.com
management.metrics.export.dynatrace.api-token=YOUR_TOKEN
management.metrics.export.dynatrace.v1.device-id=YOUR_DEVICE_IDmanagement:
metrics:
export:
dynatrace:
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 秒に設定します。
management.metrics.export.dynatrace.step=30smanagement:
metrics:
export:
dynatrace:
step: "30s"Micrometer ドキュメント (英語) および Dynatrace のドキュメント (英語) で Micrometer 用の Dynatrace エクスポーターをセットアップする方法の詳細については、こちらを参照してください。
6.2.5. Elastic
デフォルトでは、メトリクスはローカルマシンで実行されている Elastic (英語) にエクスポートされます。次のプロパティを使用して、使用する Elastic サーバーの場所を指定できます。
management.metrics.export.elastic.host=https://elastic.example.com:8086management:
metrics:
export:
elastic:
host: "https://elastic.example.com:8086"6.2.6. Ganglia
デフォルトでは、メトリクスはローカルマシンで実行されている Ganglia (英語) にエクスポートされます。次の例に示すように、Ganglia サーバー (英語) ホストとポートを指定できます。
management.metrics.export.ganglia.host=ganglia.example.com
management.metrics.export.ganglia.port=9649management:
metrics:
export:
ganglia:
host: "ganglia.example.com"
port: 96496.2.7. Graphite
デフォルトでは、メトリクスはローカルマシンで実行されている Graphite (英語) にエクスポートされます。次の例に示すように、Graphite サーバー (英語) ホストとポートを指定できます。
management.metrics.export.graphite.host=graphite.example.com
management.metrics.export.graphite.port=9004management:
metrics:
export:
graphite:
host: "graphite.example.com"
port: 9004Micrometer は、ディメンションメーター ID をフラットな階層名にマップ (英語) する方法を管理するデフォルトの HierarchicalNameMapper を提供します。
この動作を制御するには、 Java Kotlin |
6.2.8. Humio
デフォルトでは、Humio レジストリは定期的にメトリクスを cloud.humio.com (英語) にプッシュします。メトリクスを SaaS Humio (英語) にエクスポートするには、API トークンを提供する必要があります。
management.metrics.export.humio.api-token=YOUR_TOKENmanagement:
metrics:
export:
humio:
api-token: "YOUR_TOKEN"また、メトリクスがプッシュされるデータソースを識別するために、1 つ以上のタグを構成する必要があります。
management.metrics.export.humio.tags.alpha=a
management.metrics.export.humio.tags.bravo=bmanagement:
metrics:
export:
humio:
tags:
alpha: "a"
bravo: "b"6.2.9. Influx
デフォルトでは、メトリクスは、デフォルト構成でローカルマシンで実行されている Influx (英語) v1 インスタンスにエクスポートされます。メトリクスを InfluxDBv2 にエクスポートするには、メトリクスを書き込むための org、bucket、認証 token を構成します。以下を使用して、使用する Influx サーバー (英語) の場所を指定できます。
management.metrics.export.influx.uri=https://influx.example.com:8086management:
metrics:
export:
influx:
uri: "https://influx.example.com:8086"6.2.10. JMX
Micrometer は、JMX (英語) への階層マッピングを提供します。これは主に、メトリクスをローカルで表示するための安価でポータブルなメソッドです。デフォルトでは、メトリクスは metrics JMX ドメインにエクスポートされます。以下を使用して、使用するドメインを指定できます。
management.metrics.export.jmx.domain=com.example.app.metricsmanagement:
metrics:
export:
jmx:
domain: "com.example.app.metrics"Micrometer は、ディメンションメーター ID をフラットな階層名にマップ (英語) する方法を管理するデフォルトの HierarchicalNameMapper を提供します。
この動作を制御するには、 Java Kotlin |
6.2.11. KairosDB
デフォルトでは、メトリクスはローカルマシンで実行されている KairosDB (英語) にエクスポートされます。以下を使用して、使用する KairosDB サーバー (英語) の場所を指定できます。
management.metrics.export.kairos.uri=https://kairosdb.example.com:8080/api/v1/datapointsmanagement:
metrics:
export:
kairos:
uri: "https://kairosdb.example.com:8080/api/v1/datapoints"6.2.12. New Relic
New Relic レジストリは、定期的にメトリクスを New Relic (英語) にプッシュします。メトリクスを New Relic (英語) にエクスポートするには、API キーとアカウント ID を提供する必要があります。
management.metrics.export.newrelic.api-key=YOUR_KEY
management.metrics.export.newrelic.account-id=YOUR_ACCOUNT_IDmanagement:
metrics:
export:
newrelic:
api-key: "YOUR_KEY"
account-id: "YOUR_ACCOUNT_ID"また、メトリクスが New Relic に送信される間隔を変更することもできます。
management.metrics.export.newrelic.step=30smanagement:
metrics:
export:
newrelic:
step: "30s"デフォルトでは、メトリクスは REST 呼び出しを通じて公開されますが、クラスパスにある場合は Java AgentAPI を使用することもできます。
management.metrics.export.newrelic.client-provider-type=insights-agentmanagement:
metrics:
export:
newrelic:
client-provider-type: "insights-agent" 最後に、独自の NewRelicClientProvider Bean を定義することで、完全に制御できます。
6.2.13. 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 が存在する必要があります。Spring Cloud Sleuth を使用する場合、これは自動的に構成されますが、必要に応じていつでも独自に作成できます。
この機能は Prometheus 側で明示的に有効にする必要があり、OpenMetrics [GitHub] (英語) 形式を使用してのみサポートされるため、Prometheus ドキュメント (英語) を確認してください。
スクレイピングするのに十分な期間存在しない可能性のある一時的なジョブまたはバッチジョブの場合は、Prometheus Pushgateway [GitHub] (英語) サポートを使用してメトリクスを Prometheus に公開できます。Prometheus Pushgateway サポートを有効にするには、プロジェクトに次の依存関係を追加します。
<dependency>
<groupId>io.prometheus</groupId>
<artifactId>simpleclient_pushgateway</artifactId>
</dependency> クラスパスに Prometheus Pushgateway 依存関係が存在し、management.metrics.export.prometheus.pushgateway.enabled プロパティが true に設定されている場合、PrometheusPushGatewayManager Bean が自動的に構成されます。これにより、メトリクスの Prometheus Pushgateway へのプッシュが管理されます。
management.metrics.export.prometheus.pushgateway のプロパティを使用して、PrometheusPushGatewayManager を調整できます。高度な構成の場合は、独自の PrometheusPushGatewayManager Bean を提供することもできます。
6.2.14. SignalFx
SignalFx レジストリは、定期的にメトリクスを SignalFx (英語) にプッシュします。メトリクスを SignalFx (英語) にエクスポートするには、アクセストークンを提供する必要があります。
management.metrics.export.signalfx.access-token=YOUR_ACCESS_TOKENmanagement:
metrics:
export:
signalfx:
access-token: "YOUR_ACCESS_TOKEN"メトリクスが SignalFx に送信される間隔を変更することもできます。
management.metrics.export.signalfx.step=30smanagement:
metrics:
export:
signalfx:
step: "30s"6.2.15. シンプル
Micrometer には、他のレジストリが構成されていない場合にフォールバックとして自動的に使用される、シンプルなメモリ内バックエンドが付属しています。これにより、メトリクスエンドポイントで収集されているメトリクスを確認できます。
インメモリバックエンドは、他の利用可能なバックエンドを使用するとすぐに無効になります。明示的に無効にすることもできます。
management.metrics.export.simple.enabled=falsemanagement:
metrics:
export:
simple:
enabled: false6.2.16. Stackdriver
Stackdriver レジストリは定期的に指標を Stackdriver にプッシュします。メトリクスを SaaS Stackdriver (英語) にエクスポートするには、Google クラウドプロジェクト ID を指定する必要があります。
management.metrics.export.stackdriver.project-id=my-projectmanagement:
metrics:
export:
stackdriver:
project-id: "my-project"また、メトリクスが Stackdriver に送信される間隔を変更することもできます。
management.metrics.export.stackdriver.step=30smanagement:
metrics:
export:
stackdriver:
step: "30s"6.2.17. StatsD
StatsD レジストリは、UDP を介してメトリクスを StatsD エージェントに先行してプッシュします。デフォルトでは、メトリクスはローカルマシンで実行されている StatsD (英語) エージェントにエクスポートされます。以下を使用して、使用する StatsD エージェントのホスト、ポート、プロトコルを提供できます。
management.metrics.export.statsd.host=statsd.example.com
management.metrics.export.statsd.port=9125
management.metrics.export.statsd.protocol=udpmanagement:
metrics:
export:
statsd:
host: "statsd.example.com"
port: 9125
protocol: "udp"使用する StatsD 回線プロトコルを変更することもできます（デフォルトは Datadog です）。
management.metrics.export.statsd.flavor=etsymanagement:
metrics:
export:
statsd:
flavor: "etsy"6.2.18. Wavefront
Wavefront レジストリは、メトリクスを定期的に Wavefront (英語) にプッシュします。メトリクスを Wavefront (英語) に直接エクスポートする場合は、API トークンを提供する必要があります。
management.metrics.export.wavefront.api-token=YOUR_API_TOKENmanagement:
metrics:
export:
wavefront:
api-token: "YOUR_API_TOKEN"あるいは、環境内の Wavefront サイドカーまたは内部プロキシを使用して、メトリクスデータを Wavefront API ホストに転送することもできます。
management.metrics.export.wavefront.uri=proxy://localhost:2878management:
metrics:
export:
wavefront:
uri: "proxy://localhost:2878" メトリクスを Wavefront プロキシに公開する場合 ( Wavefront ドキュメント (英語) に従って)、ホストは proxy://HOST:PORT 形式である必要があります。 |
メトリクスが Wavefront に送信される間隔を変更することもできます。
management.metrics.export.wavefront.step=30smanagement:
metrics:
export:
wavefront:
step: "30s"6.3. サポートされているメトリクスとメーター
Spring Boot は、さまざまなテクノロジーの自動メーター登録を提供します。ほとんどの場合、デフォルトは、サポートされている監視システムのいずれかに公開できる実用的なメトリクスを提供します。
6.3.1. JVM メトリクス
自動構成により、コア Micrometer クラスを使用して JVM メトリクスが有効になります。JVM メトリクスは、jvm. メーター名で公開されます。
次の JVM メトリクスが提供されます。
さまざまなメモリとバッファプールの詳細
ガベージコレクションに関連する統計
スレッドの使用率
ロードおよびアンロードされたクラスの数
6.3.2. システムメトリクス
自動構成により、コア Micrometer クラスを使用してシステムメトリクスが有効になります。システムメトリクスは、system.、process.、disk. メーター名で公開されます。
次のシステムメトリクスが提供されます。
CPU メトリクス
ファイル記述子のメトリクス
稼働時間メトリクス (アプリケーションが実行されている時間と絶対開始時間の固定ゲージの両方)
利用可能なディスク容量
6.3.3. アプリケーションの起動メトリクス
自動構成により、アプリケーションの起動時間メトリクスが公開されます。
application.started.time: アプリケーションの起動にかかる時間。application.ready.time: アプリケーションがリクエストを処理する準備ができるまでにかかる時間。
メトリクスは、アプリケーションクラスの完全修飾名でタグ付けされます。
6.3.4. ロガーメトリクス
自動構成により、Logback と Log4J2 の両方のイベントメトリクスが有効になります。詳細は、log4j2.events. または logback.events. メーター名で公開されています。
6.3.5. タスクの実行とスケジューリングの指標
自動構成により、基盤となる ThreadPoolExecutor が使用可能である限り、使用可能なすべての ThreadPoolTaskExecutor および ThreadPoolTaskScheduler Bean のインスツルメンテーションが可能になります。メトリクスは、Bean 名から派生したエグゼキュータの名前でタグ付けされます。
6.3.6. Spring MVC メトリクス
自動構成により、Spring MVC コントローラーおよび機能ハンドラーによって処理されるすべてのリクエストのインストルメンテーションが可能になります。デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.metrics.web.server.request.metric-name プロパティを設定することにより、名前をカスタマイズできます。
@Timed アノテーションは、@Controller クラスおよび @RequestMapping メソッドでサポートされています（詳細については、@Timed アノテーションのサポートを参照してください）。すべての Spring MVC リクエストのメトリクスを記録したくない場合は、management.metrics.web.server.request.autotime.enabled を false に設定し、代わりに @Timed アノテーションのみを使用できます。
デフォルトでは、Spring MVC 関連のメトリクスは次の情報でタグ付けされています。
| タグ | 説明 |
|---|---|
| リクエストの処理中にスローされた例外の単純なクラス名。 |
| リクエストの方法 (たとえば、 |
| レスポンスのステータスコードに基づく、リクエストの結果。1xx は |
| レスポンスの HTTP ステータスコード (たとえば、 |
| 可能であれば、変数置換前のリクエストの URI テンプレート (たとえば、 |
デフォルトのタグに追加するには、WebMvcTagsContributor を実装する 1 つ以上の @Bean を提供します。デフォルトのタグを置き換えるには、WebMvcTagsProvider を実装する @Bean を提供します。
| 場合によっては、Web コントローラーで処理される例外は、リクエストメトリクスタグとして記録されません。アプリケーションは、処理された例外をリクエスト属性として設定することにより、オプトインして例外を記録できます。 |
デフォルトでは、すべてのリクエストが処理されます。フィルターをカスタマイズするには、FilterRegistrationBean<WebMvcMetricsFilter> を実装する @Bean を提供します。
6.3.7. Spring WebFlux メトリクス
自動構成により、Spring WebFlux コントローラーおよび機能ハンドラーによって処理されるすべてのリクエストのインストルメンテーションが可能になります。デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.metrics.web.server.request.metric-name プロパティを設定することにより、名前をカスタマイズできます。
@Timed アノテーションは、@Controller クラスおよび @RequestMapping メソッドでサポートされています（詳細については、@Timed アノテーションのサポートを参照してください）。すべての Spring WebFlux リクエストのメトリクスを記録したくない場合は、management.metrics.web.server.request.autotime.enabled を false に設定し、代わりに @Timed アノテーションのみを使用できます。
デフォルトでは、WebFlux 関連のメトリクスは次の情報でタグ付けされています。
| タグ | 説明 |
|---|---|
| リクエストの処理中にスローされた例外の単純なクラス名。 |
| リクエストの方法 (たとえば、 |
| レスポンスのステータスコードに基づく、リクエストの結果。1xx は |
| レスポンスの HTTP ステータスコード (たとえば、 |
| 可能であれば、変数置換前のリクエストの URI テンプレート (たとえば、 |
デフォルトのタグに追加するには、WebFluxTagsContributor を実装する 1 つ以上の Bean を提供します。デフォルトのタグを置き換えるには、WebFluxTagsProvider を実装する Bean を提供します。
| 場合によっては、コントローラーおよびハンドラー関数で処理される例外は、リクエストメトリクスタグとして記録されません。アプリケーションは、処理された例外をリクエスト属性として設定することにより、オプトインして例外を記録できます。 |
6.3.8. Jersey サーバーメトリクス
自動構成により、Jersey JAX-RS 実装によって処理されるすべてのリクエストのインストルメンテーションが可能になります。デフォルトでは、メトリクスは http.server.requests という名前で生成されます。management.metrics.web.server.request.metric-name プロパティを設定することにより、名前をカスタマイズできます。
@Timed アノテーションは、リクエスト処理クラスおよびメソッドでサポートされています（詳細については、@Timed アノテーションのサポートを参照してください）。すべての Jersey リクエストのメトリクスを記録したくない場合は、management.metrics.web.server.request.autotime.enabled を false に設定し、代わりに @Timed アノテーションのみを使用できます。
デフォルトでは、Jersey サーバーメトリクスは次の情報でタグ付けされます。
| タグ | 説明 |
|---|---|
| リクエストの処理中にスローされた例外の単純なクラス名。 |
| リクエストの方法 (たとえば、 |
| レスポンスのステータスコードに基づく、リクエストの結果。1xx は |
| レスポンスの HTTP ステータスコード (たとえば、 |
| 可能であれば、変数置換前のリクエストの URI テンプレート (たとえば、 |
タグをカスタマイズするには、JerseyTagsProvider を実装する @Bean を提供します。
6.3.9. HTTP クライアントメトリクス
Spring Boot Actuator は、RestTemplate と WebClient の両方のインストルメンテーションを管理します。そのためには、自動構成されたビルダーを挿入し、それを使用してインスタンスを作成する必要があります。
RestTemplate用RestTemplateBuilderWebClient用WebClient.Builder
このインストルメンテーションを担当するカスタマイザー、つまり MetricsRestTemplateCustomizer および MetricsWebClientCustomizer を手動で適用することもできます。
デフォルトでは、メトリクスは http.client.requests という名前で生成されます。management.metrics.web.client.request.metric-name プロパティを設定することにより、名前をカスタマイズできます。
デフォルトでは、インストルメントされたクライアントによって生成されたメトリクスには、次の情報がタグ付けされます。
| タグ | 説明 |
|---|---|
| URI のホスト部分 |
| リクエストの方法 (たとえば、 |
| レスポンスのステータスコードに基づく、リクエストの結果。1xx は |
| レスポンスの HTTP ステータスコード（使用可能な場合）（たとえば、 |
| 可能であれば、変数置換前のリクエストの URI テンプレート (たとえば、 |
タグをカスタマイズし、選択したクライアントに応じて、RestTemplateExchangeTagsProvider または WebClientExchangeTagsProvider を実装する @Bean を提供できます。RestTemplateExchangeTags および WebClientExchangeTags には便利な静的関数があります。
すべての RestTemplate および WebClient リクエストのメトリクスを記録したくない場合は、management.metrics.web.client.request.autotime.enabled を false に設定します。
6.3.10. Tomcat メトリクス
自動構成により、MBeanRegistry が有効になっている場合にのみ Tomcat のインストルメンテーションが有効になります。デフォルトでは、MBeanRegistry は無効になっていますが、server.tomcat.mbeanregistry.enabled を true に設定することで有効にできます。
Tomcat メトリクスは、tomcat. メーター名で公開されています。
6.3.11. キャッシュメトリクス
自動構成により、起動時に使用可能なすべての Cache インスタンスのインストルメンテーションが可能になり、メトリクスの前に cache が付けられます。キャッシュインストルメンテーションは、メトリクスの基本セットに対して標準化されています。追加のキャッシュ固有のメトリクスも利用できます。
次のキャッシュライブラリがサポートされています。
Cache2k
Caffeine
EhCache 2
Hazelcast
準拠する JCache（JSR-107）実装
Redis
メトリクスは、キャッシュの名前と、Bean 名から派生した CacheManager の名前でタグ付けされます。
起動時に構成されたキャッシュのみがレジストリにバインドされます。オンザフライで作成されたキャッシュや起動フェーズ後にプログラムで作成されたキャッシュなど、キャッシュの構成で定義されていないキャッシュの場合は、明示的な登録が必要です。そのプロセスを容易にするために、CacheMetricsRegistrar Bean が利用可能になります。 |
6.3.12. Spring GraphQL メトリクス
自動構成により、サポートされているトランスポートに対して、GraphQL クエリのインストルメンテーションが可能になります。
Spring Boot は、次のように graphql.request タイマーを記録します。
| タグ | 説明 | サンプル値 |
|---|---|---|
outcome | 結果をリクエストする | 「成功」、「エラー」 |
1 つの GraphQL クエリには多くの DataFetcher 呼び出しが含まれる可能性があるため、専用の graphql.datafetcher タイマーがあります。
| タグ | 説明 | サンプル値 |
|---|---|---|
path | データフェッチャーパス | "Query.project" |
outcome | データフェッチの結果 | 「成功」、「エラー」 |
graphql.request.datafetch.count 配布要約 (英語) は、リクエストごとに行われた重要な DataFetcher 呼び出しの数をカウントします。このメトリクスは、"N + 1" データフェッチの課題を検出し、バッチロードを検討できます。これは、記録されたリクエストの "COUNT" を介して行われたデータフェッチャー呼び出しの "TOTAL" 数と、考慮された期間に単一のリクエストに対して行われた "MAX" 呼び出しを提供します。アプリケーションプロパティを使用してディストリビューションを構成するために、より多くのオプションを利用できます。
単一のレスポンスには、graphql.error カウンターによってカウントされる多くの GraphQL エラーが含まれる可能性があります。
| タグ | 説明 | サンプル値 |
|---|---|---|
errorType | エラー型 | "DataFetchingException" |
errorPath | エラー JSON パス | "$.project" |
6.3.13. DataSource メトリクス
自動構成により、jdbc.connections で始まるメトリクスを使用して、使用可能なすべての DataSource オブジェクトをインストルメント化できます。データソースインストルメンテーションは、プール内の現在アクティブ、アイドル、最大許容、最小許容接続を表すゲージになります。
メトリクスは、Bean 名に基づいて計算された DataSource の名前でもタグ付けされます。
デフォルトでは、Spring Boot はサポートされているすべてのデータソースのメタデータを提供します。お気に入りのデータソースがサポートされていない場合は、DataSourcePoolMetadataProvider Bean を追加できます。例については、DataSourcePoolMetadataProvidersConfiguration を参照してください。 |
また、光固有のメトリクスは hikaricp プレフィックスで公開されます。各メトリクスは、プールの名前でタグ付けされます（spring.datasource.name で制御できます）。
6.3.14. Hibernate メトリクス
org.hibernate:hibernate-micrometer がクラスパス上にある場合、統計が有効になっている使用可能なすべての Hibernate EntityManagerFactory インスタンスは、hibernate という名前のメトリクスで計測されます。
メトリクスには、Bean 名から派生した EntityManagerFactory の名前もタグ付けされます。
統計を有効にするには、標準の JPA プロパティ hibernate.generate_statistics を true に設定する必要があります。自動構成された EntityManagerFactory でそれを有効にすることができます:
spring.jpa.properties[hibernate.generate_statistics]=truespring:
jpa:
properties:
"[hibernate.generate_statistics]": true6.3.15. Spring Data リポジトリメトリクス
自動構成により、すべての Spring Data Repository メソッド呼び出しのインストルメンテーションが可能になります。デフォルトでは、メトリクスは spring.data.repository.invocations という名前で生成されます。management.metrics.data.repository.metric-name プロパティを設定することにより、名前をカスタマイズできます。
@Timed アノテーションは、Repository クラスおよびメソッドでサポートされています（詳細については、@Timed アノテーションのサポートを参照してください）。すべての Repository 呼び出しのメトリクスを記録したくない場合は、management.metrics.data.repository.autotime.enabled を false に設定し、代わりに @Timed アノテーションのみを使用できます。
デフォルトでは、リポジトリ呼び出し関連のメトリクスは次の情報でタグ付けされています。
| タグ | 説明 |
|---|---|
| ソース |
| 呼び出された |
| 結果の状態（ |
| 呼び出しからスローされた例外の単純なクラス名。 |
デフォルトのタグを置き換えるには、RepositoryTagsProvider を実装する @Bean を提供します。
6.3.17. Spring Integration メトリクス
Spring Integration は、MeterRegistry Bean が使用可能な場合は常に、Micrometer サポートを自動的に提供します。メトリクスは、spring.integration. メーター名で公開されています。
6.3.18. Kafka メトリクス
自動構成は、自動構成されたコンシューマーファクトリとプロデューサーファクトリにそれぞれ MicrometerConsumerListener と MicrometerProducerListener を登録します。また、StreamsBuilderFactoryBean の KafkaStreamsMicrometerListener を登録します。詳細については、Spring Kafka ドキュメントの Micrometer ネイティブメトリクスセクションを参照してください。
6.3.19. MongoDB メトリクス
このセクションでは、MongoDB で使用可能なメトリクスについて簡単に説明します。
MongoDB コマンドメトリクス
自動構成は、MongoMetricsCommandListener を自動構成された MongoClient に登録します。
基礎となる MongoDB ドライバーに発行されたコマンドごとに、mongodb.driver.commands という名前のタイマーメトリクスが作成されます。各メトリクスには、デフォルトで次の情報がタグ付けされています。
| タグ | 説明 |
|---|---|
| 発行されたコマンドの名前。 |
| コマンドの送信先のクラスターの ID。 |
| コマンドの送信先のサーバーのアドレス。 |
| コマンドの結果（ |
次の例に示すように、デフォルトのメトリクスタグを置き換えるには、MongoCommandTagsProvider Bean を定義します。
@Configuration(proxyBeanMethods = false)
public class MyCommandTagsProviderConfiguration {
@Bean
public MongoCommandTagsProvider customCommandTagsProvider() {
return new CustomCommandTagsProvider();
}
}
@Configuration(proxyBeanMethods = false)
class MyCommandTagsProviderConfiguration {
@Bean
fun customCommandTagsProvider(): MongoCommandTagsProvider? {
return CustomCommandTagsProvider()
}
}
自動構成されたコマンドメトリクスを無効にするには、次のプロパティを設定します。
management.metrics.mongo.command.enabled=falsemanagement:
metrics:
mongo:
command:
enabled: falseMongoDB 接続プールメトリクス
自動構成は、MongoMetricsConnectionPoolListener を自動構成された MongoClient に登録します。
次のゲージメトリクスが接続プール用に作成されます。
mongodb.driver.pool.sizeは、アイドル状態のメンバーと使用中のメンバーを含む、接続プールの現在のサイズを報告します。mongodb.driver.pool.checkedoutは、現在使用されている接続の数を報告します。mongodb.driver.pool.waitqueuesizeは、プールからの接続の待機キューの現在のサイズを報告します。
各メトリクスには、デフォルトで次の情報がタグ付けされています。
| タグ | 説明 |
|---|---|
| 接続プールが対応するクラスターの ID。 |
| 接続プールが対応するサーバーのアドレス。 |
デフォルトのメトリクスタグを置き換えるには、MongoConnectionPoolTagsProvider Bean を定義します。
@Configuration(proxyBeanMethods = false)
public class MyConnectionPoolTagsProviderConfiguration {
@Bean
public MongoConnectionPoolTagsProvider customConnectionPoolTagsProvider() {
return new CustomConnectionPoolTagsProvider();
}
}
@Configuration(proxyBeanMethods = false)
class MyConnectionPoolTagsProviderConfiguration {
@Bean
fun customConnectionPoolTagsProvider(): MongoConnectionPoolTagsProvider {
return CustomConnectionPoolTagsProvider()
}
}
自動構成された接続プールメトリクスを無効にするには、次のプロパティを設定します。
management.metrics.mongo.connectionpool.enabled=falsemanagement:
metrics:
mongo:
connectionpool:
enabled: false6.3.20. Jetty メトリクス
自動構成は、Micrometer の JettyServerThreadPoolMetrics を使用して、Jetty の ThreadPool のメトリクスをバインドします。Jetty の Connector インスタンスのメトリクスは、Micrometer の JettyConnectionMetrics を使用してバインドされ、server.ssl.enabled が true に設定されている場合は、Micrometer の JettySslHandshakeMetrics にバインドされます。
6.3.21. @Timed アノテーションのサポート
io.micrometer.core.annotation パッケージの @Timed アノテーションは、前述のサポートされているテクノロジーのいくつかで使用できます。サポートされている場合は、クラスレベルまたはメソッドレベルのいずれかでアノテーションを使用できます。
例: 次のコードは、アノテーションを使用して @RestController のすべてのリクエストマッピングをインストルメント化する方法を示しています。
@RestController
@Timed
public class MyController {
@GetMapping("/api/addresses")
public List<Address> listAddress() {
return ...
}
@GetMapping("/api/people")
public List<Person> listPeople() {
return ...
}
}
@RestController
@Timed
class MyController {
@GetMapping("/api/addresses")
fun listAddress(): List<Address>? {
return ...
}
@GetMapping("/api/people")
fun listPeople(): List<Person>? {
return ...
}
}
単一のマッピングのみをインストルメント化する場合は、クラスの代わりにメソッドのアノテーションを使用できます。
@RestController
public class MyController {
@GetMapping("/api/addresses")
public List<Address> listAddress() {
return ...
}
@GetMapping("/api/people")
@Timed
public List<Person> listPeople() {
return ...
}
}
@RestController
class MyController {
@GetMapping("/api/addresses")
fun listAddress(): List<Address>? {
return ...
}
@GetMapping("/api/people")
@Timed
fun listPeople(): List<Person>? {
return ...
}
}
特定のメソッドのタイミングの詳細を変更する場合は、クラスレベルとメソッドレベルのアノテーションを組み合わせることもできます。
@RestController
@Timed
public class MyController {
@GetMapping("/api/addresses")
public List<Address> listAddress() {
return ...
}
@GetMapping("/api/people")
@Timed(extraTags = { "region", "us-east-1" })
@Timed(value = "all.people", longTask = true)
public List<Person> listPeople() {
return ...
}
}
@RestController
@Timed
class MyController {
@GetMapping("/api/addresses")
fun listAddress(): List<Address>? {
return ...
}
@GetMapping("/api/people")
@Timed(value = "all.people", longTask = true, extraTags = ["region", "us-east-1"])
fun listPeople(): List<Person>? {
return ...
}
}
longTask = true を使用した @Timed アノテーションにより、メソッドの長いタスクタイマーが有効になります。長いタスクタイマーには個別のメトリクス名が必要であり、短いタスクタイマーとスタックできます。 |
Spring Boot で直接サポートされていない @Timed を使用するには、Micrometer ドキュメント (英語) を参照してください。 |
6.3.22. Redis メトリクス
自動構成は、自動構成された LettuceConnectionFactory の MicrometerCommandLatencyRecorder を登録します。詳細については、Lettuce ドキュメントの Micrometer メトリクスセクション (英語) を参照してください。
6.4. カスタムメトリクスの登録
カスタムメトリクスを登録するには、MeterRegistry をコンポーネントに挿入します。
@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());
}
}
@Component
class MyBean(registry: MeterRegistry) {
private val dictionary: Dictionary
init {
dictionary = Dictionary.load()
registry.gauge("dictionary.size", Tags.empty(), dictionary.words.size)
}
}
メトリクスが他の Bean に依存している場合は、MeterBinder を使用して登録することをお勧めします。
public class MyMeterBinderConfiguration {
@Bean
public MeterBinder queueSize(Queue queue) {
return (registry) -> Gauge.builder("queueSize", queue::size).register(registry);
}
}
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 に自動的にバインドされます。 |
6.5. 個々の指標のカスタマイズ
特定の Meter インスタンスにカスタマイズを適用する必要がある場合は、io.micrometer.core.instrument.config.MeterFilter インターフェースを使用できます。
例: com.example で始まるすべてのメーター ID の mytag.region タグの名前を mytag.area に変更する場合、次の操作を実行できます。
@Configuration(proxyBeanMethods = false)
public class MyMetricsFilterConfiguration {
@Bean
public MeterFilter renameRegionTagMeterFilter() {
return MeterFilter.renameTag("com.example", "mytag.region", "mytag.area");
}
}
@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 が管理していないグローバルレジストリを使用します。 |
6.5.1. 共通タグ
一般的なタグは、一般に、ホスト、インスタンス、リージョン、スタックなどのオペレーティング環境でのディメンションのドリルダウンに使用されます。Commons タグはすべてのメーターに適用され、次の例に示すように構成できます。
management.metrics.tags.region=us-east-1
management.metrics.tags.stack=prodmanagement:
metrics:
tags:
region: "us-east-1"
stack: "prod" 前の例では、region タグと stack タグを、それぞれ us-east-1 と prod の値ですべてのメーターに追加します。
Graphite を使用する場合、共通タグの順序は重要です。このアプローチでは共通タグの順序を保証できないため、Graphite ユーザーは代わりにカスタム MeterFilter を定義することをお勧めします。 |
6.5.2. メーターごとのプロパティ
MeterFilter Bean に加えて、プロパティを使用してメーターごとに限定されたカスタマイズセットを適用できます。メーターごとのカスタマイズは、Spring Boot の PropertiesMeterFilter を使用して、指定された名前で始まるすべてのメーター ID に適用されます。次の例では、ID が example.remote で始まるすべてのメーターを除外します。
management.metrics.enable.example.remote=falsemanagement:
metrics:
enable:
example:
remote: false次のプロパティでは、メーターごとのカスタマイズが可能です。
| プロパティ | 説明 |
|---|---|
| 特定の ID を持つメーターを受け入れるかどうか。受け入れられないメーターは |
| 集計可能な（ディメンション間）パーセンタイル近似の計算に適したヒストグラムを公開するかどうか。 |
| 期待値の範囲をクランプすることにより、公開するヒストグラムバケットの数を減らします。 |
| アプリケーションで計算されたパーセンタイル値を公開する |
| 構成可能な有効期限の後に回転するリングバッファーに、構成可能なバッファー長で蓄積することにより、最近のサンプルにより大きな重みを与えます。 |
| サービスレベルゴールによって定義されたバケットを含む累積ヒストグラムを公開します。 |
percentiles-histogram、percentiles、slo の背景となる概念の詳細については、Micrometer ドキュメントの「ヒストグラムとパーセンタイル」セクション (英語) を参照してください。
6.6. メトリクスエンドポイント
Spring Boot は、アプリケーションによって収集されたメトリクスを検査するために診断的に使用できる metrics エンドポイントを提供します。エンドポイントはデフォルトでは使用できないため、公開する必要があります。詳細については、エンドポイントの公開を参照してください。
/actuator/metrics に移動すると、使用可能なメーター名のリストが表示されます。セレクターとして名前を指定することにより、特定のメーターに関する情報を表示するためにドリルダウンできます（たとえば、/actuator/metrics/jvm.memory.max）。
ここで使用する名前は、コードで使用されている名前と一致している必要があります。命名規則が提供された監視システム用に正規化された後の名前ではありません。つまり、 |
URL の末尾に任意の数の tag=KEY:VALUE クエリパラメーターを追加して、メーターを次元的にドリルダウンすることもできます（たとえば、/actuator/metrics/jvm.memory.max?tag=area:nonheap）。
報告される測定値は、メーター名と適用されたタグに一致するすべてのメーターの統計の合計です。前の例では、返される |
7. 監査
Spring Security が動作すると、Spring Boot Actuator にはイベント（デフォルトでは「認証成功」、「失敗」、「アクセス拒否」の例外）を公開する柔軟な監査フレームワークがあります。この機能は、レポートおよび認証失敗に基づいたロックアウトポリシーの実装に非常に役立ちます。
アプリケーションの構成で型 AuditEventRepository の Bean を提供することにより、監査を有効にできます。便宜上、Spring Boot は InMemoryAuditEventRepository を提供しています。InMemoryAuditEventRepository の機能には制限があるため、開発環境でのみ使用することをお勧めします。本番環境では、独自の代替 AuditEventRepository 実装を作成することを検討してください。
7.1. カスタム監査
公開されたセキュリティイベントをカスタマイズするには、AbstractAuthenticationAuditListener および AbstractAuthorizationAuditListener の独自の実装を提供できます。
独自のビジネスイベントに監査サービスを使用することもできます。そのためには、AuditEventRepository Bean を独自のコンポーネントに挿入して直接使用するか、AuditApplicationEvent を Spring ApplicationEventPublisher で公開します（ApplicationEventPublisherAware を実装することにより）。
8. HTTP トレース
HTTP トレースを有効にするには、アプリケーションの構成で HttpTraceRepository 型の Bean を指定します。便宜上、Spring Boot は、最後の 100 件 (デフォルト) のリクエストとレスポンスの交換のトレースを保存する InMemoryHttpTraceRepository を提供します。InMemoryHttpTraceRepository は他のトレースソリューションと比べて制限があるため、開発環境でのみ使用することをお勧めします。本番環境の場合は、Zipkin や Spring Cloud Sleuth など、本番対応のトレースまたは可観測性ソリューションを使用することをお勧めします。あるいは、独自の HttpTraceRepository を作成することもできます。
httptrace エンドポイントを使用して、HttpTraceRepository に格納されているリクエスト / レスポンス交換に関する情報を取得できます。
9. プロセス監視
spring-boot モジュールには、プロセスの監視に役立つことが多いファイルを作成するための 2 つのクラスがあります。
ApplicationPidFileWriterは、アプリケーション PID を含むファイルを作成します（デフォルトでは、ファイル名がapplication.pidのアプリケーションディレクトリにあります）。WebServerPortFileWriterは、実行中の Web サーバーのポートを含む 1 つまたは複数のファイルを作成します（デフォルトでは、ファイル名がapplication.portのアプリケーションディレクトリにあります）。
デフォルトでは、これらのライターはアクティブ化されていませんが、有効にすることができます。
10. Cloud Foundry サポート
Spring Boot のアクチュエーターモジュールには、互換性のある Cloud Foundry インスタンスにデプロイするときにアクティブになる追加のサポートが含まれています。/cloudfoundryapplication パスは、すべての @Endpoint Bean への安全な代替ルートを提供します。
拡張サポートにより、Cloud Foundry 管理 UI（デプロイされたアプリケーションを表示するために使用できる Web アプリケーションなど）を Spring Boot アクチュエーター情報で拡張できます。例: アプリケーションステータスページには、通常の「実行中」または「停止」ステータスの代わりに、完全なヘルス情報を含めることができます。
/cloudfoundryapplication パスは、通常のユーザーが直接アクセスすることはできません。エンドポイントを使用するには、リクエストで有効な UAA トークンを渡す必要があります。 |
10.1. 拡張 Cloud Foundry アクチュエーターサポートの無効化
/cloudfoundryapplication エンドポイントを完全に無効にする場合は、application.properties ファイルに次の設定を追加できます。
management.cloudfoundry.enabled=falsemanagement:
cloudfoundry:
enabled: false10.2. Cloud Foundry 自己署名証明書
デフォルトでは、/cloudfoundryapplication エンドポイントのセキュリティ検証は、さまざまな Cloud Foundry サービスへの SSL 呼び出しを行います。Cloud Foundry UAA または Cloud Controller サービスが自己署名証明書を使用する場合、次のプロパティを設定する必要があります。
management.cloudfoundry.skip-ssl-validation=truemanagement:
cloudfoundry:
skip-ssl-validation: true10.3. カスタムコンテキストパス
サーバーのコンテキストパスが / 以外に構成されている場合、Cloud Foundry エンドポイントはアプリケーションのルートで使用できません。例: server.servlet.context-path=/app の場合、Cloud Foundry エンドポイントは /app/cloudfoundryapplication/* で使用できます。
サーバーのコンテキストパスに関係なく、Cloud Foundry エンドポイントが常に /cloudfoundryapplication/* で利用可能であると予想される場合は、アプリケーションで明示的に構成する必要があります。構成は、使用している Web サーバーによって異なります。Tomcat の場合、次の構成を追加できます。
@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("/*");
};
}
}
@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("/*")
}
}
}
11. 次のステップ
Graphite (英語) などのグラフ作成ツールについて参照してください。
それ以外の場合は、「デプロイオプション」について読み続けるか、Spring Boot のビルドツールプラグインに関する詳細な情報を先に参照してください。