Анотації

Для більшості користувачів достатньо інструментування з коробки, і нічого більше робити не потрібно. Однак іноді користувачі бажають створювати відрізки для свого власного коду без значних змін у коді. Анотації WithSpan та SpanAttribute підтримують ці варіанти використання.

Залежності

Щоб використовувати анотацію @WithSpan, вам потрібно додати залежність від бібліотеки opentelemetry-instrumentation-annotations.

• Maven
• Gradle

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

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

Створення відрізків навколо методів з @WithSpan

Щоб створити відрізок, що інструментує певний метод, анотуйте метод за допомогою @WithSpan.

import io.opentelemetry.instrumentation.annotations.WithSpan;

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

Кожного разу, коли застосунок викликає анотований метод, створюється відрізок, який позначає його тривалість і надає будь-які помилки, що зʼявляються. Стандартно імʼя відрізка буде <className>.<methodName>, якщо імʼя не вказано як аргумент параметра value до анотації.

Якщо тип повернення методу, анотованого @WithSpan, є одним із типів, схожих на future або promise, зазначених нижче, то відрізок не буде завершено, доки 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 підтримує наступні необовʼязкові параметри для налаштування відрізків:

Приклад використання параметрів:

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

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

Додавання атрибутів до відрізка за допомогою @SpanAttribute

Коли створюється відрізок для анотованого методу, значення аргументів до виклику методу можуть автоматично додаватися як атрибути до створеного відрізка. Просто додайте до параметрів методу анотацію @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) {
        <...>
    }
}

Якщо не вказано як аргумент до анотації, імʼя атрибута буде виведено з формальних імен параметрів, якщо вони скомпільовані у файли .class за допомогою параметра -parameters до компілятора javac.

Придушення інструментування @WithSpan

Придушення @WithSpan корисне, якщо у вас є код, який надмірно інструментований за допомогою @WithSpan, і ви хочете придушити деякі з них без зміни коду.

Створення відрізків навколо методів за допомогою otel.instrumentation.methods.include

У випадках, коли ви не можете змінити код, ви все ще можете налаштувати Java агент для захоплення відрізків навколо конкретних методів.

Якщо метод перевантажений (зʼявляється більше одного разу в одному класі з однаковим імʼям, але з різними параметрами), всі версії методу будуть інструментовані.

Наступні кроки

Крім використання анотацій, API OpenTelemetry дозволяє отримати трасувальник, який можна використовувати для ручного інструментування.