注解
对于大多数用户而言,开箱即用的插桩功能已经完全足够,无需进行额外操作。
不过,有时用户希望为自己的自定义代码创建 Span,同时又不想对代码做太多改动。
WithSpan
和 SpanAttribute
注解可满足这些使用场景。
依赖项
要使用 @WithSpan
注解,你需要添加对 opentelemetry-instrumentation-annotations
库的依赖。
<dependencies>
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-instrumentation-annotations</artifactId>
<version>2.19.0</version>
</dependency>
</dependencies>
使用 @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 完成后才会结束。
- 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
注解支持以下可选参数,用于对 Span 进行自定义:
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
value | String | "" | Span 名称。如果未指定,则使用默认的 <类名>.<方法名> 。 |
kind | SpanKind (enum) | INTERNAL | Span 的类型。 |
inheritContext | boolean | true | 自 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-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 还允许你获取一个追踪器(tracer), 该追踪器可用于自定义插桩。
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!