Annotations

Pour la plupart des utilisateurs, l’instrumentation fournie par défaut est complètement suffisante et rien de plus n’a besoin d’être fait. Parfois, cependant, les utilisateurs souhaitent créer des spans pour leur propre code sans avoir à changer beaucoup de code. Les annotations WithSpan et SpanAttribute supportent ces cas d’usage.

Dépendances

Vous devrez ajouter une dépendance à opentelemetry-instrumentation-annotations pour utiliser l’annotation @WithSpan.

• Maven
• Gradle

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

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

Créer des spans autour de méthodes avec @WithSpan

Pour créer un span qui instrumente une méthode particulière, annotez la méthode avec @WithSpan.

import io.opentelemetry.instrumentation.annotations.WithSpan;

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

Chaque fois que l’application invoque la méthode annotée, elle crée un span qui indique sa durée et fournit toutes les exceptions levées. Par défaut, le nom du span sera <className>.<methodName>, sauf si un nom est fourni via le paramètre d’annotation value.

Si le type de retour de la méthode annotée par @WithSpan est l’un des types future ou promise listés ci-dessous, alors le span ne sera pas terminé jusqu’à ce que le future se termine.

• 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

Paramètres

L’attribut @WithSpan supporte les paramètres optionnels suivants pour permettre la personnalisation des spans :

Exemple d’utilisation des paramètres :

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

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

Ajouter des attributs au span avec @SpanAttribute

Quand un span est créé pour une méthode annotée, les valeurs des arguments de l’invocation de méthode peuvent être automatiquement ajoutées comme attributs au span créé. Annotez simplement les paramètres de méthode avec l’annotation @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) {
        <...>
    }
}

Sauf si spécifié comme argument de l’annotation, le nom de l’attribut sera dérivé des noms de paramètres formels s’ils sont compilés dans les fichiers .class en passant l’option -parameters au compilateur javac.

Supprimer l’instrumentation @WithSpan

Supprimer @WithSpan est utile si vous avez du code qui est sur-instrumenté en utilisant @WithSpan et que vous voulez en supprimer certains sans modifier le code.

Créer des spans autour de méthodes avec otel.instrumentation.methods.include

Dans les cas où vous ne pouvez pas modifier le code, vous pouvez toujours configurer l’agent Java pour capturer des spans autour de méthodes spécifiques.

Si une méthode est surchargée (apparaît plus d’une fois sur la même classe avec le même nom mais des paramètres différents), toutes les versions de la méthode seront instrumentées.

Prochaines étapes

Au-delà de l’utilisation d’annotations, l’API OpenTelemetry vous permet d’obtenir un traceur qui peut être utilisé pour l’instrumentation personnalisée.