今回のテーマは前回のMicroProfile Metricsに続き可観測性のもう一角をなす分散トレーシングのMicroProfile OpenTracing(MP OpenTracing)です。MP OpenTracingの仕様は主にランタイム提供ベンダー向けのもので利用する側はランタイムがトレース情報を自動計測してくれるため、その存在を意識することはほぼありません。これは便利で都合がよいことですが、その一方で、どこまでがOpenTracingなどの標準仕様で決められていることで、どこからがMP OpenTracing固有で、そしてJaegerなどの製品が担っているのはどの部分か？などといった、分散トレーシングの構成要素とその役割が分かりづらくなっています。今回の記事ではこの辺りも意識し、MP OpenTracingだけではなく少し視野を広げた説明を行っていきます。

なお、記事はコードの抜粋を記載しています。全体を見たい場合や動作を確認したい場合は以下のGitHubリポジトリを参照ください。

• https://github.com/extact-io/contrarian-microprofile-sample/tree/main/10-tracing

MP OpenTracingのテーマそのものとなる"分散トレーシング"について筆者なりの理解を説明します。

マイクロサービスは複数の分散アプリケーションが協調動作して機能を実現するため、外部からのリクエストに対して、どのアプリケーションをいつ、どのように通ったかを把握できるようにすることが障害調査やパフォーマンスのボトルネック調査で重要となります。しかし、マイクロ―サービスはアプリケーションが分散している分、この把握は難しくなります。そこで登場するのが分散トレーシングです。

分散トレーシングとはアプリケーションを跨いだ一連のリクエストを追跡（トレース）し、通過したアプリや時間などのテレメトリーデータを収集、記録する技術となります。また、この収集したテレメトリーデータをツールで可視化することで、どのアプリケーションをどのように通ったかを把握できるようにするものとなります。

テレメトリーデータを収集、可視化するツールはいつかありますが、今回はその中でもフリーで使える定番のJaeger(イェーガー)を使って説明していきます。

そんな素敵な分散トレーシングをMP OpenTracingを使ってどのようなことができるかをみてきます。そもそもOpenTracingとはなにか？などの細かい話しは機能のイメージを掴んでもらった後に説明します。

複数のアプリが協調動作するシンプルなものがよいため、今回は「MicroProfile RestClient 3.0の確認と小技機能の紹介」で利用した挨拶を返す次の簡単なRESTアプリケーションを使って説明していきます。

前回の説明と重複しますが、このRESTアプリケーションはHelloAggregateサービスが収集(/aggregate)のリクエストを受け取ると配下の3つのHelloサービスに挨拶(/hello)を問い合わせ、各Helloサービスは自身の言語に対する挨拶を返します。HelloAggregateサービスは各Helloサービスから返された挨拶をカンマ区切りで連結してまとめ、その内容をリクエスト元に返すものとなります。

上述の挨拶アプリケーションを使ってアプリケーションを跨いだリクエストの流れがどのように記録、可視化されるかをMP OpenTracingとJaegerを使ってみていきます。

MP OpenTracingは計測対象のアプリケーションにMP OpenTracingを組み込んで有効化することで、自動でテレメトリーデータを取得し、取得したデータをJaegerなどのバックエンドに自動で送信します。なお、MP OpenTracingの有効化はMicroProfileランタイムごとに異なるため、詳細は利用するランタイムのマニュアルを参照ください。

<dependency>
    <groupId>org.eclipse.microprofile.opentracing</groupId>
    <artifactId>microprofile-opentracing-api</artifactId>
</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-jaeger</artifactId>
    <scope>runtime</scope>
    <exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-jdk14</artifactId>
        </exclusion>
    </exclusions>
</dependency>

MP OpenTracingのアプリケーションへの組み込みができたら次はJaegerの起動になります。
Jaegerのインストール方法はいくつかありますが、UIも含め必要なものが一式含まれているAll-in-oneのコンテナイメージを使うのが一番簡単なため、ここではAll-in-oneコンテナを使った説明をしてきます。

次のdockerコマンドでJaegerのAll-in-oneコンテナを起動します。

docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 14250:14250 \
  -p 14268:14268 \
  -p 14269:14269 \
  -p 9411:9411 \
  jaegertracing/all-in-one:1.39

コンテナが起動したしたらブラウザからhttp://localhost:16686にアクセスし、下の画面が開けば起動成功です。問題がある場合やAll-in-oneコンテナの詳細についてはJaeger公式のこちらを参考にしてください。

ここまでで準備は完了です。次からは実際のトレース機能をみていきましょう。

先ほど説明した挨拶アプリにリクエストを送り動かしてみます。

curl localhost:7001/aggregate/sync
こんにちは, Hello, ニイハオ

• リクエストの流れ(再掲)
  

この際のリクエストは上の図(再掲)のようにHelloAggregation→HelloService→HelloService→HelloServiceと流れ、それぞれのHelloSeviceの処理時間はスリープにより約1秒程度となっているハズです。

それではこの結果をJaegerで確認してみましょう。
挨拶アプリにリクエストを投げた後に先ほどのhttp://localhost:16686の画面の左上の”Service”プルダウンメニューに[HelloAggregationApplicaiton]が出てくるので、それを選択し[FindTraces]ボタンをクリックします。

そうすると次のような結果が表示されます。

この結果の"HelloAggregationApplicaiton"の行を選択すると、そのリクエストに対するアプリケーションを跨ったトレース情報がビジュアルに表示されます。

この結果から/aggregateに対するリクエストが確かにHelloAggregation→HelloService→HelloService→HelloServiceと流れていき、それぞれのHelloServiceの処理時間が約1秒程度でトータルで約4秒弱掛かっていることが分かります。

MP OpenTracingにはこの他にもコードを実装することでより詳細なトレース情報を取得する機能もあります。本記事ではこの機能は取り上げませんが、興味がある方は公式マニュアルのこちらを参照ください。

MP OpenTracingとJaegerでどのようなことができるかを掴んでもらったところで、次は「だれが」「どこで」「どのように」トレース情報を採っているかを見ていきたいと思います。

今回のトレース情報の取得から表示に関わる登場人物をもとにその全体像を表すと次のようになります。Jaegerに登場する要素は他にもありますが、本題と余り関係ない要素は省略しています。

MP OpenTracingはJakarta RESTful Web Services(JAX-RS)のリクエストに対するトレース情報を自動で取得します。MP OpenTracingはRESTリソースに対するリクエスト（Incoming Request）があった場合、下の画面キャプチャの1つの赤帯に相当するSpanを開始し、リクエストが完了した時点でそのSpanを終了させます。JAX-RS Clientで送信するリクエスト(Outgoing Request)に対しては、トレースID等のSpanContext情報をHTTPヘッダに設定し、送信先にそのコンテキスト情報を自動で伝播させます。

MP OpenTracingにより取得されたトレース情報はMP OpenTracingの機能によりJaeger Collectorに自動で送信され、Jaeger Collectorは受信したトレース情報を蓄積していきます。そしてこの蓄積されたトレース情報をJaeger UIを通してビジュアルに表示するといった流れになります。

ここまでの説明を整理する次のようになります。

• MP OpenTracingによりJAX-RSのリクエストに対するトレース情報の取得とバックエンドへの送信が行われる
• Jaegerなどのバックエンドによりトレース情報が収集、蓄積されるとともにトレース情報を可視化する機能も提供される

ポイントはMP OpenTracingとJaegerの双方の役割はトレース情報の取得・送信と収集・蓄積を境に分かれるところになります。この点は理解しておきましょう。

仕組みの説明してきましたがOpenTracingの話はまだ出てきていません。次からはMP OpenTracingの中を少し掘り下げて、MP OpenTracingとOpenTracingの関係を見ていきます。

まずはOpenTracingについて簡単に説明します。

OpenTracingは過去にCloud Native Computing Foundation(CNCF)により策定されたトレースを取得するためのベンダー非依存な仕様で、主にTraceとSpanといったトレースのデータモデルとそのデータモデルを扱うAPI仕様で構成されています。このAPIは主要な各言語に対して提供されており、Javaの場合はio.opentracing.*パッケージ(opentracing-api.jar)がその実体となります。

ただし、OpenTracingは仕様を定めているだけのため、実際のトレース処理にはJaegerなどのOpenTracingに準拠した実装が必要なります。このOpenTracingとJaegerの関係はJakartaEEのJakarta Persistence(JPA)とその実装としてのHibernateやEclipse Linkと同じといえます。

また、JPAを素で使うときと同じようにOpenTracingを素で使う場合は、OpenTracingのAPIを使い下記のようにTraceを取得するロジックをアプリケーションに埋め込むことが必要となります。

io.opentracing.Tracer tracer = ...;
...
Span span = tracer.buildSpan("someWork").start();
try (Scope scope = tracer.scopeManager().activate(span)) {
    // Do things.
} catch(Exception ex) {
    Tags.ERROR.set(span, true);
    span.log(Map.of(Fields.EVENT, "error", Fields.ERROR_OBJECT, ex, Fields.MESSAGE, ex.getMessage()));
} finally {
    span.finish();
}

• 引用元: GitHub::opentracing/opentracing-java - Starting a new Span

OpenTracingを素で使う場合、コードが必要になる一方、MP OpenTracingではトレースに関する処理は一切書いていません。これがMP OpenTracingの具体的な機能となります。MP OpenTracingはJAX-RSとCDIの機能を統合し、OpenTracing APIを使った処理を肩代わりしてくれます。

このMP OpenTracingとOpenTracingの関係を今度はソフトウェアスタックで図示すると次のようになります。

アプリケーションからはMicroProfile OpenTracingしか意識することはありませんが、図にあるとおり、その内部における実際のトレースの取得と送信はOpenTracing実装(今回はJaeger Client)により行われます。

マイクロサービスの利点の一つとして、サービスごとに実装言語や実行環境を選択できることがあります。このため、マイクロサービスを構成するすべてのアプリケーションがMicroProfile OpenTracingをサポートしているとは限りません。では、MicroProfile OpenTracingをサポートしていないアプリ(非MP OpenTracingアプリ)を分散トレースに参加させるにはどのようにしたらよいでしょうか？

これには分散トレーシングの仕組みへの理解が必要となります。ここではよりその仕組みを理解することを目的に非MP OpenTracingアプリをトレースに参加させる方法をみていきます。

MP OpenTracingアプリと非MP OpenTracingアプリが混在したトレース環境の構成は次のようになります。

この際、非MP OpenTracingアプリのトレースで考える必要があることは、呼び出し元のBアプリケーションからSpanの紐づけ情報として渡されるトレース情報のHTTPヘッダの設定形式を意味するPropagationフォーマットとバックエンドにSpan情報を送信する際のSpanフォーマット(通信プロトコルも含む)の2つになります。

MP OpenTracingで構成されたトレース環境に参加するには、MP OpenTracingアプリ間で利用されているPropagationフォーマットとSpanフォーマットに合わせる必要があります。この具体的なフォーマットしてはOpenTelemetry SDKがサポートしているフォーマットが参考になります。(Propagationフォーマットはこちら、Spanフォーマット^[7]はこちら)

X-B3-TraceId: 80f198ee56343ba864fe8b2a57d3eff7
X-B3-ParentSpanId: 05e3ac9a4f6e3b90
X-B3-SpanId: e457b5a2e4d86bd1
X-B3-Sampled: 1

先ほどの説明に使っていたRESTアプリに次のようにRandomHelloServiceを追加してみます。

このRandomHelloApplicationアプリはJAX-RSを使っていますが、HelloAggregationApplicaitonやHelloServiceApplicationのようにMP OpenTracingは組み込んでいません。トレース実装にはその代わりとしてOpenTelemetry Java agent(Java agent)を使います。

Java agentはその名のとおりエージェントによるAuto Instrumentation方式のため、サポート一覧に記載されているフレームワークやライブラリ、アプリケーションサーバであれば、起動時にagentを組み込むだけでコードやライブラリを追加することなく各対応コンポーネントに対するトレースを取得できます^[8]。

RandomHelloApplicaitonを次のように起動し、Java agentを組み込みます。なお、-javaagent:にはreleasesページで取得したopentelemetry-javaagent.jarへのパスを指定します。

export OTEL_TRACES_EXPORTER=otlp
export OTEL_PROPAGATORS=b3
export OTEL_METRICS_EXPORTER=none
export OTEL_SERVICE_NAME=RandomHelloService
java -javaagent:/path/to/opentelemetry-javaagent.jar -jar target/hello-service-random-tr.jar

ここでポイントとなるのは起動する前に設定しているOTEL_TRACES_EXPORTERとOTEL_PROPAGATORSの環境変数です。これはJava agentに対する設定となります。

上述したとおり、Helidon 3.xのMP OpenTracingアプリケーションではPropagationフォーマットにB3フォーマット、SpanフォーマットにはOTLPが使われます。後から追加したRandomHelloApplicationは利用するフォーマットを参加する環境に合わせ、B3とOTLPにする必要があります^[9]。

他の2つの環境変数は、今回はメトリクス情報の取得は対象としてないためOTEL_METRICS_EXPORTERにnoneを、トレースのタイムラインで表示されるサービス名はRandomHelloServiceとなるようにOTEL_SERVICE_NAMEを設定しています。

それではこのように構成したアプリケーションのトレース情報を見てみましょう。

まずは/aggregateへのリクエスト結果を確認します。

curl localhost:7001/aggregate/sync
こんにちは, Hello, ニイハオ, チャオ

挨拶結果の4つ目にチャオが追加されていることからRandomHelloも処理に参加していることが確認できます。

次にJaeger UIから該当のトレース情報を確認してみます。

表示されたトレース情報からMP OpenTracingアプリケーションの中に、OpenTelemetryを使った非MP OpenTracingアプリのRandomHelloアプリがトレースに参加できていることが確かに分かります。

MicroProfile OpenTracingによる分散トレーシングをみてきましたが、Kubernetesなどを利用したクラウドネイティブ環境ではトレース機能をアプリケーション側で持つのではなく、分散トレーシング(OpenTelemetry / Jaeger)の記事で紹介しているようなサイドカーやサービスメッシュで持つのが一般的です。

サイドカーやサービスメッシュの場合は、言語を問わずアプリケーションに後からアドオンできるという大きなメリットがありますが、非コンテナ環境のアプリケーションには適用できません。また、記事で詳細は取り上げませんでしたがMicroProfile OpenTracingはコードを実装することでアプリケーション内部の詳細なトレース情報も簡便に取得ことが可能です。

サイドカーやサービスメッシュが利用できる環境であれば、筆者もそちらを中心とした方がメリットがあると考えていますが、非コンテナ環境のサポートやアプリケーション内部のトレース情報の取得などの要件がある場合はMicroProfile OpenTracingの存在が活きてくると思います。

参照資料

• OpenTracing: https://opentracing.io/docs/
• Jaeger: https://www.jaegertracing.io/docs/1.39/
• OpenTelemetry: https://opentelemetry.io/docs/
• Qiita - Kubernetes上のマイクロサービスを分散トレースする: https://qiita.com/mumoshu/items/d4065a96a9d7e319eceb