Kit SDK Java Trace

Pour utiliser le SDK Java Trace basé sur la configuration, vous devez activer le SDK Java Trace comme décrit dans Activation du SDK Java Trace.

L'exemple d'application publié (https://github.com/instana/instana-java-sdk/tree/master/instana-java-sdk-sample) contient un serveur et un client CustomTCP , illustrant comment le SDK peut être utilisé pour le marquage des entrées, des exits et des corrélations.

Le SDK de traçage d' Java nécessite l'ajout d'un fichier JAR à votre application. Ce fichier jar contient les annotations et les classes Helper utilisées pour le marquage des sections de code qu'Instana doit traiter. Lors de l'utilisation de Maven, la dépendance peut être facilement ajoutée avec :

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

L'artefact instana-java-sdk est disponible dans le référentiel central Maven par défaut.

Lorsqu'aucun agent ne surveille l' JVM, qui comprend cette bibliothèque et comporte des sections marquées d'annotations, celles-ci agissent comme des opérations sans effet. Vous pouvez utiliser les annotations en toute sécurité, car elles n'ont aucun impact tant qu'aucun agent ne surveille la machine JVM. Pour qu'un agent Instana utilise les annotations, vous devez indiquer les noms de package Java ayant ces annotations. En effet, la recherche d'annotations est un processus gourmand en ressources, et l'analyse de l'intégralité du classpath d'applications volumineuses peut prendre beaucoup de temps.

La configuration.yaml section requise se présente comme suit :

# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    # By default no packages are scanned for SDK annotations.
    sdk:
      packages:
        - 'com.mycompany.backend'
        - 'com.mycompany.frontend'
 

Les packages sont analysés de manière récursive. À savoir, si com.mycompany.backend est configuré pour être analysé pour les annotations, com.mycompany.backend.impl et les autres sous-packages sont également analysés.

Pour marquer une méthode dans un span intermédiaire, ajoutez simplement l'annotation suivante :

@Span(value = "custom-tcp-server")

Intermédiaire est le type par défaut du kit SDK et utilisé, sauf indication contraire. Ce type de span marque les méthodes « intéressantes » dans l'application pour lesquelles vous souhaitez disposer d'une meilleure visibilité. Veuillez noter que cela ne remplace en aucun cas un véritable outil de profilage, comme notre Instana AutoProfile™.

Pour marquer une méthode dans une balise Entry, il suffit d'ajouter l'annotation suivante, comme le montre cet exemple :

@Span(type = Type.ENTRY, value = "custom-tcp-server")

Dès qu'Instana détecte le code entrant dans cette méthode, une trace est démarrée. Les spans d'entrée indiquent normalement les appels entrants provenant des systèmes externes ou des tâches planifiées.

Pour marquer une méthode dans une section « Exit », il suffit d'ajouter l'annotation suivante, comme le montre cet exemple :

@Span(type = Type.EXIT, value = "custom-tcp-client", capturedStackFrames = 5)

Chaque fois que cette méthode est détectée, Instana enregistre un span en le marquant comme appel de sortie. Les sorties marquent les appels sortants vers les systèmes externes.

Dans la plupart des cas où une sortie et une entrée ne sont pas encore connues d'Instana, les applications les utilisent pour effectuer une sorte de communication à distance. Lorsqu'une sortie est détectée et qu'aucune corrélation n'est effectuée, la trace se « rompt », c'est-à-dire que deux traces sont observées : l'une se terminant à la sortie et une nouvelle commençant à l'entrée.

Il est possible d'aider Instana à effectuer une corrélation en transportant manuellement les informations de corrélation dans la communication distante. Côté sortie, l'annotation de sortie vérifie que les identificateurs de corrélation requis existent. Il suffit d'appeler ( https://github.com/instana/instana-java-sdk/blob/master/instana-java-sdk/src/main/java/com/instana/sdk/support/SpanSupport.java#L182 ) :

SpanSupport.addTraceHeadersIfTracing(Type.EXIT, params);

pour remplir la mappe de paramètres avec les ID requis. Si le protocole prend en charge d'autres moyens de transporter d'autres données, il est possible d'obtenir les ID avec ce qui suit :

currentTraceId(type)

currentSpanId(type)

Côté entrée, il est important de lire les paramètres et de les définir pour le span d'entrée avant que le span soit créé par les annotations :

(https://github.com/instana/instana-java-sdk/blob/master/instana-java-sdk-sample/custom-http-sample/src/main/java/com/instana/sample/GreetingHandler.java#L52):

SpanSupport.inheritNext(SpanSupport.stringAsId(trace), SpanSupport.stringAsId(span));

Ainsi, le span d'entrée rejoint automatiquement la trace distante et s'ajoute en tant que span enfant de la sortie appelante.

Dans certains cas, il peut être avantageux de transformer les spans SDK en un autre type, tel que HTTP ou RPC, pour mieux représenter leur origine. Pour ce faire, il suffit d'ajouter des balises de conversion aux éléments `span`, comme décrit dans la section consacrée aux balises de traitement des bonnes pratiques en matière de traçage personnalisé.

Ces balises peuvent être définies à l'aide de la méthode SpanSupport.annotate(type, name, key, value) .

Instana traitera ces balises de la même manière que le système d'instrumentation automatique des agents dès que ces champs seront imbriqués sous la tags. clé. Ainsi, par exemple, pour définir la zone http.url, l'appel de méthode se présente comme suit :

SpanSupport.annotate(<type>, <name>, "tags.http.url", "service://my-awesome-service/some/path")

De la même manière, il est également possible de modifier le service, le point de terminaison et le nom de l'appel, comme indiqué dans la page consacr ée aux bonnes pratiques en matière de traçage personnalisé.

Lorsque aucune zone spécifique n'est fournie, le nom du service de tous les spans SDK est SDK. Le noeud final et le nom d'appel seront les name indiqués dans l'annotation @Span ou dans la méthode SpanSupport.annotate() .

La classe ContextSupport permet de sauvegarder et de restaurer le contexte de trace en cours. La méthode takeSnapshot() stocke les informations de contexte de trace, telles que l'ID de trace et l'ID de plage, dans une mappe interne. La méthode restoreSnapshot() lit les informations qui ont été sauvegardées par la méthode takeSnapshot() et les utilise pour définir le contexte de trace en cours. Ces méthodes sont utiles dans les situations où une application utilise le traitement asynchrone pour effectuer une tâche et que la trace doit être poursuivie dans une autre unité d'exécution.

Par exemple, le contexte de trace actuel peut être sauvegardé avec:

snapShotKey = ContextSupport.takeSnapshot();

Ensuite, le contexte de trace peut être restauré dans une autre unité d'exécution avec:

ContextSupport.restoreSnapshot(snapShotKey);

Les tutoriels suivants vous guideront dans certains cas d'utilisation courants du kit SDK Java Trace :

• Implémentation d'un framework personnalisé pour l'instrumentation d' Java HTTP
• Mise en place d'un planificateur personnalisé
• Implémentation d'une fonction intermédiaire personnalisée

Si les traces SDK ne s'affichent pas dans l'interface utilisateur, vous devez vérifier plusieurs éléments :

• Le fichier jar instana-java-sdk est-il fourni avec l'application ? Si ce n'est pas le cas, l'agent ne fait rien silencieusement, car il est en mode no-op.
• Le fichier configuration.yaml fait-il référence à tous les packages avec des annotations?
• Le traçage est-il activé ?
• La syntaxe YAML est-elle correcte ?
• D'autres agents APM sont-ils actifs ? La plupart des autres agents APM sont connus pour interférer avec Instana. Par conséquent, l'agent d'Instana n'exécutera pas le traçage s'il détecte d'autres agents. Si tel est le cas, les éléments suivants figurent dans les journaux :

  JVM <PID> is running the <3rdParty> agent, which is known to be causing problems for the Instana Agent. Tracing will not be enabled for this JVM.
   

• Activez la journalisation DEBUG et recherchez un message du type :

  2016-09-05T08:26:14.094+0200 | DEBUG | na-http-thread-1 | LoggerEndpoint                   | 48 - com.instana.agent - 1.1.194 | JVM (11403). Successfully instrumented class com.acme.resources.HelloWorldResource [sun.misc.Launcher$AppClassLoader@3d4eac69]`
  2016-09-05T08:26:14.145+0200 | DEBUG | na-http-thread-1 | LoggerEndpoint                   | 48 - com.instana.agent - 1.1.194 | JVM (11403) - Spent 188ms and 124kb transforming SDK classes. 
   

• Les méthodes annotées sont-elles réellement appelées par un utilisateur/un pilote de chargement ? L'agent Instana interagira avec chaque machine JVM peu après son démarrage. Par conséquent, les transactions qui ont lieu avant que l'agent soit attaché ne sont pas capturées. Veillez à annoter les méthodes qui sont normalement appelées au cours de la durée de vie de l'application.
• Suivez les étapes décrites dans la section « Vérification de la configuration de votre SDK ».