Tutoriel : Instrumentation d'une fonction intermédiaire personnalisée avec le SDK de traçage d' Instana

Modifier en ligne

Vous pouvez utiliser le SDK de traçage d' Instana pour instrumenter des fonctions intermédiaires personnalisées et obtenir une visibilité sur la logique d'application qui n'est pas automatiquement instrumentée par Instana.

Exemple de code

Pour obtenir un exemple de code pour le custom-intermediate-span-samplee tutoriel, consultez l'exemple d'intervalle intermédiaire personnalisé. Il montre comment utiliser le SDK Instana Java pour créer des spans intermédiaires personnalisés dans une application Spring Boot avec MongoDB.

Instrumentation d'une fonction intermédiaire personnalisée

Suivez ces étapes pour activer le SDK Tracer d' InstanaJava et instrumenter une fonction intermédiaire personnalisée :

Ajoutez le SDK Trace d' Java s en tant que dépendance. Si vous utilisez Maven, ajoutez la dépendance suivante à votre .xml fichier :

<dependency>
    <groupId>com.instana</groupId>
    <artifactId>instana-java-sdk</artifactId>
    <version>1.2.0</version>
</dependency>

Pour permettre la détection des annotations SDK, spécifiez les noms de packages Java avec les annotations SDK dans le configuration.yaml fichier.
```
# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    # By default no packages are scanned for SDK annotations.
    sdk:
      packages:
          - 'com.instana.sample.application'
```
Remarque : les paquets spécifiés sont analysés de manière récursive, il suffit donc de spécifier uniquement le nom du paquet le plus courant.

Ajoutez une annotation span à une fonction pour la capturer dans une trace.

Avec le SDK Tracer d' InstanaJava, vous pouvez attribuer l'un des trois types de span à une méthode afin de définir son rôle dans une trace. Pour capturer une fonction spécifique, ajoutez l'annotation span appropriée à la définition de la fonction.

@Span(type = Type.INTERMEDIATE, value = "custom-instana-java-sdk")

Exemple de code :

@Span(type = Span.Type.INTERMEDIATE, value = SPAN_NAME)
public List<Profile> all(Boolean error) {
    try {
        if (error) {
            throw new Exception();
        }
        SpanSupport.annotate(Span.Type.INTERMEDIATE, SPAN_NAME, "tags.instana.java.sdk", "Success");
        return getAll();
    } catch (Exception e) {
        SpanSupport.annotate(Span.Type.INTERMEDIATE, SPAN_NAME, "tags.error", "true");
        SpanSupport.annotate(Span.Type.INTERMEDIATE, SPAN_NAME, "tags.instana.java.sdk", "Fail");
    }
    return Collections.emptyList();
}

private List<Profile> getAll() {
    return profileRepository.findAll();
}

Facultatif : ajoutez des informations supplémentaires à l'annotation.

Dans certaines situations, l'ajout d'informations pertinentes aux spans SDK peut mieux représenter leur origine. Pour ajouter des attributs span, intégrez des balises de conversion dans les spans. Ces balises peuvent être définies à l'aide de la SpanSupport.annotate(type, name, key, value) méthode.
```
SpanSupport.annotate(Span.Type.INTERMEDIATE, SPAN_NAME, "tags.instana.java.sdk","Success");
```
Figure 1. Détails de la portée réussie
Facultatif : marquer une portée comme erronée.

Pour signaler un appel comme erroné, ajoutez la error balise :
```
SpanSupport.annotate(Span.Type.INTERMEDIATE, SPAN_NAME, "tags.error","true");
```
Pour afficher la trace complète, y compris la portée intermédiaire personnalisée et ses annotations, dans l'interface utilisateur d' Instana, exécutez les commandes suivantes.

Pour afficher une trace réussie, exécutez :
```
curl -X 'GET' 'http://localhost:8081/v1/instana/profile?error=false' -H 'accept: application/json'
```
Figure 2. Portée réussie

Pour afficher une trace d'erreur, exécutez :
```
curl -X 'GET' 'http://localhost:8081/v1/instana/profile?error=true' -H 'accept: application/json'
```
Figure 3 Intervalle d'erreur

Figure 4 Détails de la plage d'erreur

Récapitulatif et perspective

Ce tutoriel crée un nouveau contexte de trace pour une fonction intermédiaire personnalisée, permettant ainsi à l'exécution de cette fonction d'être reconnue comme une période intermédiaire dans Instana.

Le concept de portée améliore la granularité de l'observation, en classant les appels en entrants, sortants et internes, offrant ainsi des informations détaillées. Le processus d'intégration simple du SDK, illustré par les dépendances et les fichiers de configuration d' Maven, facilite son incorporation transparente dans les applications.

Pour obtenir une référence complète sur le SDK Java d' Instana, consultez Java Trace SDK. Par exemple, les @SpanParam annotations @SpanReturn et facilitent la capture de paramètres ou de valeurs de retour en tant qu'informations supplémentaires, ce qui peut s'avérer plus pratique que d'appeler SpanSupport.annotate() explicitement dans certains scénarios.