Tutorial: Implementierung einer benutzerdefinierten Zwischenfunktion mit dem Tracing SDK von „ Instana “

Online bearbeiten

Mit dem SDK „ Instana Tracing“ können Sie benutzerdefinierte Zwischenfunktionen instrumentieren und Einblick in Anwendungslogik gewinnen, die nicht automatisch von „ Instana “ instrumentiert wird.

Beispielcode

Ein Beispielcode für das custom-intermediate-span-samplee Tutorial finden Sie unter „Beispiel für eine benutzerdefinierte Zwischenspannweite “. Es zeigt, wie Sie das SDK „ Instana “ ( Java ) verwenden, um benutzerdefinierte Zwischenspannen in einer „ Spring Boot “-Anwendung mit „ MongoDB “ zu erstellen.

Implementierung einer benutzerdefinierten Zwischenfunktion

Befolgen Sie diese Schritte, um das Tracer SDK „ InstanaJava “ zu aktivieren und eine benutzerdefinierte Zwischenfunktion zu instrumentieren:

Fügen Sie das Trace SDK „ Java “ als Abhängigkeit hinzu. Wenn Sie Maven verwenden, fügen Sie die folgende Abhängigkeit zu Ihrer .xml Datei hinzu:
```
<dependency>
    <groupId>com.instana</groupId>
    <artifactId>instana-java-sdk</artifactId>
    <version>1.2.0</version>
</dependency>
```
Um die Erkennung von SDK-Anmerkungen zu aktivieren, geben Sie die Paketnamen „ Java “ mit SDK-Anmerkungen in der configuration.yaml Datei an.
```
# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    # By default no packages are scanned for SDK annotations.
    sdk:
      packages:
          - 'com.instana.sample.application'
```
Hinweis: Die angegebenen Pakete werden rekursiv gescannt, daher reicht es aus, nur den gängigsten Paketnamen anzugeben.

Fügen Sie einer Funktion eine Span-Annotation hinzu, um sie in einer Ablaufverfolgung zu erfassen.

Mit dem Tracer SDK „ Instana “ ( Java ) können Sie einer Methode einen von drei Spantypen zuweisen, um ihre Rolle in einer Ablaufverfolgung zu definieren. Um eine bestimmte Funktion zu erfassen, fügen Sie der Funktionsdefinition die entsprechende Span-Annotation hinzu.

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

Beispielcode:

@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();
}

Optional: Fügen Sie der Spanne zusätzliche Informationen hinzu.

In bestimmten Situationen kann das Hinzufügen relevanter Informationen zu SDK-Spans deren Ursprung besser darstellen. Um Span-Attribute hinzuzufügen, fügen Sie Konvertierungs-Tags in die Spans ein. Diese Tags können mit der SpanSupport.annotate(type, name, key, value) Methode gesetzt werden.
```
SpanSupport.annotate(Span.Type.INTERMEDIATE, SPAN_NAME, "tags.instana.java.sdk","Success");
```
Abbildung 1. Erfolgreiche Spannweitenangaben
Optional: Markieren Sie einen Bereich als fehlerhaft.

Um einen Aufruf als fehlerhaft zu kennzeichnen, fügen Sie das error Tag ein:
```
SpanSupport.annotate(Span.Type.INTERMEDIATE, SPAN_NAME, "tags.error","true");
```
Um die vollständige Ablaufverfolgung einschließlich der benutzerdefinierten Zwischenspanne und ihrer Anmerkungen in der Benutzeroberfläche von „ Instana “ anzuzeigen, führen Sie die folgenden Befehle aus.

Um eine erfolgreiche Ablaufverfolgung anzuzeigen, führen Sie Folgendes aus:
```
curl -X 'GET' 'http://localhost:8081/v1/instana/profile?error=false' -H 'accept: application/json'
```
Abbildung 2. Erfolgreiche Spannweite

Um einen Fehlerverlauf anzuzeigen, führen Sie Folgendes aus:
```
curl -X 'GET' 'http://localhost:8081/v1/instana/profile?error=true' -H 'accept: application/json'
```
Abbildung 3. Fehlerbereich

Abbildung 4. Fehlerbereichsdetails

Zusammenfassung und Ausblick

Dieses Tutorial erstellt einen neuen Trace-Kontext für eine benutzerdefinierte Zwischenfunktion, sodass die Ausführung dieser Funktion in „ Instana “ als Zwischenspan erkannt werden kann.

Das Spanne-Konzept verbessert die Beobachtungsgenauigkeit, indem es Anrufe in eingehende, ausgehende und interne Anrufe kategorisiert und detaillierte Einblicke bietet. Der einfache Integrationsprozess des SDK, der durch „ Maven “-Abhängigkeiten und Konfigurationsdateien veranschaulicht wird, erleichtert die nahtlose Einbindung in Anwendungen.

Eine vollständige Referenz zum SDK „ InstanaJava “ finden Sie unter „ Java Trace SDK “. Beispielsweise erleichtern die Annotationen @SpanParam@SpanReturn und das Erfassen von Parametern oder Rückgabewerten als zusätzliche Informationen, was in manchen Szenarien praktischer sein kann als der explizite Aufruf SpanSupport.annotate() von.