Konfigurationsbasiertes Java-Trace-SDK

Das konfigurationsbasierte SDK reagiert empfindlich auf Änderungen an der Anwendung. Sie können eine Klasse oder eine Methode umbenennen, und plötzlich stimmt die Konfiguration nicht mehr überein, und Sie verlieren Ihre Tracedaten. Wir empfehlen Ihnen, nach Möglichkeit das „ Java Trace SDK“ zu verwenden, da dieses wesentlich widerstandsfähiger gegenüber Codeänderungen ist und über mehr Funktionen verfügt, die Ihnen bei der Erreichung Ihrer Ziele helfen.

Um das konfigurationsbasierte „ Java “-Trace-SDK zu verwenden, müssen Sie das „ Java “-Trace-SDK wie unter „Aktivieren des „ Java “-Trace-SDK“ beschrieben aktivieren.

Hinweise:

• Änderungen an der Konfiguration des konfigurationsbasierten „ Java Trace SDK“ werden vom „ Instana “-Agenten automatisch übernommen. Bereits instrumentierte Anwendungen müssen erneut gestartet werden, damit die geänderte Konfiguration verwendet werden kann.

• Das konfigurationsbasierte „ Java “-Trace-SDK ist in der Version „ 1.2.351Java “-Trace-Sensor oder höher verfügbar.

In der folgenden Liste wird das allgemeine Format der Konfiguration beschrieben:

# 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']
 

Innerhalb des Schlüssels targets (Ziele) können mehrere Ziele definiert werden, die jeweils eine zu erstellende Spanne angeben. Das Objekt match eines target gibt die Methode an, auf die die Instrumentierung angewendet werden soll. Das Objekt span gibt an, wie die Spanne erstellt wird, einschließlich ihres Namens (der z. B. in unbegrenzten Analysen für den Filter call.name verwendet wird) und welche Tags gesetzt werden sollen.

Wenn sich Throwable außerhalb einer instrumentierten Methode ausbreitet, wird die Spanne automatisch als fehlerhaft markiert, und der Wert von Throwable#getMessage() wird als Fehlermeldung festgelegt, nach der Sie in Unbounded Analytics über das call.error.message Tag suchen können.

1. Überprüfen Sie, ob die Konfiguration erfolgreich geparst wurde. Suchen Sie in den Agent-Protokollen nach einer Meldung, die in etwa wie folgt lautet:

   Parsed configuration file /instana-agent/etc/instana/configuration.yaml 

2. Überprüfen Sie, ob die Instrumentierung angewendet wurde. Nach der Analyse protokolliert der Agent eine Meldung, aus der hervorgeht, dass er die SDK-Instrumentierung durchgeführt hat:

   ... Spent XX ms and XXX KiB of Metaspace for instrumentation [sdk] ... 

3. Aktivieren und überprüfen Sie die SDK-Span-Trace-Protokolle. Um zu überprüfen, ob Spans tatsächlich erstellt werden, aktivieren Sie die Trace-Protokollierung, indem Sie Folgendes unter „ YAML “ hinzufügen:

   com.instana.plugin.javatrace: instrumentation: log: type: trace file: /tmp/trace.log 

Sobald die Instrumentierung aktiv ist und der instrumentierte Code ausgeführt wird, sollten SDK-Spans ausgegeben werden. Beispiel für ein Trace-Protokollformat:

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

Das folgende Snippet zeigt eine Beispielkonfiguration, in der beschrieben wird, wie eine Anwendung, die Batch-Jobs verarbeitet, verfolgt werden kann:

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
 

Als erstes wird die Methode processBatch in der Klasse com.instana.java.sdk.BatchApplication instrumentiert, um Eingangsspannen mit dem Namen Job, der Annotation endpoint mit dem konstanten Wert BatchJob und der Annotation batch.job mit dem ersten Argument als zugehörigen Wert zu erstellen.

Zudem erstellen abgehende DB-Aufrufe während der Batchverarbeitung, d. h. Aufrufe der Methode updateDatabase in derselben Klasse, Ausgangsspannen mit dem Namen DatabaseCall und der Annotation db.connection_string mit dem konstanten Wert jdbc:mysql://127.0.0.1:3306/jobs und der Annotation db.statement mit dem ersten Argument des Methodenaufrufs.

Bei der Verarbeitung eines neuen Batches mit processBatch wird ein neuer Trace gestartet und nachfolgende DB-Aktualisierungen mit updateDatabase werden als untergeordnete Spannen innerhalb dieses Trace aufgelistet. Alle Instana-Funktionen, wie z. B. "Unbegrenzte Analyse", können auf dieselbe Weise auf mit Instana AutoTrace erstellte Traces angewendet werden.

Die folgenden Einschränkungen gelten für das konfigurationsbasierte Java-Trace-SDK:

• Die Instrumentierung von Konstruktoren wird nicht unterstützt.
• Das Starten einer Spanne in einer Methode und das Schließen in einer anderen wird nicht unterstützt. Das heißt, das konfigurationsbasierte SDK hat keine Entsprechung für die Annotationen @Span.Start und @Span.End.
• Das Erfassen aller Argumente oder des Rückgabewerts ohne explizite Erstellung eines tag wird nicht unterstützt.
• Die Angabe von Platzhaltern in der Argumentliste für unwichtige Argumente oder alle übrigen Argumente wird nicht unterstützt; die argumentbasierte Übereinstimmung wird streng durchgeführt.
• Das Angeben von Namensmustern für Klassen oder Methoden wird nicht unterstützt.
• Das Wiederherstellen eines Tracekontextes vor dem Erstellen einer Spanne wird nicht unterstützt. Das heißt, das konfigurationsbasierte SDK hat keine funktionelle Entsprechung zu SpanSupport.inheritNext().
• Das konfigurationsbasierte SDK unterstützt keine Instrumentierung von JDK-Klassen.