注释

对于大多数用户来说，开箱即用的仪器是完全足够的，无需再做任何事情。然而，有时用户希望为自己的自定义代码创建 跨度，而无需更改太多代码。WithSpan 和 SpanAttribute 注解支持这些用例。

依赖项

您需要将 opentelemetry-instrumentation-annotations 库添加到依赖中，才能使用 @WithSpan 注解。

• Maven
• Gradle

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

dependencies {
    implementation('io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:2.23.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 还允许您获取一个用于 自定义仪器 的 Tracer。