Java Agent 自定义检测

对于大多数用户来说，开箱即用的检测功能已经完全足够，无需进行额外配置。

但在某些场景下，您可能需要对特定代码进行自定义检测，本文将介绍两种实现方式。

方式一：创建指定方法的 Span

如果您无法或不想修改源代码，可以通过配置 Java Agent 来创建指定方法的 Spans。

配置方法

• 系统属性: otel.instrumentation.methods.include
• 环境变量: OTEL_INSTRUMENTATION_METHODS_INCLUDE

配置格式：my.package.MyClass1[method1,method2];my.package.MyClass2[method3]

重载方法说明

当方法存在重载时（同一个类中有多个同名但参数不同的方法），所有版本的方法都会被检测。

方式二：使用注解创建 Span

如果您可以修改源代码，使用注解是一种更优雅的方式。

OpenTelemetry 提供了 @WithSpan 和 @SpanAttribute 注解来实现自定义检测。

依赖配置

要使用注解功能，首先需要添加以下依赖：

Maven

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

Gradle

dependencies {
    implementation 'io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:2.12.0'
}

使用 @WithSpan 注解

@WithSpan 注解用于创建新的 Span：

import io.opentelemetry.instrumentation.annotations.WithSpan;

public class MyClass {
  @WithSpan
  public void myMethod() {
      // 方法实现
  }
}

使用 @SpanAttribute 注解

信息

如果被 @WithSpan 注解的方法返回类型是以下异步类型之一，那么 Span 将在异步操作完成后才结束：

• 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 注解标注方法参数：

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 检测。

配置选项

• 系统属性: otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods
• 环境变量： OTEL_INSTRUMENTATION_OPENTELEMETRY_INSTRUMENTATION_ANNOTATIONS_EXCLUDE_METHODS

配置格式为： my.package.MyClass1[method1,method2];my.package.MyClass2[method3]

下一步

除了上述两种方式外，OpenTelemetry API 还允许您获取 tracer 用于更灵活的自定义检测。