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=trueapplication.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=trueJVM および HTTP サーバーのメトリクスは Micrometer によって収集されます。
Next, are examples of the metrics collected by Micrometer compared with what would be the quarkus-micrometer-registry-prometheus endpoint output (/q/metrics) vs the OTLP protocol output on this bridge.
A link to the equivalent OpenTelemetry Semantic Convention is also provided for reference and is not currently used by the bridge.
| Micrometer Meter Java definition | Quarkus Micrometer Prometheus output (as seen at /q/metrics/) |
This bridge OpenTelemetry output name (as seen in the OTLP output) | 関連する OpenTelemetry セマンティック規約 (適用されません) |
|---|---|---|---|
Using the @Timed interceptor. |
method.timed (Histogram), method.timed.max (DoubleGauge) |
該当なし |
|
Using the @Counted interceptor. |
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>
