明示的分散トレース・コードのインスツルメンテーションの有効化

OpenTracing 用にクラスおよびメソッドをインスツルメントするには、@Traced アノテーションを使用します。

このタスクについて

OpenTracing 用にトレースされるクラスまたはメソッドを指定するには、@Traced アノテーションを適用します。

新しいバージョンの OpenTracing にマイグレーションする場合 : mpOpentracing-1.1 および opentracing-1.1 の両方のフィーチャーは、OpenTracing API への依存関係をバージョン 0.31.0 に変更しました。 アプリケーションで @Traced アノテーションを使用している場合は、変更は必要ありません。 バージョン 0.30.0 からの io.opentracing.ActiveSpan と io.opentracing.ActiveSpanSource を使用するコードがある場合は、これらのアプリケーションをバージョン 0.31.0 にマイグレーションする必要があります。

安定した機能： MicroProfile OpenTracing 1.3 フィーチャーは安定している。 戦略的な選択肢は、 mpTelemetry-1.0、 MicroProfile テレメトリー機能である。 詳細については、 MicroProfile OpenTracing から MicroProfile Telemetry 1.0 への移行ドキュメントを参照。

手順

  1. @Traced アノテーションをクラスまたはメソッドに適用します。
    • @Traced アノテーションをクラスに適用すると、アノテーションはそのクラスのすべてのメソッドに適用されます。
    • @Traced アノテーションをクラスおよびメソッドに適用した場合、メソッドに適用されるアノテーションが優先されます。 アノテーションは、メソッドの先頭でスパンを開始し、メソッドの終わりでスパンを終了します。
  2. オプション: 引数を @Traced アノテーションに適用します。
    value=[true|false]

    value=[true] 引数がデフォルトです。

    特定のメソッドにアノテーションを付け、それらのメソッドのスパンの作成を無効にするには、@Traced(false) を使用します。 @Traced(false) を使用して、特定の JAX-RS エンドポイントのスパン作成を無効にすることもできます。 JAX-RS エンドポイント・メソッドに対して @Traced(false) を使用すると、アップストリームの SpanContext は抽出されません。 作成するスパンには、アウトバウンド要求に対して自動的に作成される場合でも、注入されたトレーサーによって明示的に作成される場合でも、スパン階層内にアップストリームの親スパンはありません。 デフォルトでは、プログラムはすべての JAX-RS エンドポイント・メソッドをトレースします。

    operationName=<Name for the span>

    デフォルト値は、二重引用符 ("") です。

    operationName 値に二重引用符 ("") が使用されている場合、@Traced アノテーションはデフォルトのオペレーション名を使用します。 アノテーションが付けられたメソッドが JAX-RS エンドポイントでない場合、メソッドの新規スパンのデフォルト操作名には <package name>.<class name>.<method name> 値が含まれます。 クラスに operationName 値を指定した場合、独自の operationName 値で明示的にオーバーライドするメソッドがない限り、クラスのすべてのメソッドに対してその operationName 値が使用されます。

    以下の例は、@Traced アノテーションのオプションの引数を示します。

    @InterceptorBinding
@Target({ TYPE, METHOD })
@Retention(RUNTIME)
public @interface Traced {
    @Nonbinding
    boolean value() default true;
    @Nonbinding
    String operationName() default "";
}
  3. 構成済みトレーサーにアクセスします。
    1. 基礎にある OpenTracing トレーサー・オブジェクトが構成されたインスタンスを使用します。 構成済みトレーサーを Contexts and Dependency Injection (CDI) と共に使用するように MicroProfile 実装を設定します。
    2. この環境用の特定のアプリケーション用に構成したトレーサー・クラスを注入することによって、構成済みトレーサー・オブジェクトにアクセスします。 各アプリケーションは、それぞれ異なる 1 つのトレーサー・インスタンスを受け取ります。 トレーサー・オブジェクトは、ビジネス・メソッド内部でのスパンの作成など、複雑なトレース要件のサポートを可能にします。 以下の例は、注入されたトレーサー・クラスを表示します。
      @Inject
io.opentracing.Tracer configuredTracer;
    3. 以下の例に示すように、タグ、ログ、およびバゲージをスパンに追加します。
      configuredTracer.activeSpan().setTag(...);
configuredTracer.activeSpan().log(...);
configuredTracer.activeSpan().setBaggage(...);