Micrometer および OpenTelemetry エクステンション
previewこのエクステンションは、 Quarkus アプリケーションにおける Micrometer と OpenTelemetry 両方のサポートを提供します。 両方のエクステンションを、 Micrometer メトリクスを OpenTelemetry 経由で送信可能にするブリッジとともに組み込むことで、 統合を合理化します。
|
この技術は、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 によって処理され、 quarkus-opentelemetry エクステンションのエクスポーターを使用して OTLP プロトコルで送信されます。
これにより、 quarkus-micrometer と quarkus-opentelemetry エクステンションを個別に独立して使用する場合に生じる、 同一アプリケーション内での独立した Micrometer レジストリと OpenTelemetry SDK の両方をメモリに保持するオーバーヘッドが削減されます。
OpenTelemetry SDK がすべてのメトリクスを処理します。 Micrometer メトリクス (手動または自動) と OpenTelemetry メトリクスの両方を使用できます。 この単一のエクステンションですべて利用可能です。
OpenTelemetry および Micrometer エクステンションのすべての設定は、 quarkus-micrometer-opentelemetry で利用可能です。
このブリッジは、 Quarkiverse にある単純な OTLP レジストリ以上のものです。 このエクステンションでは、 OpenTelemetry SDK が 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 は Timer を使用し、 OpenTelemetry は Histogram を使用することです。
Micrometer で @Timed アノテーションを使用すると、 OpenTelemetry 側で 2 つの異なるメトリクスが作成されます。 1 つは max 値用の Gauge で、 もう 1 つは Histogram です。
Micrometer の DistributionSummary は、 Histogram と max 値用の DoubleGauge に変換されます。 DistributionSummary の作成時にサービスレベル目標 (slo) が true に設定されている場合、 それらに対して追加のヒストグラムが作成されます。
この表は、 2 つのフレームワーク間の違いを示しています。
| Micrometer | OpenTelemetry |
|---|---|
DistributionSummary |
|
SLO 付きの DistributionSummary |
|
LongTaskTimer |
|
Timer |
|
セマンティックコンベンションの違い
2 つのフレームワークは異なるセマンティックコンベンションに従っています。 OpenTelemetry メトリクスは OpenTelemetry Semantic Conventions に基づいており、 現在も活発に開発されています (2025 年初頭時点)。 一方、 Micrometer のメトリクスコンベンション形式は古くから存在し、 あまり変化していません。
application.properties ファイルにこれら 2 つの設定が行われている場合。
quarkus.micrometer.binder.jvm=true
quarkus.micrometer.binder.http-server.enabled=trueJVM および HTTP サーバーのメトリクスは Micrometer によって収集されます。
次に、 Micrometer によって収集されたメトリクスの例として、 quarkus-micrometer-registry-prometheus エンドポイントの出力 (/q/metrics) と、 このブリッジでの OTLP プロトコル出力の比較を示します。
対応する OpenTelemetry Semantic Convention へのリンクも参考として提供されていますが、 現在このブリッジでは使用されていません。
| Micrometer Meter Java 定義 | Quarkus Micrometer Prometheus 出力 (/q/metrics/ での表示) |
本ブリッジの OpenTelemetry 出力名 (OTLP 出力での表示) | 関連する OpenTelemetry Semantic Convention (適用外) |
|---|---|---|---|
@Timed インターセプターを使用する場合。 |
method.timed (Histogram), method.timed.max (DoubleGauge) |
該当なし |
|
@Counted インターセプターを使用する場合。 |
method.counted (DoubleSum) |
該当なし |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
該当なし |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
該当なし |
|
|
|
|
データが含まれていない場合、 一部のメトリクスが出力から欠落することがあります。 |
出力の確認
Grafana-OTel-LGTM Dev Service
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>
