Micrometer と OpenTelemetry エクステンション
このエクステンションは、Quarkus アプリケーションで Micrometer と OpenTelemetry の両方をサポートします。OpenTelemetry 経由で Micrometer メトリクスを送信できるようにするブリッジとともに両方のエクステンションを組み込むことでインテグレーションを効率化します。
この技術は、previewと考えられています。 preview では、下位互換性やエコシステムでの存在は保証されていません。具体的な改善には設定や API の変更が必要になるかもしれませんが、 stable になるための計画は現在進行中です。フィードバックは メーリングリスト や GitHub の課題管理 で受け付けています。 とりうるステータスの完全なリストについては、 FAQの項目 を参照してください。 |
このドキュメントは、オブザーバビリティコンポーネントとその他のオブザーバビリティ関連コンポーネントを取り上げている Quarkus のオブザーバビリティリファレンスガイド の一部です。
|
このエクステンションにより、Micrometer API の通常の使用が可能になりますが、メトリクスは OpenTelemetry エクステンションによって処理されます。
たとえば、Micrometer の @Timed
アノテーションは、メソッドの実行時間を測定するために使用します。
import io.micrometer.core.annotation.Timed;
//...
@Timed(name = "timer_metric")
public String timer() {
return "OK";
}
出力テレメトリーデータは OpenTelemetry SDK によって処理され、OTLP プロトコルを使用して quarkus-opentelemetry
エクステンションエクスポーターによって送信されます。
これにより、quarkus-micrometer
エクステンションと quarkus-opentelemetry
エクステンションの両方が独立して使用される場合に、同じアプリケーションに対して独立した Micrometer レジストリーと OpenTelemetry SDK をメモリー内に保持することによるオーバーヘッドが削減されます。
OpenTelemetry SDK はすべてのメトリクスを処理します。 Micrometer メトリクス (手動または自動) と OpenTelemetry メトリクスのいずれかを使用できます。この単一のエクステンションですべてが利用できます。
OpenTelemetry および Micrometer エクステンションのすべての設定は、quarkus-micrometer-opentelemetry
で利用できます。
このブリッジは、Quarkiverse にある単純な OTLP レジストリー以上のものです。このエクステンションでは、OpenTelemetry SDK は、https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/micrometer/micrometer-1.5/library[micrometer/micrometer-1.5
] OpenTelemetry 計装ライブラリーに基づく Micrometer レジストリー実装を提供します。
使用法
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")
設定
エクステンションが存在する場合、Micrometer は、OpenTelemetry トレース、メトリクス、ログと同様にデフォルトで有効になります。
HTTP サーバーおよび JVM メトリクスの OpenTelemetry メトリクス自動計装は、Micrometer によって収集できるため、デフォルトでは無効になっています。
特定の自動 Micrometer メトリクスはすべてデフォルトで無効になっていますが、設定によって有効にできます。たとえば、JVM メトリクスの場合:
quarkus.micrometer.binder.jvm=true
application.properties
ファイルは以下のとおりです。
このプロパティーやエクステンションで使用できるその他のプロパティーについては、以下を参照してください。
Micrometer と OpenTelemetry のメトリクスの違い
API の違い
各フレームワークで生成されるメトリクスは異なる API に従うため、マッピングは 1:1 ではありません。
基本的な API の違いの 1 つは、Micrometer は タイマー を使用し、OpenTelemetry は ヒストグラム を使用して、レイテンシー (実行時間) メトリクスとイベントの頻度を記録する点です。
Micrometer で @Timed
アノテーションを使用する場合、2 つの異なるメトリクスが OpenTelemetry 側で作成 されます。1 つは、max
値用の Gauge
、もう 1 つが Histogram
です。
Micrometer の DistributionSummary
は、max
値の Histogram
と DoubleGauge
に変換されます。DistributionSummary
の作成時にサービスレベル目標 (slo) が true
に設定されている場合、追加のヒストグラムが作成されます。
この表は、2 つのフレームワークの違いを示しています。
Micrometer | OpenTelemetry |
---|---|
DistributionSummary |
|
SLO による分布サマリー |
|
LongTaskTimer |
|
Timer |
|
意味上の慣習の違い
2 つのフレームワークは、異なるセマンティック規則に従います。OpenTelemetry メトリクスは、https://opentelemetry.io/docs/concepts/semantic-conventions/[OpenTelemetry Semantic Conventions] に基づいており、現在も活発に開発中です (2025 年初頭)。Micrometer メトリクス規則の形式は長い間使用されており、あまり変更されていません。
application.properties
ファイルで次の 2 つの設定が指定されている場合:
quarkus.micrometer.binder.jvm=true
quarkus.micrometer.binder.http-server.enabled=true
JVM および HTTP サーバーのメトリクスは Micrometer によって収集されます。
次に、Micrometer によって収集されたメトリクスの例と、quarkus-micrometer-registry-prometheus
の出力とこのブリッジの出力の比較を示します。同等の OpenTelemetry セマンティックコンベンションへのリンクも参照用に提供されていますが、これは現在ブリッジでは使用されていません。
マイクロメーターのメトリクス | Quarkus Micrometer Prometheus の出力 | このブリッジの OpenTelemetry 出力名 | 関連する OpenTelemetry セマンティック規約 (適用されません) |
---|---|---|---|
@Timed インターセプターの使用。 |
method.timed (Histogram), method.timed.max (DoubleGauge) |
該当なし |
|
@Counted インターセプターの使用。 |
method.counted (DoubleSum) |
該当なし |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
該当なし |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
該当なし |
|
|
|
|
一部のメトリクスは、データが含まれていない場合、出力に含まれない可能性があります。 |
出力を参照してください。
Grafana-OTel-LGTM 開発サービス
Grafana-OTel-LGTM Dev Service を使用できます。
この Dev Service には、データを視覚化する Grafana、ログを保存する Loki、トレースを保存する Tempo、メトリクスを保存する Prometheus が含まれています。 また、データを受信する OTel コレクターも提供します。
Logging エクスポーター
application.properties
ファイルでエクスポーターを logging
に設定して、すべてのメトリクスをコンソールに出力できます。
quarkus.otel.metrics.exporter=logging (1)
quarkus.otel.metric.export.interval=10000ms (2)
1 | エクスポーターを logging に設定します。
通常、これを設定する必要はありません。
デフォルトは cdi です。 |
2 | メトリクスのエクスポート間隔を設定します。
デフォルトは 1m ですが、デバッグには長すぎます。 |
次の依存関係もプロジェクトに追加します。
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-logging</artifactId>
</dependency>