注解

使用Java代理与仪表注解。

对于大多数用户来说,开箱即用的仪表是完全足够的,不需要做任何额外的操作。然而,有时候用户希望在不进行太多代码更改的情况下为自己的自定义代码创建span

依赖项

您需要添加对opentelemetry-instrumentation-annotations库的依赖,以使用@WithSpan注解。

Maven

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

Gradle

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

使用@WithSpan注解创建包围方法的span

要为您的方法之一创建与之对应的span,请使用@WithSpan注解对该方法进行注解。

import io.opentelemetry.instrumentation.annotations.WithSpan;

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

每次应用程序调用被注解的方法时,都会创建一个span,用以表示该方法的持续时间并提供任何抛出的异常。默认情况下,span的名称将是<className>.<methodName>,除非注解的参数中提供了名称。

如果被@WithSpan注解的方法的返回类型是下面列出的future-或promise-like类型之一,则span将在future完成之前不会结束。

使用@SpanAttribute注解向span添加属性

当为被注解的方法创建span时,可以通过使用@SpanAttribute注解来自动将方法调用的参数值添加为属性到创建的span中。

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) {
        <...>
    }
}

除非在注解的参数中指定了名称,否则如果形式参数名被编译进.class文件,可以通过向javac编译器传递-parameters选项来从形式参数名派生属性名称。

抑制@WithSpan仪表注解

如果您的代码使用了过多的@WithSpan仪表注解,而您希望抑制其中的一些而不修改代码,那么抑制@WithSpan非常有用。

System property: otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods Environment variable: OTEL_INSTRUMENTATION_OPENTELEMETRY_INSTRUMENTATION_ANNOTATIONS_EXCLUDE_METHODS

Description: 针对特定方法抑制@WithSpan仪表注解。格式为my.package.MyClass1[method1,method2];my.package.MyClass2[method3]

使用otel.instrumentation.methods.include为方法创建span

如果您无法修改代码,仍然可以配置Java代理以在特定方法周围捕获span。

System property: otel.instrumentation.methods.include Environment variable: OTEL_INSTRUMENTATION_METHODS_INCLUDE

Description: 添加针对特定方法的仪表,取代@WithSpan。格式为my.package.MyClass1[method1,method2];my.package.MyClass2[method3]

如果方法是重载的(在同一个类中多次出现,名称相同但参数不同),所有版本的方法都将被仪表化。

下一步

除了使用注解之外,OpenTelemetry API 还允许您获取一个可以用于手动仪表化并在该span范围内执行代码的跟踪器。

最后修改 December 10, 2023: translate (a4350d6e)