SDK Java Trace basé sur la configuration

Modifier en ligne

Le SDK de traçage Java, basé sur la configuration, permet de définir de manière déclarative les segments et les balises que ces segments doivent contenir, et crée des segments en exécutant certaines méthodes de votre application.

Son pouvoir d'expression est comparable à celui des fonctionnalités @Span d'annotation et SpanSupport.annotate() des outils du SDK Trace d' Java.

Avant de mettre en place un traçage personnalisé, consultez les bonnes pratiques en matière de traçage.

Introduction

Modifier en ligne

Le kit SDK basé sur la configuration est fragile face aux modifications de votre application. Vous pouvez renommer une classe ou une méthode, et tout d'un coup, la configuration ne correspond plus, et vous perdez vos données de trace. Dans la mesure du possible, nous vous recommandons d'utiliser le SDK de traçage d' Java, qui s'adapte bien mieux aux modifications du code et offre davantage de fonctionnalités pour vous aider à atteindre vos objectifs.

Configuration

Modifier en ligne

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.

Remarques :

  • Les modifications apportées à la configuration du SDK de traçage « Java » basé sur la configuration sont automatiquement prises en compte par l'agent « Instana ». Les applications déjà instrumentées doivent être redémarrées pour utiliser la configuration modifiée.

  • Le SDK de traçage « Java » basé sur la configuration est disponible dans la version 1.2.351Java Trace Sensor ou une version ultérieure.

Format

Modifier en ligne

La liste suivante décrit le format général de la configuration :

# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: 'interface'|'class'|'baseclass'
            name: '<type-name>'
            method: '<method-name>'
            [argumentTypes:
              - '<argument-type-index0>'
              - '<argument-type-indexn>']
            [returnType: '<return-type-name>']
          span:
            name: '<span-name>'
            [type: '<span-type>']
            [stackDepth: <depth>]
            [tags:
              - kind: 'argument'
                name: 'name'
                index: 0
              - kind: 'return'
                name: 'name'
              - kind: 'constant'
                name: 'name'
                value: 'constant-value']

Plusieurs cibles peuvent être définies dans la clé targets, chacune indiquant un span à créer. L'objet match d'une méthode target permet de déterminer à quelle méthode l'instrumentation doit s'appliquer. L'objet span indique comment générer le span, y compris son nom (qui est utilisé, par exemple, dans Analyse illimitée pour le filtre call.name), ainsi que les balises qui doivent être définies.

Correspondance des méthodes à instrumenter

Modifier en ligne
Remarque : l'instrumentation des interfaces ou des classes de base peut être très gourmande en ressources, en particulier dans les applications utilisant un grand nombre de classes, et doit être évitée dans la mesure du possible.

Cet objet décrit le point de code auquel une instrumentation doit avoir lieu :

  • type : type du code à instrumenter. Valeurs prises en charge :
    • class, correspondance avec une classe concrète
    • interface, correspondance avec toutes les classes implémentant l'interface
    • baseclass, correspondance avec toutes les classes étendant la classe de base
  • name: Nom complet de la classe, de l'interface ou de la classe de base à rechercher. Pour les classes imbriquées, la notation a.b.c.OutsideClass$NestedClass est requise
  • method : nom de la méthode de la classe, de l'interface ou de la classe de base spécifiée dont un appel doit être enregistré
  • argumentTypes : liste des types d'arguments qualifiés complets de la méthode à mettre en correspondance (facultatif)
    • Si omis, les arguments ne sont pas mis en correspondance, et l'instrumentation est appliquée à toutes les méthodes en cas de surcharge.
    • Si présent, tous les arguments doivent correspondre aux types indiqués dans l'ordre pour que la méthode corresponde.
  • returnType : type qualifié complet retourné de la méthode à mettre en correspondance (facultatif)
    • Si omis, le type de retour n'est pas pris en compte.
    • Si présent, le type de retour doit correspondre au type donné pour que la méthode corresponde.

Spécification de la présentation des spans

Modifier en ligne

Cet objet décrit les propriétés du span qui sera créé si la méthode décrite dans match est appelée :

  • name : nom du span
  • type : type de span. Valeurs prises en charge :
    • ENTRY, utilisé pour indiquer les appels « entrants » depuis les systèmes externes
    • INTERMEDIATE, utilisé pour capturer les appels internes aux méthodes « intéressantes » (par défaut)
    • EXIT, utilisé pour indiquer les appels « sortants » vers les systèmes externes
  • stackDepth : nombre de cadres de pile pour capturer l'appel de la méthode (facultatif). La valeur par défaut est 0
  • tags : liste des balises/annotations à capturer et comment obtenir leurs valeurs (facultatif). Valeurs prises en charge :
    • constant, capture une valeur constante
      • kind: constant
      • name : nom de la balise à créer
      • value : valeur constante de la balise à créer
    • return, capture la valeur de retour de l'appel de méthode
      • kind: return
      • name : nom de la balise à créer. La valeur est la valeur de l'objet renvoyé
    • argument, capture une valeur d'argument spécifique de l'appel de méthode
      • kind: argument
      • name : nom de la balise à créer
      • index : index basé sur 0 de l'argument à capturer en tant que valeur de la balise
Remarque : si la valeur capturée est null ou, Optional.empty la balise définie ne sera pas ajoutée. Les périodes pour lesquelles il manque des balises peuvent être recherchées dans Unbounded Analytics à l'aide de is not present l'opérateur associé au call.tag filtre.

Spans erronés

Modifier en ligne

Si une valeur Throwable sort du cadre d'une méthode instrumentée, la plage sera automatiquement signalée comme erronée, et la valeur de Throwable#getMessage() sera définie comme message d'erreur, que vous pourrez rechercher dans Unbounded Analytics à l'aide de la call.error.message balise.

Vérification de la configuration de votre SDK

Modifier en ligne
  1. Vérifiez que la configuration a bien été analysée. Dans les journaux de l'agent, recherchez un message similaire à celui-ci :
    Parsed configuration file /instana-agent/etc/instana/configuration.yaml
  2. Vérifiez que l'instrumentation a bien été mise en place. Une fois l'analyse terminée, l'agent enregistrera un message indiquant qu'il a procédé à l'instrumentation du SDK :
    ... Spent XX ms and XXX KiB of Metaspace for instrumentation [sdk] ...
  3. Activer et vérifier les journaux de traçage des spans du SDK. Pour vérifier que les spans sont bien créés, activez la journalisation de trace en ajoutant l' YAML suivante :
    com.instana.plugin.javatrace: instrumentation: log: type: trace file: /tmp/trace.log

Une fois l'instrumentation activée et le code instrumenté exécuté, vous devriez voir apparaître des segments SDK. Exemple de format de journal de trace :

 -|EN|052d6bf37f16034c7:0:52d6bf37f16034c7|sdk:sdk.quarkus-hello|*com.instana.agent.instrumentation.sdk.SdkPlugin:start:789:SdkPlugin.java

Exemple

Modifier en ligne

L'extrait de code suivant montre un exemple de configuration de la façon dont une application traitant des travaux par lots peut être tracée :

com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: processBatch
          span:
            name: Job
            type: ENTRY
            stackDepth: 2
            tags:
              - kind: constant
                name: endpoint
                value: BatchJob
              - kind: argument
                name: batch.job
                index: 0
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: updateDatabase
          span:
            name: DatabaseCall
            type: EXIT
            stackDepth: 2
            tags:
              - kind: constant
                name: db.connection_string
                value: jdbc:mysql://127.0.0.1:3306/jobs
              - kind: argument
                name: db.statement
                index: 0

D'abord, la méthode processBatch de la classe com.instana.java.sdk.BatchApplication est instrumentée pour créer des spans d'entrée avec le nom Job, l'annotation endpoint avec la valeur constante BatchJob et l'annotation batch.job avec le premier argument comme valeur.

En outre, les appels de base de données sortants pendant le traitement par lots, c'est-à-dire les appels de méthode updateDatabase dans la même classe, créent des spans de sortie portant le nom DatabaseCall et l'annotation db.connection_string avec la valeur constantejdbc:mysql://127.0.0.1:3306/jobs et l'annotation db.statement avec le premier argument de l'appel de méthode.

Le traitement d'un nouveau lot avec processBatch démarrera une nouvelle trace, et les mises à jour ultérieures de base de données avec updateDatabase y seront répertoriées en tant que spans enfants. Toutes les fonctions Instana, comme l'Analyse illimitée, peuvent être utilisées de la même manière que les traces créées avec Instana AutoTrace.

Limitations

Modifier en ligne

Les restrictions suivantes s'appliquent au kit SDK Java Trace basé sur la configuration :

  • L'instrumentation des constructeurs n'est pas prise en charge.
  • Le démarrage d'un span dans une méthode et sa fermeture dans une autre ne sont pas pris en charge, c'est-à-dire que le kit SDK basé sur la configuration n'a pas d'équivalent pour les annotations @Span.Start et @Span.End.
  • La capture de tous les arguments ou de la valeur de retour sans la création explicite d'un tag n'est pas prise en charge.
  • Il n'est pas possible d'utiliser des placeholders dans la liste d'arguments pour les arguments non essentiels ou pour tous les autres; la correspondance basée sur les arguments est effectuée de manière stricte.
  • La spécification de modèles de noms pour les classes ou les méthodes n'est pas prise en charge.
  • La restauration d'un contexte de trace avant de créer un span n'est pas prise en charge, c'est-à-dire que le kit SDK basé sur la configuration ne possède pas de fonctionnalité équivalente à SpanSupport.inheritNext().
  • Le SDK basé sur la configuration ne prend pas en charge l'instrumentation des classes JDK.