アノテーション

ほとんどのユーザーにとって、デフォルトの計装で十分であり、追加の作業は必要ありません。 しかし、コードをほとんど変更せずに、独自のカスタムコードに対してスパンを作成したい場合もあります。 WithSpan と SpanAttribute アノテーションはこのようなユースケースをサポートします。

依存関係

@WithSpan アノテーションを使用するには、opentelemetry-instrumentation-annotations ライブラリへの依存関係を追加する必要があります。

• Maven
• Gradle

<dependencies>
  <dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-instrumentation-annotations</artifactId>
    <version>2.30.0</version>
  </dependency>
</dependencies>

dependencies {
    implementation('io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:2.30.0')
}

@WithSpan でメソッドにスパンを作成する

特定のメソッドを計装するスパンを作成するには、メソッドに @WithSpan アノテーションを付けます。

import io.opentelemetry.instrumentation.annotations.WithSpan;

public class MyClass {
  @WithSpan
  public void myMethod() {
      <...>
  }
}

アプリケーションがアノテーション付きのメソッドを呼び出すたびに、その実行時間を示し、スローされた例外を記録するスパンが作成されます。 デフォルトでは、スパン名は <className>.<methodName> になりますが、value アノテーションパラメーターで名前を指定することもできます。

@WithSpan でアノテーションされたメソッドの戻り値の型が、以下に示す future またはPromise に類似した型のいずれかである場合、スパンは future が完了するまで終了しません。

• java.util.concurrent.CompletableFuture
• java.util.concurrent.CompletionStage
• com.google.common.util.concurrent.ListenableFuture
• org.reactivestreams.Publisher
• reactor.core.publisher.Mono
• reactor.core.publisher.Flux
• io.reactivex.Completable
• io.reactivex.Maybe
• io.reactivex.Single
• io.reactivex.Observable
• io.reactivex.Flowable
• io.reactivex.parallel.ParallelFlowable

パラメーター

@WithSpan 属性はスパンのカスタマイズのために以下のオプションパラメーターをサポートしています。

パラメーターの使用例：

@WithSpan(kind = SpanKind.CLIENT, inheritContext = false, value = "my span name")
public void myMethod() {
    <...>
}

@WithSpan("my span name")
public void myOtherMethod() {
    <...>
}

@SpanAttribute でスパンに属性を追加する

アノテーション付きのメソッドに対してスパンが作成される際、メソッド呼び出しの引数の値を、作成されたスパンの属性として自動的に追加できます。 メソッドのパラメーターに @SpanAttribute アノテーションを付けるだけです。

import io.opentelemetry.instrumentation.annotations.SpanAttribute;
import io.opentelemetry.instrumentation.annotations.WithSpan;

public class MyClass {

    @WithSpan
    public void myMethod(@SpanAttribute("parameter1") String parameter1,
        @SpanAttribute("parameter2") long parameter2) {
        <...>
    }
}

アノテーションの引数として指定しない場合、属性名は -parameters オプションを javac コンパイラーに渡して .class ファイルにコンパイルされた仮パラメーター名から導出されます。

@WithSpan 計装の抑制

@WithSpan の抑制は、@WithSpan で過剰に計装されたコードがあり、コードを変更せずに一部を抑制したい場合に便利です。

otel.instrumentation.methods.include でメソッドにスパンを作成する

コードを変更できない場合でも、特定のメソッドにスパンをキャプチャするように Java エージェントを設定できます。

メソッドがオーバーロードされている場合（同じクラスに同じ名前で異なるパラメーターを持つメソッドが複数存在する場合）、そのメソッドのすべてのバージョンが計装されます。

次のステップ

アノテーションの使用に加えて、OpenTelemetry API を使用すると、カスタム計装に使えるトレーサーを取得できます。