Version:

Micrometer and OpenTelemetry extension

このエクステンションは、Quarkus アプリケーションで Micrometer と OpenTelemetry の両方をサポートします。OpenTelemetry 経由で Micrometer メトリクスを送信できるようにするブリッジとともに両方のエクステンションを組み込むことでインテグレーションを効率化します。

このドキュメントは、 QuarkusのObservabilityリファレンスガイドの一部です。

このエクステンションは、Quarkus バージョン 3.19 以降で利用できます。
Micrometer エクステンションの詳細は、Micrometer ガイドを参照してください。
OpenTelemetry ガイドには、OpenTelemetry エクステンションに関する情報が記載されています。

このエクステンションにより、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 をメモリー内に保持することによるオーバーヘッドが削減されます。

Using a Micrometer registry (such as quarkus-micrometer-registry-prometheus) together with OpenTelemetry metrics collects the same measurements twice. Quarkus logs a build-time warning in that case. See Avoiding redundant metrics collection for the available options, including this extension.

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 エクステンションをプロジェクトに追加できます。

CLI

quarkus extension add micrometer-opentelemetry

Maven

./mvnw quarkus:add-extension -Dextensions='micrometer-opentelemetry'

Gradle

./gradlew addExtension --extensions='micrometer-opentelemetry'

これにより、ビルドファイルに以下が追加されます:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-opentelemetry</artifactId>
</dependency>

build.gradle

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

Micrometer	OpenTelemetry
DistributionSummary	`<Metric name>` (Histogram), `<Metric name>.max` (DoubleGauge)
SLO による分布サマリー	`<Metric name>` (Histogram), `<Metric name>.max` (DoubleGauge), `<Metric name>.histogram` (DoubleGauge)
LongTaskTimer	`<Metric name>.active` (ObservableLongUpDownCounter), `<Metric name>.duration` (ObservableDoubleUpDownCounter)
Timer	`<Metric name>` (Histogram), `<Metric name>.max` (ObservableDoubleGauge)

DistributionSummary

<Metric name> (Histogram), <Metric name>.max (DoubleGauge)

SLO による分布サマリー

<Metric name> (Histogram), <Metric name>.max (DoubleGauge), <Metric name>.histogram (DoubleGauge)

LongTaskTimer

<Metric name>.active (ObservableLongUpDownCounter), <Metric name>.duration (ObservableDoubleUpDownCounter)

Timer

<Metric name> (Histogram), <Metric name>.max (ObservableDoubleGauge)

意味上の慣習の違い

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 エンドポイントの出力 (/q/metrics) と、このブリッジでの OTLP プロトコル出力の比較を示します。

対応する OpenTelemetry Semantic Convention へのリンクも参考として提供されていますが、現在このブリッジでは使用されていません。

Table 1. Micrometer メトリクス出力比較。 Prometheus レジストリ対 OpenTelemetry ブリッジ
Micrometer Meter Java 定義	Quarkus Micrometer Prometheus client v0.x output (as seen at `/q/metrics/`)	本ブリッジの OpenTelemetry 出力名 (OTLP 出力での表示)	関連する OpenTelemetry セマンティック規約 (適用されません)
@Timed インターセプターを使用する場合。		method.timed (Histogram), method.timed.max (DoubleGauge)	該当なし
@Counted インターセプターを使用する場合。		method.counted (DoubleSum)	該当なし
`http.server.active.requests` (Gauge)	`http_server_active_requests` (Gauge)	`http.server.active.requests` (DoubleGauge)	`http.server.active_requests` (UpDownCounter)
`http.server.requests` (Timer)	`http_server_requests_seconds_count`, `http_server_requests_seconds_sum`, `http_server_requests_seconds_max` (Gauge)	`http.server.requests` (Histogram), `http.server.requests.max` (DoubleGauge)	`http.server.request.duration` (Histogram)
`http.server.bytes.read` (DistributionSummary)	`http_server_bytes_read_count`, `http_server_bytes_read_sum` , `http_server_bytes_read_max` (Gauge)	`http.server.bytes.read` (Histogram), `http.server.bytes.read.max` (DoubleGauge)	`http.server.request.body.size` (Histogram)
`http.server.bytes.write` (DistributionSummary)	`http_server_bytes_write_count`, `http_server_bytes_write_sum` , `http_server_bytes_write_max` (Gauge)	`http.server.bytes.write` (Histogram), `http.server.bytes.write.max` (DoubleGauge)	`http.server.response.body.size` (Histogram)
`http.server.connections` (LongTaskTimer)	`http_server_connections_seconds_active_count`, `http_server_connections_seconds_duration_sum` `http_server_connections_seconds_max` (Gauge)	`http.server.connections.active` (LongSum), `http.server.connections.duration` (DoubleGauge)	N/A
`jvm.threads.live` (Gauge)	`jvm_threads_live_threads` (Gauge)	`jvm.threads.live` (DoubleGauge)	`jvm.threads.live` (UpDownCounter)
`jvm.threads.started` (FunctionCounter)	`jvm_threads_started_threads_total` (Counter)	`jvm.threads.started` (DoubleSum)	`jvm.threads.live` (UpDownCounter)
`jvm.threads.daemon` (Gauge)	`jvm_threads_daemon_threads` (Gauge)	`jvm.threads.daemon` (DoubleGauge)	`jvm.threads.live` (UpDownCounter)
`jvm.threads.peak` (Gauge)	`jvm_threads_peak_threads` (Gauge)	`jvm.threads.peak` (DoubleGauge)	N/A
`jvm.threads.states` (ステートごとの Gauge)	`jvm_threads_states_threads` (Gauge)	`jvm.threads.states` (DoubleGauge)	`jvm.threads.live` (UpDownCounter)

一部のメトリクスは、データが含まれていない場合、出力に含まれない可能性があります。

出力を参照してください。

Metrics in the Dev UI

In dev mode, the Observability Metrics view in the Dev UI charts your live metrics. With the bridge active, Micrometer meters forwarded into the OpenTelemetry SDK, as well as native OpenTelemetry metrics, are captured once (from OpenTelemetry) — so there are no duplicate series. See Metrics in the Dev UI for details.

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>