分散トレースの有効化

環境を構成して、JAX-RS アプリケーションでの自動分散トレースを使用可能にします。 mpOpenTracing-1.3 フィーチャーをユーザー提供の opentracing.io.Tracer 実装と共に使用可能にして、JAX-RS アプリケーションが、分散トレース情報の作成、伝搬、および配信を自動的に行えるようにできます。

安定化されたフィーチャー: MicroProfile OpenTracing 1.3 フィーチャーは安定化されました。戦略的代替手段は、 mpTelemetry-1.0( MicroProfile Telemetry フィーチャー) です。詳しくは、 MicroProfile OpenTracing から MicroProfile Telemetry 1.0 へのマイグレーションに関する資料を参照してください。

このタスクについて

分散トレース: 分散トレースを使用して、サービス境界を越えて要求の流れをトレースします。これは、要求が複数のサービスを通って流れていくのが一般的であるマイクロサービス環境では重要なことです。分散トレースがアクティブな場合、各サービスは相関 ID を使用してトレース・レコードを作成します。使用される相関 IDは、アップストリーム・サービスから伝搬されている可能性があります。分散トレース・ロギングには、以下の例に示すように、分散トレース・レコード用のストレージ・サービスがあります。ストレージ・サービスを使用して、複数のサービスにまたがって流れる特定の要求フローと関連付けられたトレース・レコードを表示します。

Opentracing.io: opentracing.io プロジェクトは、分散トレース用のサービスを装備するための標準 API を提供します。 opentracing.io API を使用して分散トレース用にすべてのサービスを計測する場合、デプロイメント時にサービスを構成できます。サービスの言語用の実装ライブラリーが存在する場合、サービスが共通システム実装を使用して、ログ・レコードをフォーマットし、サービスにまたがる相関 ID を伝搬するようにします。共通実装は、すべてのサービスで理解できるように相関 ID を伝搬します。また、この実装は、サーバーが分散トレース・レコード・ストレージ用にログ・レコードを理解できるようにログ・レコードをフォーマットします。

手順

ユーザー・フィーチャーを提供します。 ${wlp.user.dir}/extension ディレクトリーに、 io.opentracing.Tracer 実装を持つユーザー・フィーチャーを作成してインストールします。
1. Zipkin Opentracing tracer implementation for use with Libertyで Zipkin固有の opentracing.io API 実装を提供するフィーチャーのサンプル・ソース・コードにアクセスします。 Maven リポジトリーで Zipkin固有の opentracing.io API 実装を提供するユーザー・フィーチャーのビルド・バージョンにアクセスします。
2. ユーザー・フィーチャーが com.ibm.ws.opentracing.tracer.OpentracingTracerFactory インターフェースを実装する OSGI サービスを提供するようにします。
```
package com.ibm.ws.opentracing.tracer;

import io.opentracing.Tracer;

public interface OpentracingTracerFactory {

    Tracer newInstance(String serviceName);

}
```
1. OpentracingTracerFactory 実装の newInstance メソッドを設定して、 io.opentracing.Tracer オブジェクトのインスタンスを返します。プログラムが返す Tracer オブジェクトが、サービスが実行される環境にとって正しい実装であることを確認してください。
  「 Zipkin Opentracing tracer implementation for use with Liberty」の例では、Tracer は、 Zipkin サーバーが使用可能な環境で通信するインスタンスです。
2. 環境で Zipkin サーバーを使用しない場合は、環境内の分散トレース・サーバーと通信する Tracer オブジェクトを提供するように実装を変更します。
  ユーザー・フィーチャーを作成すると、次の 2 つの成果物が生成されます。
  - OpentracingTracerFactory 実装と Tracer 実装が含まれる .jar ファイル
  - ユーザー・フィーチャーの記述が含まれた mf ファイル
  Zipkin Opentracing tracer implementation for use with Libertyの例では、以下の場所に 2 つのファイルが作成されます。
  
  mpOpenTracing-1.0 の場合:
```
target/extension/lib/com.ibm.ws.opentracing.zipkintracer-0.30.jar
target/extension/lib/features/opentracingZipkin-0.30.mf
```
  mpOpenTracing-1.1、mpOpenTracing-1.2、または mpOpenTracing-1.3 の場合:
```
target/extension/lib/com.ibm.ws.opentracing.zipkintracer-0.31.jar
target/extension/lib/features/opentracingZipkin-0.31.mf
```
3. 実装を含む .jar ファイルを、環境内のすべての Liberty サーバーの ${wlp.user.dir}/extension/lib ディレクトリーにコピーします。
4. フィーチャーの説明が含まれている .mf ファイルを、環境内のすべての Liberty サーバーの ${wlp.user.dir}/extension/lib/features ディレクトリーにコピーします。
サーバーを構成します。サーバー環境の server.xml ファイルでユーザー・フィーチャーを有効にします。
1. 環境内の各 Liberty サーバーでこのフィーチャーを使用可能にします。
  作成した .mf ファイルには、 IBM-ShortName という名前のプロパティーが含まれています。 IBM-ShortName プロパティーの値は、各 Liberty サーバーの server.xml ファイル内で有効にされているフィーチャー名です。 Zipkin Opentracing tracer implementation for use with Libertyの例では、 IBM-ShortName プロパティーの値は、 mpOpenTracing-1.1、 mpOpenTracing-1.2、または mpOpenTracing-1.3の opentracingZipkin-0.30 または opentracingZipkin-0.31 です。このフィーチャーを有効にするため、以下のコードを各 server.xml ファイルに追加します。
  mpOpenTracing-1.0 の場合:
```
<featureManager>
	<feature>usr:opentracingZipkin-0.30</feature>
</featureManager>
```
  mpOpenTracing-1.1、mpOpenTracing-1.2、または mpOpenTracing-1.3 の場合:
```
<featureManager>
	<feature>usr:opentracingZipkin-0.31</feature>
</featureManager>
```
  Zipkin Opentracing tracer implementation for use with Liberty のサンプルは、 server.xml ファイルから構成パラメーターを受け入れます。デフォルト・サービス名 zipkin とデフォルト・ポート 9411 を使用して環境内の Zipkin サーバーに到達できない場合は、以下のように opentracingZipkin 構成エレメントを各サーバーに追加してホストとポートを構成します。
```
<opentracingZipkin host="Zipkin Host Name" port="Zipkin Port Number"/>
```