Spring Boot Actuator: 本番対応機能

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

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

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

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

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

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

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

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

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

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

レスポンスの HTTP ステータスコードは、全体的なヘルスステータスを反映します（たとえば、UP は 200 にマッピングされ、OUT_OF_SERVICE および DOWN は 503 にマッピングされます）。HTTP 経由でヘルスエンドポイントにアクセスする場合は、カスタムステータスマッピングを登録することもできます。例: 次のプロパティは FATAL を 503 にマップします（サービスは利用できません）:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

完全な git 情報（つまり、git.properties の完全なコンテンツ）を表示する場合は、次のように management.info.git.mode プロパティを使用します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

クラスパスに Prometheus Pushgateway 依存関係が存在する場合、Spring Boot は PrometheusPushGatewayManager Bean を自動構成します。これにより、Prometheus Pushgateway へのメトリクスのプッシュが管理されます。PrometheusPushGatewayManager は、management.metrics.export.prometheus.pushgateway のプロパティを使用して調整できます。高度な構成では、独自の PrometheusPushGatewayManager Bean を提供することもできます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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