Micrometerメトリクス
Micrometer は、メトリクス収集のための抽象化レイヤーを提供します。カウンター、ゲージ、タイマー、ディストリビューションサマリーなどの基本的なメータータイプの API と、さまざまなバックエンドモニタリングシステムのメトリクス収集と伝達を一般化する MeterRegistry API を定義します。
このドキュメントは、Quarkusにおけるオブザーバビリティリファレンスガイド の一部であり、このガイドでは本コンポーネントとその他のオブザーバビリティ関連コンポーネントを紹介しています。
| Micrometer は、Quarkus のメトリクスに対する推奨アプローチです。 |
| デフォルトでは、メトリクスはメイン HTTP サーバーで公開されます。別の管理ポートからメトリクスを表示したい場合は、Managed interface セクションを参照してください。 |
Micrometer とモニタリングシステムエクステンション
Quarkus Micrometer エクステンションは、Micrometer プロジェクトと同じ構造になっています。quarkus-micrometer エクステンションは、Micrometer のコアサポートとランタイム統合を提供します。その他の Quarkus および Quarkiverse エクステンションは、Quarkus Micrometer エクステンションを使用して、他のモニタリングシステムのサポートを提供します。
Quarkus エクステンション:
-
micrometer
-
micrometer-registry-prometheus
-
micrometer-opentelemetry
Quarkiverse エクステンション (このリストは完全ではない可能性があります):
-
micrometer-registry-azure-monitor
-
micrometer-registry-datadog
-
micrometer-registry-graphite
-
micrometer-registry-influx
-
micrometer-registry-jmx
-
micrometer-registry-newrelic-telemetry
-
micrometer-registry-otlp
-
micrometer-registry-signalfx
-
micrometer-registry-stackdriver
-
micrometer-registry-statsd
例えば、アプリケーションに Prometheus メトリクスのサポートを追加するには、micrometer-registry-prometheus エクステンションを使用します。これにより、Quarkus Micrometer エクステンションと Micrometer コアライブラリが依存関係として追加されます。
(プロジェクトディレクトリで)以下のコマンドを使用して、エクステンションをプロジェクトに追加します:
quarkus extension add micrometer-registry-prometheus
./mvnw quarkus:add-extension -Dextensions='micrometer-registry-prometheus'
./gradlew addExtension --extensions='micrometer-registry-prometheus'
これにより、ビルドファイルに以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>
implementation("io.quarkus:quarkus-micrometer-registry-prometheus")
これで準備完了です!
他のメーターレジストリーエクステンションにも同様のプロセスが適用されます。例えば、Micrometer StackDriver MeterRegistry を使用するには、Quarkiverse の quarkus-micrometer-registry-stackdriver エクステンションを使用します:
quarkus extension add io.quarkiverse.micrometer.registry:quarkus-micrometer-registry-stackdriver
./mvnw quarkus:add-extension -Dextensions='io.quarkiverse.micrometer.registry:quarkus-micrometer-registry-stackdriver'
./gradlew addExtension --extensions='io.quarkiverse.micrometer.registry:quarkus-micrometer-registry-stackdriver'
<dependency>
<groupId>io.quarkiverse.micrometer.registry</groupId>
<artifactId>quarkus-micrometer-registry-stackdriver</artifactId>
</dependency>
implementation("io.quarkiverse.micrometer.registry:quarkus-micrometer-registry-stackdriver")
その他のレジストリ実装
使用したい Micrometer レジストリに関連エクステンションがない場合は、quarkus-micrometer エクステンションを使用し、Micrometer メーターレジストリの依存関係を直接取り込んでください:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-micrometer</artifactId>
</dependency>
<dependency>
<groupId>com.acme</groupId>
<artifactId>custom-micrometer-registry</artifactId>
<version>...</version>
</dependency>
implementation("io.quarkus:quarkus-micrometer")
implementation("com.acme:custom-micrometer-registry")
次に、次のセクションで説明するように、MeterRegistry を設定して初期化するために、独自のプロバイダを指定する必要があります。
OpenTelemetry を介した Micrometer メトリクスの送信
quarkus-micrometer-opentelemetry エクステンションを使用すると、Quarkus で利用可能な Micrometer API と既存のすべての自動インスツルメンテーションを使用しながら、OpenTelemetry ですべてのテレメトリーを送信できます。
これは、OpenTelemetry SDK で実装された Micrometer レジストリによって実現され、Micrometer メトリクス、OpenTelemetry トレース、およびログを OTLP プロトコルを使用した統合テレメトリー出力に統合できます。
Quarkus プロジェクトがすでに設定されている場合、プロジェクトのベースディレクトリーで次のコマンドを実行することで、quarkus-micrometer-opentelemetry エクステンションをプロジェクトに追加できます:
quarkus extension add micrometer-opentelemetry
./mvnw quarkus:add-extension -Dextensions='micrometer-opentelemetry'
./gradlew addExtension --extensions='micrometer-opentelemetry'
これにより、ビルドファイルに以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-micrometer-opentelemetry</artifactId>
</dependency>
implementation("io.quarkus:quarkus-micrometer-opentelemetry")
カスタマイズされた MeterRegistry の作成
必要に応じて、カスタム @Produces メソッドを使用して、独自の MeterRegistry を作成および設定します。
次の例は、StatsD に使用される行形式をカスタマイズするものです:
@Produces
@Singleton (1)
public StatsdMeterRegistry createStatsdMeterRegistry(StatsdConfig statsdConfig, Clock clock) { (2)
// define what to do with lines
Consumer<String> lineLogger = line -> logger.info(line);
// inject a configuration object, and then customize the line builder
return StatsdMeterRegistry.builder(statsdConfig)
.clock(clock)
.lineSink(lineLogger)
.build();
}
| 1 | このメソッドは @Singleton を返します。 |
| 2 | このメソッドは特定のタイプの MeterRegistry を返します |
この例は、Micrometer ドキュメントの Micrometer StatsD: Customizing the Metrics Sink の手順に対応しています。
MicroProfile Config を使用して、レジストリーを設定するために必要な設定属性を挿入します。quarkus-micrometer-registry-statsd などのほとんどの Micrometer レジストリーエクステンションは、Quarkus 設定モデルと統合されたレジストリー固有の設定オブジェクトを提供します。Quarkiverse GitHub Repository は、便利な実装リファレンスとして活用できます。
独自のメトリクスの作成
メトリクスデータは、時間の経過に伴うデータの変化を観察するために集計されて使用されます。このデータは、傾向分析、異常検出、アラートに活用されます。データは、バックエンドモニタリングシステムによって時系列データベースに保存され、新しい値が系列の末尾に追加されます。
| メトリクスは遅延して構築されます。エンドポイントへのアクセスなど、メトリクスを作成するアクションを実行するまで、探しているメトリクスのデータが表示されない場合があります。 |
命名規則
メーター名では、ドットを使用してセグメントを区切る必要があります (例: a.name.like.this)。Micrometer は命名規則を適用し、登録されたメーター名をバックエンドモニタリングシステムの期待に一致するように変換します。
次のタイマー宣言 registry.timer("http.server.requests") を考慮すると、適用される命名規則は、さまざまなモニタリングシステムに対して以下のメトリクスを出力します:
-
Prometheus:
http_server_requests_duration_seconds -
Atlas:
httpServerRequests -
Graphite:
http.server.requests -
InfluxDB:
http_server_requests
集計のディメンション定義
メトリクスは単一の数値測定ですが、多くの場合、追加データが一緒にキャプチャーされます。この補助データは、分析のためにメトリクスをグループ化または集計するために使用されます。Micrometer API では、このディメンションデータをタグと呼びますが、他のドキュメントソースでは「ラベル」または「属性」と呼ばれることもあります。
Micrometer は主に、ディメンションデータ (キー/値のペアで強化されたメトリクス名) をサポートするバックエンドモニタリングシステム用に構築されています。フラットなメトリクス名のみをサポートする階層型システムの場合、Micrometer はキー/値のペアのセット (キーでソート) をフラット化し、名前に追加します。
タグは、メーターが MeterRegistry に登録されるとき、または Meter Filter を使用して指定できます。
タグの命名 に関するその他のアドバイスについては、Micrometer のドキュメントを参照してください。
| メトリクス名とディメンションの一意の組み合わせごとに、一意の時系列が生成されます。無制限のディメンションデータセットを使用すると、「カーディナリティーの爆発」、つまり新しい時系列の作成が指数関数的に増加する可能性があります。 |
MeterRegistry への参照の取得
メーターを登録するには、Micrometer エクステンションによって設定および維持される MeterRegistry への参照が必要です。
MeterRegistry への参照を取得するには、次のいずれかの方法を使用します。
-
CDIコンストラクタ注入の使用:
package org.acme.micrometer; import io.micrometer.core.instrument.MeterRegistry; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; @Path("/example") @Produces("text/plain") public class ExampleResource { private final MeterRegistry registry; ExampleResource(MeterRegistry registry) { this.registry = registry; } } -
MeterRegistryメンバー変数を使用し、@Injectを使用します。@Inject MeterRegistry registry; -
グローバル
MeterRegistryを使用します。MeterRegistry registry = Metrics.globalRegistry;
ゲージ
ゲージは、車のスピードメーターのように、時間の経過とともに増加または減少する値を測定します。ゲージは、キャッシュまたはコレクションの統計を監視するときに役立ちます。
ゲージの値は設定されずにサンプリングされます。測定間でゲージに関連付けられた値がどのように変化したかについての記録はありません。
Micrometer はゲージを作成するためのいくつかのメカニズムを提供します。
-
コレクションのサイズを監視するためにコレクションの構築をラップします。
List<String> list = registry.gaugeCollectionSize("fantastic.list", (1) Tags.of("key", "value") // optional (2) new ArrayList<>()); (3)1 ドット区切りの規則を使用して、新しいゲージ list.sizeを作成します。2 ゲージに tags を関連付けます。ゲージタグの値は一定であり、構築時に割り当てる必要があります。 3 サイズを監視する必要のある配列リストを構築します。 -
ビルダーを使用して、関数を呼び出すゲージを作成します。
Gauge.builder("jvm.threads.peak", threadBean, ThreadMXBean::getPeakThreadCount) (1) .baseUnit(BaseUnits.THREADS) // optional (2) .description("The peak live thread count...") // optional (3) .tags("key", "value") // optional (4) .register(registry); (5)1 jvm.threads.peakという新しいゲージを作成し、threadBean(ThreadMXBeanのインスタンス) でgetPeakThreadCountを呼び出します。2 基本単位を定義します。事前定義された値については BaseUnits.java を参照してください。 3 ゲージの説明を入力してください 4 ゲージに tags を関連付けます。 5 MeterRegistry にゲージを登録する
詳細と例については、Micrometer ドキュメントの Gauges を参照してください。特筆すべきは2つの特別なケースです: 時間を測定するための TimeGauge と、いくつかの基準をまとめて報告するための MultiGauge です。
Micrometer は、デフォルトでは監視対象のオブジェクトに対して強い参照を作成しません。レジストリーによっては、Micrometer はガベージコレクションが設定されたオブジェクトを監視するゲージを完全に省略するか、監視値として NaN (not a number) を使用します。
|
ゲージはいつ使用したらよいですか? 他のものを使用できない場合にのみゲージを使用してください。ゲージは他のメーターに比べて使い方が簡単ではない場合があります。測定対象をカウントできる場合 (値が常に増加するため) は、代わりにカウンターを使用します。
カウンター
カウンターは増加する値のみを測定します。カウンターを作成するには、以下のいずれかの方法を使用します。
-
MeterRegistryの便利なメソッドを使用します。registry.counter("example.prime.number", "type", "prime"); (1) (2)1 example.prime.numberはカウンター名です。2 typeは、値がprimeであるディメンションタグです。 -
説明と単位を指定するには、
Counter.builderを使用します。Counter.builder("count.me") (1) .baseUnit("beans") // optional (2) .description("a description") // optional (3) .tags("region", "test") // optional (4) .register(registry);1 count.meという新しいカウンターを作成します。2 カスタムベースユニットを定義します。事前定義された値については BaseUnits.java を参照してください。 3 カウンターの説明を入力してください 4 カウンターに タグ を関連付けます。 -
メソッドに アノテーションを付与 します。
@Counted(value = "counted.method", extraTags = { "extra", "annotated" }) (1) (2) void countThisMethod(){ ... }1 CDI インターセプターは counted.methodというカウンターを作成して登録します。2 インターセプターが作成したカウンターには、値が "annotated" の "extra" ディメンションタグが付きます。
常時増加する関数が返す結果を測定するために使用できる、あまり一般的でない FunctionCounter を含む、より詳細な情報と例については、Micrometer のドキュメントの カウンター を参照してください。
カウンターはいつ使用したらよいですか? 時間を計ったり要約したりできない作業の場合は、カウンターを使用します。値がどのように変化しているかを詳しく知りたい場合は、タイマー (測定の基本単位が時間の場合) またはディストリビューションサマリーの方が、より適切な場合もあります。
サマリーとタイマー
Micrometer のタイマーとディストリビューションサマリーは非常に似ています。両方のメーターはデータを記録し、追加のヒストグラムまたはパーセンタイルデータを取得できます。ディストリビューションサマリーは任意のタイプのデータに使用できますが、タイマーは時間と期間の測定に最適化されています。
タイマーとディストリビューションサマリーは、少なくとも 3 つの値を内部に保存します。
-
記録されたすべての値の合計としての集計
-
記録された値の数 (カウンター)
-
減少する時間ウィンドウ内で見られる最高値 (ゲージ)。
ディストリビューションサマリーの作成
ディストリビューションサマリーを使用して、時間ではなく値を記録します。ディストリビューションサマリーを作成するには、次のいずれかの方法を使用します。
-
MeterRegistryの便利なメソッドを使用します。registry.summary("bytes.written", "protocol", "http"); (1) (2)1 bytes.writtenはサマリー名です2 protocolは、値がhttpのディメンションタグです。 -
説明と単位を指定するには、
DistributionSummary.builderを使用します。DistributionSummary.builder("response.size") (1) .baseUnit("bytes") // optional (2) .description("a description") // optional (3) .tags("protocol", "http") // optional (4) .register(registry);1 response.sizeという新しいディストリビューションサマリーを作成します。2 基本単位として bytesを使用します。事前定義された値については BaseUnits.java を参照してください。3 ディストリビューションサマリーの説明を入力します 4 ディストリビューションサマリーに tags を関連付けます。
タイマーの作成
タイマーは、短時間のレイテンシーとその発生頻度を測定します。負の値はサポートされておらず、期間が長すぎると合計時間 (Long.MAX_VALUE ナノ秒 (292.3 年)) がオーバーフローする可能性があります。
タイマーを構築するには、次のいずれかのメソッドを使用します。
-
MeterRegistryの便利なメソッドを使用します。registry.timer("fabric.selection", "primary", "blue"); (1) (2)1 fabric.selectionはサマリー名です2 primaryは、値がblueのディメンションタグです。 -
説明と単位を指定するには、
Timer.builderを使用します。Timer.builder("my.timer") (1) (2) .description("description ") // optional (3) .tags("region", "test") // optional (4) .register(registry);1 my.timerという新しいタイマーを作成します。2 タイマーは時間を測定し、それをモニタリングバックエンドに必要な単位に変換します。 3 ディストリビューションサマリーの説明を入力します 4 タイマーに tags を関連付けます。 -
メソッドに アノテーションを付与 します。
@Timed(value = "call", extraTags = {"region", "test"}) (1) (2)1 CDI インターセプターは callと呼ばれるタイマーを作成して登録します。2 インターセプターが作成したタイマーには、値が "test" の "region" ディメンションタグが付きます。
タイマーによる期間の測定
Micrometer は、期間を記録するための以下の便利なメカニズムを提供します。
-
Runnableの呼び出しをラップします。timer.record(() -> noReturnValue()); -
Callableの呼び出しをラップします。timer.recordCallable(() -> returnValue()); -
繰り返される呼び出し用にラップされた
Runnableを作成します。Runnable r = timer.wrap(() -> noReturnValue()); -
繰り返される呼び出し用にラップされた
Callableを作成します。Callable c = timer.wrap(() -> returnValue()); -
より複雑なコードパスには
Sampleを使用します。Sample sample = Timer.start(registry); (1) doStuff; (2) sample.stop(registry.timer("my.timer", "response", response.status())); (3)1 タイマーの開始を記録するサンプルを作成します。 2 サンプルはコンテキストとして渡すことができます。 3 サンプルが停止されるときにタイマーを選択できます。この例では、処理が完了するまで不明な、タイマーを識別するタグとしてレスポンスステータスを使用します。
ヒストグラムとパーセンタイル
タイマーとディストリビューションサマリーの両方は、ヒストグラムデータ、事前に計算されたパーセンタイル、またはサービスレベル目標 (SLO) 境界などの追加の統計情報を出力するように設定できます。両方の種類のメモリフットプリントの推定を含む、詳細な情報と例については、Micrometer ドキュメントの Timers と Distribution Summaries を参照してください。
|
タイマーとディストリビューションサマリーに関連付けられたカウント、合計、およびヒストグラムのデータは、ディメンション間 (または一連のインスタンス間) で再集計できます。 事前計算されたパーセンタイル値は再集計できません。パーセンタイルは各データセットに固有です (この測定値のコレクションの 90 パーセンタイルなど)。 |
自動生成されるメトリクス
HTTP サーバー
Micrometer エクステンションは、HTTP サーバーリクエストの時間を自動的に計測します。Prometheus のタイマーの命名規則に従い、http_server_requests_seconds_count、http_server_requests_seconds_sum、http_server_requests_seconds_max を参照してください。要求された URI、HTTP メソッド (GET、POST など)、ステータスコード (200、302、404 など)、そしてより一般的な結果フィールドのために、次元ラベルが追加されています。
quarkus.micrometer.binder.http-server.ignore-patterns プロパティーを使用して、HTTP エンドポイントの測定を無効にすることができます。このプロパティーは、無視すべき URI パスを識別する単純な正規表現マッチパターンをコンマ区切りでリストとして受け入れます。例えば、quarkus.micrometer.binder.http-server.ignore-patterns=/example/prime/[0-9]+ を設定すると、http://localhost:8080/example/prime/7919 へのリクエストは無視されます。http://localhost:8080/example/gauge/7919 へのリクエストは、引き続き測定されます。
Micrometer エクステンションは、パスパラメーターを含む URI をテンプレート形式で表現するよう最大限努力します。上記の例を使用すると、http://localhost:8080/example/prime/7919 へのリクエストは、http_server_requests_seconds_* メトリクスの属性として uri=/example/prime/{number} の値で表示されるはずです。
正しい URL が特定できない場合は、 quarkus.micrometer.binder.http-server.match-patterns プロパティを使用します。このプロパティには、単純な正規表現マッチパターンと置換文字列との関連を定義するカンマ区切りのリストを指定できます。たとえば、 quarkus.micrometer.binder.http-server.match-patterns=/example/prime/[0-9]+=/example/{jellybeans} を設定すると、要求された uri が /example/prime/[0-9]+ に一致した場合、uri 属性に /example/{jellybeans} の値が使用されます。
デフォルトでは、メトリクスは Prometheus 形式の application/openmetrics-text を使用してエクスポートされます。Accept リクエストヘッダーを text/plain (curl -H "Accept: text/plain" localhost:8080/q/metrics/) に指定することで、以前の形式に戻すことができます。
Netty メモリ管理メトリクス
Netty のメモリ管理メトリクスは重要です。なぜなら、Quarkus は Eclipse Vert.x 上に構築されており、Vert.x は Java でリアクティブアプリケーションを作成するために Netty 上に構築されたフレームワークだからです。Quarkus で命令型プログラミングスタイルを使用する場合でも、内部的には Vert.x によってリアクティブな方法で便利に処理されます。
要するに、Netty は 効率的な メモリ管理システムを非同期アプリケーション向けに提供します。これは、ヒープ (JVM ヒープに保存される) や直接メモリ (JVM メモリの外部に割り当てられる) を含むさまざまな種類のメモリ割り当て戦略と、割り当てを最適化し、ガベージコレクション (GC) のオーバーヘッドを削減するための バッファー プーリング メカニズム を提供します。
Nettyにおけるメモリカテゴリー
Nettyは主に2つのメモリカテゴリーを使用します。
-
ヒープメモリ
-
JVMヒープ (
byte[]) から割り当てられます。 -
ガベージコレクターによって管理されます。
-
ソケット経由で送信する前にデータをダイレクトメモリにコピーする必要があるため、I/O 操作が遅くなります。
-
-
ダイレクトメモリ
-
ByteBuffer.allocateDirect()を使用して JVM ヒープ外に割り当てられます。 -
ガベージコレクターによって管理されないため、GCの負荷を軽減します。
-
不要なコピーを回避するため、I/O 操作が高速です。
-
|
-XX:MaxRAMPercentage に非常に高い値を使用すること (利用可能なRAMのほとんどをJavaヒープに割り当てること) は、Nettyのネイティブメモリ割り当て用の領域を残すことが重要であるため、Quarkusアプリケーションでは推奨されません。 これらのNettyメトリクスは、どのくらいの領域が必要かを評価するのに役立ちます。 |
プーリングメカニズム
Nettyは、メモリ割り当てのオーバーヘッドとフラグメンテーションを削減するために PooledByteBufAllocator を使用します。これは、jemallocスタイルのアリーナシステム (参照: jemalloc/jemalloc) に基づいており、以下を含みます。
-
アリーナ: 割り当てを管理する大きなメモリブロック。
-
チャンク: アリーナ内のメモリセグメント (通常サイズは16MB)。
-
ページ: チャンクの固定サイズ部分 (通常は8KB)。
-
サブページ: 小さいオブジェクト用のページ内のより小さな割り当て。
-
スレッドローカルキャッシュ: 頻繁に使用される小さなバッファー用のスレッドごとのキャッシュで、競合を軽減します。
Nettyメモリ管理のメトリクス
Micrometerメトリクスは、Nettyのアロケーターからの主要なメトリクスを報告し、メモリ使用量、固定メモリ、プーリング効率、キャッシュ動作の監視に役立ちます。
1. メモリ使用量メトリクス (すべてのアロケーター)
これらのメトリクスは、Nettyアロケーターによる現在のメモリ使用量 (バイト単位) を追跡します。
| メトリクス名 | 説明 | タイプ | タグ |
|---|---|---|---|
|
アロケーターによって現在使用されているメモリ量 |
ゲージ |
|
2. プール型アロケーター - 固定メモリメトリクス
固定メモリとは、アクティブな参照があるためリサイクルできず、アロケーターによる再利用を妨げるバッファーを指します。 多い 数は、何らかのリーク (参照が解放されていないため) を示している可能性があります。
| メトリクス名 | 説明 | タイプ | タグ |
|---|---|---|---|
|
再利用できない固定メモリの量 |
ゲージ |
|
3. プール型アロケーター - アリーナメトリクス
アリーナ (大きなサイズのメモリ) は、メモリチャンクをグループ化することでメモリ割り当てを効率的に管理します。したがって、このメトリクスは、特定のアロケーターに割り当てられたアリーナの数です。
| メトリクス名 | 説明 | タイプ | タグ |
|---|---|---|---|
|
メモリ割り当てを処理するアリーナの数 |
ゲージ |
|
4. キャッシュサイズメトリクス
Nettyは、頻繁なメモリ割り当てを回避し、パフォーマンスを向上させるために、特定のThread内に小さなバッファーをキャッシュします。同じスレッドがメモリを必要とする場合、まず自身のキャッシュをチェックします。これは、イベントループスレッドモデル (スレッド数が少ない) のおかげで特に効率的です。なお、現在、tinyキャッシュはsmallキャッシュにマージされています。
| メトリクス名 | 説明 | タイプ | タグ |
|---|---|---|---|
|
バッファーキャッシュのサイズ |
ゲージ |
|
アンプール
これは、新しいバッファーを直接作成し、プーリングメカニズムをバイパスするための静的メソッドを提供するユーティリティークラスを使用します。ユーザーは割り当てられたバッファーも解放する必要があります。
|
|
デバッグ
高い割り当て値が報告された場合、それが実際のメモリーリークであるかどうかを判断する方法は 2 つあります。
-
Netty で文書化されているように、 リーク検出 を有効にすることで。例:
java -Dio.netty.leakDetection.level=advanced ...
-
アプリケーションからのメモリーダンプを検査する。
Micrometer で自動的に計装される Quarkus コアエクステンションのリスト
-
jboss-logging(Quarkus の logging API) -
-
AMQP 1.0
-
RabbitMQ
-
Kafka
-
Pulsar
-
JMS
-
MQTT
-
Camel メッセージング
-
-
quarkus-vertx(HTTP リクエスト)
Micrometer のカスタマイズ
Quarkus は Micrometer をカスタマイズするためのさまざまな方法を提供します。
MeterFilter を使用した発行されるタグとメトリクスのカスタマイズ
Micrometer は MeterFilter インスタンスを使用して、MeterRegistry インスタンスが出力するメトリクスをカスタマイズします。Micrometer エクステンションは MeterFilter CDI Bean を検出し、MeterRegistry インスタンスを初期化する際にそれを使用します。
@Singleton
public class CustomConfiguration {
@ConfigProperty(name = "deployment.env")
String deploymentEnv;
/** Define common tags that apply only to a Prometheus Registry */
@Produces
@Singleton
@MeterFilterConstraint(applyTo = PrometheusMeterRegistry.class)
public MeterFilter configurePrometheusRegistries() {
return MeterFilter.commonTags(Arrays.asList(
Tag.of("registry", "prometheus")));
}
/** Define common tags that apply globally */
@Produces
@Singleton
public MeterFilter configureAllRegistries() {
return MeterFilter.commonTags(Arrays.asList(
Tag.of("env", deploymentEnv)));
}
/** Enable histogram buckets for a specific timer */
@Produces
@Singleton
public MeterFilter enableHistogram() {
return new MeterFilter() {
@Override
public DistributionStatisticConfig configure(Meter.Id id, DistributionStatisticConfig config) {
if(id.getName().startsWith("myservice")) {
return DistributionStatisticConfig.builder()
.percentiles(0.5, 0.95) // median and 95th percentile, not aggregable
.percentilesHistogram(true) // histogram buckets (e.g. prometheus histogram_quantile)
.build()
.merge(config);
}
return config;
}
};
}
}
この例では、シングルトン CDI Bean が 2 つの異なる MeterFilter Bean を生成します。1 つは Prometheus MeterRegistry インスタンスにのみ適用され ( @MeterFilterConstraint 修飾子を使用)、もう 1 つはすべての MeterRegistry インスタンスに適用されます。アプリケーション設定プロパティーも注入され、タグ値として使用されます。MeterFilters のその他の例は、公式ドキュメント にあります。
サーバー HTTP リクエストに対する HttpServerMetricsTagsContributor の使用
io.quarkus.micrometer.runtime.HttpServerMetricsTagsContributor を実装する CDI Bean を提供することで、ユーザーコードは HTTP リクエストとレスポンスの詳細に基づいて任意のタグを提供できます。
| このインターフェイスを使用してタグを作成する場合、値のカーディナリティーを制限することが重要です。そうしないと、メトリクスシステムの容量を著しく低下させるリスクがあります。 |
クライアント HTTP リクエストに対する HttpClientMetricsTagsContributor の使用
io.quarkus.micrometer.runtime.HttpClientMetricsTagsContributor を実装する CDI Bean を提供することで、ユーザーコードは HTTP リクエストの詳細に基づいて任意のタグを提供できます。
メーターレジストリーの任意のカスタマイズに MeterRegistryCustomizer を使用
io.quarkus.micrometer.runtime.MeterRegistryCustomizer を実装する CDI Bean を提供することで、ユーザーコードはアクティブ化された任意の MeterRegistry の設定を変更できます。実装に @io.quarkus.micrometer.runtime.MeterRegistryCustomizerConstraint アノテーションが付与されていない限り、このカスタマイズはすべての MeterRegistry インスタンスに適用されます。
Micrometer のアノテーション対応
Micrometer は、メソッドに追加できる2つのアノテーション、 @Counted と @Timed を定義しています。 @Timed アノテーションは、メソッドの実行をラップし、アノテーション自体に定義されているタグに加えて、次のタグを出力します。class、method、および exception (「none」または検出された例外の簡易クラス名)。
@Counted および @Timed のパラメーターには、意味のあるタグ値を動的に割り当てるために @MeterTag アノテーションを付けることができます。
MeterTag.resolver は、メソッドのパラメーターからタグを抽出するために使用できます。これは、 io.micrometer.common.annotation.ValueResolver を実装する Bean を作成し、そのクラスを参照することによって行われます: @MeterTag(resolver=CustomResolver.class)
MeterTag.expression もサポートされていますが、式を評価できる io.micrometer.common.annotation.ValueExpressionResolver を実装する Bean を作成することで、式の評価を実装する必要があります。
enum Currency { USD, EUR }
@Singleton
class EnumOrdinalResolver implements ValueResolver {
@Override
public String resolve(Object parameter) {
if(parameter instanceof Enum) {
return String.valueOf(((Enum<?>) parameter).ordinal());
}
return null;
}
}
@Singleton
public class MyExpressionResolver implements ValueExpressionResolver {
@Override
public String resolve(String expression, Object parameter) {
return someParser.parse(expression).evaluate(parameter);
}
}
// tags = type=with_enum, currency=${currency.toString()}
@Timed(value="time_something", extraTags = {"type", "with_enum"})
public Something calculateSomething(@MeterTag Currency currency) { ... }
// tags = type=with_enum, the_currency=${currency.toString()}
@Timed(value="time_something", extraTags = {"type", "with_enum"})
public Something calculateSomething(@MeterTag(key="the_currency") Currency currency) { ... }
// tags = type=with_enum, currency=${currency.ordinal()}
@Timed(value="time_something", extraTags = {"type", "with_enum"})
public Something calculateSomething(@MeterTag(resolver=EnumOrdinalResolver.class) Currency currency) { ... }
// tags = type=with_enum, currency=${currency.ordinal()}
@Timed(value="time_something", extraTags = {"type", "with_enum"})
public Something calculateSomething(@MeterTag(expression="currency.ordinal()") Currency currency) { ... }
| 提供されるタグ値は、低カーディナリティーである必要があります。高カーディナリティー値は、メトリクスバックエンドでパフォーマンスおよびストレージの問題 (「カーディナリティーの爆発」) を引き起こす可能性があります。タグ値には、高カーディナリティーになる可能性があるため、エンドユーザーデータを使用しないでください。 |
REST エンドポイントメソッドや Vert.x Routes などの多くのメソッドは、すぐに使用できる Micrometer エクステンションによってカウントされ、時間が計測されます。
管理インターフェース
デフォルトでは、メトリクスはメイン HTTP サーバーで公開されます。
アプリケーション設定で quarkus.management.enabled=true を設定することで、別のネットワークインターフェースとポートで公開できます。このプロパティーはビルド時のプロパティーであることに注意してください。この値は実行時にオーバーライドできません。
管理ネットワークインターフェースとポートをカスタマイズせずに管理インターフェースを有効にした場合、メトリクスは http://0.0.0.0:9000/q/metrics で公開されます。
公開される各形式のパスは、以下を使用して設定できます。
quarkus.micrometer.export.json.enabled=true (1)
quarkus.micrometer.export.json.path=metrics/json
quarkus.micrometer.export.prometheus.path=metrics/prometheus
| 1 | JSON メトリクスの有効化 |
このような設定にすると、JSON メトリクスは http://0.0.0.0:9000/q/metrics/json から利用可能になります。Prometheus メトリクスは http://0.0.0.0:9000/q/metrics/prometheus から利用可能になります。
詳しくは、 管理インターフェースのリファレンス を参照してください。
設定リファレンス
ビルド時に固定される設定プロパティー - 他のすべての設定プロパティーは実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
|---|---|---|
Micrometer metrics support. Micrometer metrics support is enabled by default. Environment variable: Show more |
boolean |
|
Micrometer MeterRegistry discovery. Micrometer MeterRegistry implementations discovered on the classpath will be enabled automatically by default. Environment variable: Show more |
boolean |
|
Micrometer MeterBinder discovery. In other words, enables the automatic metrics instrumentation. Micrometer MeterBinder implementations discovered on the classpath will be enabled automatically by default. In other words, automatic metrics instrumentation will be ON by default.
Environment variable: Show more |
boolean |
|
Outbound HTTP request metrics support. Support for HTTP client metrics will be enabled if Micrometer support is enabled, the REST client feature is enabled, and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Inbound HTTP metrics support. Support for HTTP server metrics will be enabled if Micrometer support is enabled, an extension serving HTTP traffic is enabled, and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Micrometer JVM metrics support. Support for JVM metrics will be enabled if Micrometer support is enabled, and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Kafka metrics support. Support for Kafka metrics will be enabled if Micrometer support is enabled, the Kafka Consumer or Producer interface is on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Redis client metrics support. Support for Redis metrics will be enabled if Micrometer support is enabled, the Quarkus Redis client extension is on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Stork metrics support. Support for Stork metrics will be enabled if Micrometer support is enabled, the Quarkus Stork extension is on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
gRPC Server metrics support. Support for gRPC server metrics will be enabled if Micrometer support is enabled, the gRPC server interfaces are on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
gRPC Client metrics support. Support for gRPC client metrics will be enabled if Micrometer support is enabled, the gRPC client interfaces are on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Kafka metrics support. Support for Reactive Messaging metrics will be enabled if Micrometer support is enabled, MessageObservationCollector interface is on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Virtual Threads metrics support. Support for virtual threads metrics will be enabled if Micrometer support is enabled, this value is set to Environment variable: Show more |
boolean |
|
The tags to be added to the metrics. Empty by default. When set, tags are passed as: Environment variable: Show more |
文字列のリスト |
|
Micrometer System metrics support. Support for System metrics will be enabled if Micrometer support is enabled, and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Vert.x metrics support. Support for Vert.x metrics will be enabled if Micrometer support is enabled, Vert.x MetricsOptions is on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Netty metrics support. Support for Netty metrics will be enabled if Micrometer support is enabled, the Netty allocator classes are on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
Enable all binders. Activates all metrics regardless off their particular default. This property has precedence over all Also takes precedence over Environment variable: Show more |
boolean |
|
Support for export to JSON format. Off by default. Environment variable: Show more |
boolean |
|
The path for the JSON metrics endpoint. The default value is Environment variable: Show more |
string |
|
Statistics like max, percentiles, and histogram counts decay over time to give greater weight to recent samples. Samples are accumulated to such statistics in ring buffers which rotate after the expiry, with this buffer length. Environment variable: Show more |
int |
|
Statistics like max, percentiles, and histogram counts decay over time to give greater weight to recent samples. Samples are accumulated to such statistics in ring buffers which rotate after this expiry, with a particular buffer length. Environment variable: Show more |
|
|
Support for export to Prometheus. Support for Prometheus will be enabled if Micrometer support is enabled, the PrometheusMeterRegistry is on the classpath and either this value is true, or this value is unset and Environment variable: Show more |
boolean |
|
The path for the prometheus metrics endpoint (produces text/plain). The default value is
If the management interface is enabled, the value will be resolved as a path relative to
Environment variable: Show more |
string |
|
By default, this extension will create a Prometheus MeterRegistry instance. Use this attribute to veto the creation of the default Prometheus MeterRegistry. Environment variable: Show more |
boolean |
|
Comma-separated list of regular expressions used to specify uri labels in http metrics. Outbount HTTP client instrumentation will attempt to transform parameterized
resource paths, Patterns specified here will take precedence over those computed values. For example, if Environment variable: Show more |
文字列のリスト |
|
Comma-separated list of regular expressions defining uri paths that should be ignored (not measured). Environment variable: Show more |
文字列のリスト |
|
Suppress 4xx errors from metrics collection for unmatched templates. This configuration exists to limit cardinality explosion from caller side errors. Does not apply to 404 errors. Suppressing 4xx errors is disabled by default. Environment variable: Show more |
boolean |
|
Maximum number of unique URI tag values allowed. After the max number of tag values is reached, metrics with additional tag values are denied by filter. Environment variable: Show more |
int |
|
Comma-separated list of regular expressions used to specify uri labels in http metrics. Vertx instrumentation will attempt to transform parameterized
resource paths, Patterns specified here will take precedence over those computed values. For example, if Environment variable: Show more |
文字列のリスト |
|
Comma-separated list of regular expressions defining uri paths that should be ignored (not measured). Environment variable: Show more |
文字列のリスト |
|
Suppress non-application uris from metrics collection.
This will suppress all metrics for non-application endpoints using
Suppressing non-application uris is enabled by default. Environment variable: Show more |
boolean |
|
Suppress 4xx errors from metrics collection for unmatched templates. This configuration exists to limit cardinality explosion from caller side error. Does not apply to 404 errors. Suppressing 4xx errors is disabled by default. Environment variable: Show more |
boolean |
|
Maximum number of unique URI tag values allowed. After the max number of tag values is reached, metrics with additional tag values are denied by filter. Environment variable: Show more |
int |
|
Prometheus registry configuration properties. A property source for configuration of the Prometheus MeterRegistry, see https://micrometer.io/docs/registry/prometheus. Environment variable: Show more |
Map<String,String> |
|
This property is deprecated: use Comma-separated list of regular expressions used to specify uri labels in http metrics. Vertx instrumentation will attempt to transform parameterized
resource paths, Patterns specified here will take precedence over those computed values. For example, if Environment variable: Show more |
文字列のリスト |
|
This property is deprecated: use Comma-separated list of regular expressions defining uri paths that should be ignored (not measured). Environment variable: Show more |
文字列のリスト |
|
期間フォーマットについて
期間の値を書くには、標準の 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|