注解
对于大多数用户来说,开箱即用的仪表是完全足够的,不需要做任何额外的操作。然而,有时候用户希望在不进行太多代码更改的情况下为自己的自定义代码创建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完成之前不会结束。
- 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
使用@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范围内执行代码的跟踪器。