原文はこちら。
The original article was written by Tim Quinn (Consulting Member of Technical Staff at Oracle).
https://medium.com/helidon/using-exemplars-in-helidon-metrics-56dbf70e972c

OpenMetrics（Prometheus）メトリクス・フォーマットでは、Helidonのようなメトリクス・プロバイダーがメトリクスの出力にオプションの文字列を追加できます。

OpenMetrics, a cloud-native, highly scalable metrics protocol
https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md

これらの文字列はexemplar（見本）、つまりメトリックで表されるすべてのサンプルのうち、ある意味典型的なサンプルを表しています。特に、メトリックの見本となる文字列は、多くの場合、そのメトリックの更新のきっかけとなったアプリケーションでのサービスの実際の使用に関するトレースを示します。

Helidon 2.3.0以降、Helidon SEまたはMPアプリケーションのpom.xmlにいくつかの依存関係を追加することで、ヒストグラム、カウンター、タイマー、およびシンプルタイマーのHelidon OpenMetrics出力にexemplarを追加できます。アプリケーションのコードや設定を変更する必要はありません。

この記事では、Helidon CLIを使用して作成されたHelidon QuickStartアプリケーションのような既存のHelidonアプリケーションがあることを前提としています。お手持ちのアプリケーションに簡単にexemplarサポートを追加し、その動作を確認できます。

• pom.xmlに依存関係を追加します。
• ローカルでZipkinを実行します。
• アプリケーションを実行し、アクセスします。
• 新しいメトリクスの模範となるZipkinのトレースを閲覧します。

How Helidon implements exemplars

exemplarサポートを有効にすると、Helidonがデータ値でメトリックを更新するたびに、トレースIDとサンプルの現在のシステム時間も記録します。

その後、Helidonがアプリケーションの /metrics エンドポイントに送られたリクエストに対するOpenMetrics（Prometheus）のレスポンスを整形する際に、関連するメトリック値ごとに1個の代表的なサンプル（1個のexemplar）を選択し、そのサンプルに関する情報をそのメトリック値の出力に追加します（以下の例を参照ください）。

minやmaxといったメトリック値は少なくとも1個のサンプルに直接対応しており、Helidonはこのようなサンプルをexemplarとして使用します。他のメトリック値は、meanのように複数のサンプルを集計したものです。集計メトリックの場合、Helidonはレポート対象のメトリック値にできる限り近い値を持つサンプルをexemplarとして選択します。

多くの場合、exemplarの値は、集約されたメトリクスの値と同じではありません。例えば、値が3、4、8であるサンプルの平均であるメトリックを考えてみましょう。平均値の5に等しい値を持つサンプルはないため、平均値に最も近い値を持つサンプルとして、Helidonは値が4のサンプルをこのメトリックのexemplarとします。

Adding exemplar support to your application

Update your pom.xml

exemplar、トレーシング、Zipkinをサポートするための依存関係を追加します。

<dependency>
    <groupId>io.helidon.metrics</groupId>
    <artifactId>helidon-metrics-trace-exemplar</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.helidon.microprofile.tracing</groupId>
    <artifactId>helidon-microprofile-tracing</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-zipkin</artifactId>
    <scope>runtime</scope>
</dependency>

お好みで、ZipkinではなくHelidonのJaegerサポートを追加することもできます。

【訳注】Jaegerサポートの依存関係を追加する場合は以下を使います。

<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-jaeger</artifactId>
    <scope>runtime</scope>
</dependency>

Start Zipkin

Zipkinを起動しない場合でも、アプリケーションは正しく動作しますし、Helidonはメトリクスの出力にexemplarを追加しますが、トレースのspanをレポートするZipkinサーバーに接続できない場合、Helidonは警告メッセージをログに出力します（そして当然ながらZipkinでトレースを閲覧することはできません）。

docker run --name zipkin -d -p 9411:9411 openzipkin/zipkin

Try the revised application

アプリケーションをビルドし実行します。

mvn package
java -jar target/quickstart-mp.jar

アプリケーションのサービスにアクセスします。

curl -X GET http://localhost:8080/greet
{"message":"Hello World!"}

curl -X GET http://localhost:8080/greet/Joe
{"message":"Hello Joe!"}

curl -X PUT -H "Content-Type: application/json" -d '{"greeting" : "Hola"}' http://localhost:8080/greet/greeting

curl -X GET http://localhost:8080/greet/Jose
{"message":"Hola Jose!"}

curl -X GET http://localhost:8080/greet          
{"message":"Hola World!"}

Retrieve metrics

では、メトリックを取得し、出力に現れるexemplarに着目しましょう。OpenMetrics仕様で定められている通り、exemplarはメトリック出力の最後にコメントとして現れます。

curl -s -X GET http://localhost:8080/metrics/vendor
# TYPE vendor_requests_count_total counter
# HELP vendor_requests_count_total Each request (regardless of HTTP method) will increase this counter
vendor_requests_count_total 6 # {trace_id="acc807bee31f8b96"} 1 1619637182.784000
...

各exemplarは以下を表しています。

• トレースID
• そのサンプルがメトリックに寄与した値（この例ではcount）
• Helidonがそのサンプルを記録したときのエポック秒

Browse the Zipkin Traces

ブラウザでZipkinにアクセスします（http://localhost:9411）。

RUN QUERYをクリックして、HelidonアプリケーションがZipkinにレポートしたスキャンを確認します。

続いて、EXPAND ALLをクリックしてトレースIDを表示します。

メトリックの出力に表示されているトレースIDを探し、その行のSHOWをクリックすると、トレースの詳細を確認できます。

選択したトレースとその様々なサブスパンの詳細を調べます。

Bottom Line

アプリケーションのコードを変更せずに、プロジェクトのpom.xmlにいくつかの依存関係を追加するだけで、Helidonアプリケーションのメトリクス出力でexemplarsを有効にできます。

メトリクス出力のexemplarのトレースIDを使用して、メトリクス値の代表的なトレースを特定し、Zipkinのようなトレースユーティリティを使用して、そうしたトレースの各々の詳細を調査できます。

More Information

詳細は、Helidon SEおよびHelidon MPアプリケーションのメトリックexemplarサポートのドキュメントをご覧ください。

SE — Metrics Support for Exemplars
https://helidon.io/docs/v2/#/se/metrics/04_prometheus_exemplar_support
MP — Metrics Support for Exemplars
https://helidon.io/docs/v2/#/mp/metrics/04_prometheus_exemplar_support

OpenMetrics仕様ではexemplarを説明しています。

OpenMetrics, a cloud-native, highly scalable metrics protocol
https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md