注解

结合 Java 代理使用插桩注解。

对于大多数用户而言,开箱即用的插桩功能已经完全足够,无需进行额外操作。 不过,有时用户希望为自己的自定义代码创建 Span,同时又不想对代码做太多改动。 WithSpanSpanAttribute 注解可满足这些使用场景。

依赖项

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

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

Gradle

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

使用 @WithSpan 在方法周围创建 Span

要为特定方法创建用于插桩的 Span,可使用 @WithSpan 对该方法进行注解。

import io.opentelemetry.instrumentation.annotations.WithSpan;

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

每当应用程序调用带有该注解的方法时,都会创建一个 Span 来记录方法的执行时长并捕获所有抛出的异常。 默认情况下,Span 名称为 <类名>.< 方法名 >,除非通过 value 注解参数指定了名称。

如果被 @WithSpan 注解的方法的返回类型是以下列出的类 Future 或 类Promise, 那么该 Span 将在 Future 完成后才会结束。

参数

@WithSpan 注解支持以下可选参数,用于对 Span 进行自定义:

名称类型默认值描述
valueString""Span 名称。如果未指定,则使用默认的 <类名>.<方法名>
kindSpanKind (enum)INTERNALSpan 的类型
inheritContextbooleantrue自 2.14.0 起。控制新生成的 Span 是否会在现有(当前)上下文中被继承。如果为 false,则会创建一个新的上下文。

参数使用示例:

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

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

使用 @SpanAttribute 为 Span 添加属性

当为带有注解的方法创建 Span 时, 方法调用的参数值可以自动作为属性添加到所创建的 Span 中。 只需在方法参数上添加 @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) {
        <...>
    }
}

除非在注解中指定参数名,否则属性名将从形参名派生, 前提是通过向 javac 编译器传递 -parameters 选项将形式参数名称编译到 .class 文件中。

禁用 @WithSpan 插桩

如果某些代码通过 @WithSpan 进行了过度插桩,而你希望在不修改代码的情况下禁用其中一部分, 那么禁用 @WithSpan 就会非常有用。

System property: otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methodsEnvironment 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.includeEnvironment variable: OTEL_INSTRUMENTATION_METHODS_INCLUDE

Description: 添加对特定方法的插桩,以替代 @WithSpan。 格式为 my.package.MyClass1[method1,method2];my.package.MyClass2[method3]

如果一个方法被重载(在同一个类中出现多次,名称相同但参数不同),那么该方法的所有版本都会被插桩。

下一步操作

除了使用注解之外,OpenTelemetry API 还允许你获取一个追踪器(tracer), 该追踪器可用于自定义插桩