Benutzerdefinierte Instrumentierung mit OpenTelemetry custom-instrumentation

Wenn OpenTelemetry für Ihre Umgebung aktiviert ist, verfolgt AEM as a Cloud Service jede Anfrage und exportiert JVM-, HTTP- und AEM-Metriken automatisch. Diese Telemetrie beschreibt AEM. Es zeigt an, dass das Rendern einer Seite 900 Millisekunden gedauert hat und welche Komponenten sie gerendert hat. Es kann nicht angezeigt werden, was Ihr eigener Code getan hat, z. B. für welches Listenelement eine Repository-Abfrage durchgeführt wurde und ob sie etwas gefunden hat, oder welche Seiten auf eine teure Suche zurückfallen, da ein Autor ein Feld ausgelassen hat.

Sie können dieses Wissen selbst mit der OpenTelemetry-API hinzufügen. Die Bereiche und Attribute, die Ihr Code erstellt, bewegen sich mit der automatischen Telemetrie: derselbe Service-Name, dieselbe Verarbeitung, derselbe APM-Provider. Sie konfigurieren in Ihrem Code keinen Endpunkt, keine Berechtigung und keinen Exporter.

Wenn Sie mit OpenTelemetry auf AEM as a Cloud Service noch nicht vertraut sind, beginnen Sie mit dem Tutorial Observability via OpenTelemetry, um mehr über die Funktionsweise zu erfahren. Folgen Sie dann OpenTelemetry für Einblicke in AEM-Anwendungen konfigurieren um sie für Ihre Umgebung zu aktivieren.

Die Beispiele auf dieser Seite instrumentieren die WKND-Referenz-Site. Jedes Beispiel beschreibt, was Sie erreichen möchten, den hinzuzufügenden Code und das Ergebnis, das Sie bei Ihrem APM-Anbieter erwarten können. Der vollständige instrumentierte Code, einschließlich der Komponententests, die für die Bereiche gelten, befindet sich auf der tutorial/otel-custom-instrumentation Verzweigung des WKND-Repositorys.

Funktionsweise der benutzerdefinierten Instrumentierung how-it-works

Einrichten eines Projekts set-up-project

Schritt 1: OpenTelemetry-API hinzufügen add-api

Fügen Sie die OpenTelemetry-API und die Instrumentationsanmerkungen zum dependencyManagement Abschnitt der übergeordneten pom.xml Ihres Projekts mit dem provided:

<properties>
    <opentelemetry.version>1.61.0</opentelemetry.version>
    <opentelemetry-instrumentation.version>2.27.0</opentelemetry-instrumentation.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-api</artifactId>
            <version>${opentelemetry.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-instrumentation-annotations</artifactId>
            <version>${opentelemetry-instrumentation.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Fügen Sie dann beide Abhängigkeiten (ohne Versionen) zum pom.xml jedes Bundles hinzu, das sie verwendet, z. B. core/pom.xml:

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-instrumentation-annotations</artifactId>
</dependency>

Verwenden Sie opentelemetry-api 1.61.0 und opentelemetry-instrumentation-annotations 2.27.0 oder frühere Versionen. Sie stimmen mit dem von AEM as a Cloud Service ausgeführten OpenTelemetry-Java-Agenten überein, und neuere Versionen des Agenten unterstützen sie weiterhin. API-Funktionen, die nach der vom Agenten unterstützten Version hinzugefügt wurden, haben keine Auswirkungen.

Schritt 2: Einbetten der API in das Bundle embed-api

AEM as a Cloud Service exportiert die OpenTelemetry-API-Pakete nicht, sodass jedes Bundle, das die API verwendet, eine eigene Kopie enthalten muss. Fügen Sie die folgenden Anweisungen zur Bandkonfiguration Ihres Bundles hinzu. Mit dem AEM-Projektarchetyp 🔗 ist dies die bnd-maven-plugin in core/pom.xml. Behalten Sie alle Einträge bei, die bereits in Ihrer Import-Package enthalten sind.

Import-Package: !io.opentelemetry.*,javax.annotation;version=0.0.0,*
-includepackage: io.opentelemetry.*

Jedes Bundle, das die -API verwendet, bettet eine eigene Kopie ein, und der Agent verbindet jede Kopie separat.

Schritt 3: Erstellen eines Tracers create-tracer

Erstellen Sie eine Tracer für Ihre Code-Basis und verwenden Sie sie überall wieder. In WKND wird sie von einer kleinen Klasse gespeichert:

package com.adobe.aem.guides.wknd.core.telemetry;

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Tracer;

public final class WkndTelemetry {

    /** Instrumentation scope: identifies telemetry produced by WKND code in your APM provider. */
    public static final String SCOPE = "com.adobe.aem.guides.wknd";

    public static final Tracer TRACER = GlobalOpenTelemetry.getTracer(SCOPE);

    private WkndTelemetry() {
    }
}

Der Bereichsname wird in jedem Bereich, den Sie durch diesen Tracer erstellen, als Instrumentationsbereich (oder Bibliotheksname) angezeigt. Verwenden Sie einen Namen, der Ihren Code identifiziert, z. B. das Java-Basispaket Ihres Projekts.

Wo Ihre Spannen angezeigt werden where-spans-appear

In AEM as a Cloud Service erzeugt eine Seitenanfrage bereits Bereiche aus AEM selbst. Die Bereiche, die Ihr Code erstellt, werden darin hinzugefügt. Dies ist beispielsweise der Pfad zur Bildlisten-Komponente in einer Spur der WKND-Magazinseite:

GET /*                                                     the request (AEM)
└─ SlingMainServlet.service                                Sling request processing (AEM)
   └─ AEM component: cq:Page                               (AEM)
      └─ AEM component: wknd/components/page               the page component (AEM)
         └─ HTL: libs.core.wcm.components.page.v3.page.page__002e__html
            └─ ...                                         containers and layout grids (AEM)
               └─ AEM component: wknd/components/image-list
                  └─ HTL: apps.wknd.components.image__002d__list.image__002d__list__002e__html
                     └─ ...                                spans that the Image List's Sling Model creates

Während eine Komponente gerendert wird, ist die Spanne ihres HTL-Skripts die aktuelle Spanne. Ein Sling-Modell, das mit data-sly-use geladen wird, wird innerhalb dieses Bereichs ausgeführt und umfasst so viele Elemente, dass das Modell als untergeordnete Elemente erstellt wird.

Jeder Anfragebereich erhält den Namen GET /* (oder POST /* usw.). Um die Ablaufverfolgungen für eine bestimmte Seite zu finden, suchen Sie nach dem url.path Attribut des Anfragebereichs oder fügen Sie Ihre eigenen Attribute hinzu, wie in Beispiel 3 dargestellt.

Beispiele examples

Beispiel 1: Verfolgen eines teuren Vorgangs trace-operation

Was Sie erreichen möchten trace-operation-goal

Die WKND-Bildlisten-Komponente (wknd/components/image-list) zeigt eine Liste von Seiten mit jeweils dem ersten Bild an. Um dieses Bild zu finden, führt das Sling-Modell ImageListImpl für jedes Element in der Liste eine QueryBuilder-Abfrage aus. In AEMs eigenen Bereichen werden diese Abfragen bereits angezeigt: Auf der WKND-Magazinseite, auf der fünf Artikel aufgelistet sind, enthält der Trace fünf JCR query Bereiche unter dem HTL-Bereich der Bildliste. Sie zeigen nicht an, für welches Listenelement jede Abfrage war, ob ein Bild gefunden wurde oder wie viel Zeit mit der Verarbeitung der Ergebnisse verbracht wurde. Der ursprüngliche Code synchronisierte die Abfrage mit System.currentTimeMillis() und schrieb das Ergebnis in einen DEBUG Protokolleintrag, der in der Produktion nicht verfügbar ist. Jede Abfrage soll in der Ablaufverfolgung als benannter Vorgang mit diesem Kontext angezeigt werden.

Der Code trace-operation-code

Erstellen Sie ImageListImpl.findPageComponentResources() einen Bereich um die Abfrage:

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.context.Scope;

// ... build the QueryBuilder parameters, as before

final Span span = WkndTelemetry.TRACER.spanBuilder("ImageList.findPageComponentResources")
        .setAttribute("wknd.query.path", page.getContentResource().getPath())
        .setAttribute("wknd.query.resource_type", slingResourceType)
        .setAttribute("wknd.query.limit", limit)
        .startSpan();

try (Scope ignored = span.makeCurrent()) {
    // ... run the query and collect the resources, as before

    span.setAttribute("wknd.query.result_count", componentResources.size());
} catch (RuntimeException e) {
    span.recordException(e);
    span.setStatus(StatusCode.ERROR, "Image List query failed");
    throw e;
} finally {
    span.end();
}

return componentResources;

Das Ergebnis trace-operation-outcome

Auf der Seite WKND-Magazin , die fünf Artikel auflistet, enthält die Spur jetzt fünf ImageList.findPageComponentResources Bereiche innerhalb der Bildliste, einen für jedes Listenelement. Jede ist die übergeordnete Komponente des JCR query , den AEM für seine Abfrage erstellt:

AEM component: wknd/components/image-list
└─ HTL: apps.wknd.components.image__002d__list.image__002d__list__002e__html
   ├─ ImageList.findPageComponentResources        your span
   │  └─ JCR query                                AEM
   ├─ ImageList.findPageComponentResources
   │  └─ JCR query
   └─ ...                                         three more

Jeder Ihrer Bereiche verfügt über den Instrumentationsbereich com.adobe.aem.guides.wknd und die folgenden Attribute:

Sie können jetzt für jedes Listenelement sehen, nach welcher Seite die Abfrage gesucht hat, ob ein Bild gefunden wurde (wknd.query.result_count ist 0, wenn dies nicht der Fall war) und wie lange die gesamte Suche gedauert hat, einschließlich der Verarbeitung der Ergebnisse. Auf der Seite „WKND-Magazin“ dauert jede Suche etwa 6,5 Millisekunden, wovon die Repository-Abfrage selbst etwa 3,5 benötigt: Die Hälfte der Zeit geht in die Verarbeitung der Ergebnisse, die in AEM eigenen Bereichen nicht angezeigt werden. Da die Anzahl der Abfragen mit der Länge der Liste zunimmt, können Sie auch sehen, wie viel der Rendering-Zeit der Komponente die Suchvorgänge verzeichnen.

Beispiel 2: Verfolgen einer Methode mit einer Anmerkung with-span

Was Sie erreichen möchten with-span-goal

Das WKND-SocialImageImpl wird auf jeder Seite ausgeführt, um das og:image-Meta-Tag auszufüllen. Wenn ein Autor kein vorgestelltes Bild festgelegt hat, durchsucht das Modell den Inhaltsbaum der Seite, um das erste Bild zu finden, und besucht bis zu 500 Ressourcen. Sie möchten wissen, wie oft dieser Spaziergang läuft und wie viel von dem Baum er besucht, ohne die Methode umzustrukturieren.

Der Code with-span-code

Kommentieren Sie die Methode mit @WithSpan:

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.instrumentation.annotations.WithSpan;

@WithSpan("SocialImage.resolveFromFirstImageOnPage")
protected boolean resolveFromFirstImageOnPage() {
    Resource contentResource = currentPage.getContentResource();
    if (contentResource == null) {
        return false;
    }

    int[] visitedCount = new int[]{0};
    Resource firstImage = findFirstImage(contentResource, 0, visitedCount);

    // Span.current() is the span that @WithSpan started for this method.
    Span.current().setAttribute("wknd.social_image.nodes_visited", visitedCount[0]);
    Span.current().setAttribute("wknd.social_image.walk_truncated", visitedCount[0] > MAX_NODES_TO_VISIT);

    // ... use firstImage, as before
}

Das Ergebnis with-span-outcome

Ein SocialImage.resolveFromFirstImageOnPage wird nur in den Spuren von Seiten angezeigt, die kein vorgestelltes Bild haben:

Suchen Sie nach diesem span-Namen, um die Seiten aufzulisten, die ein vorgestelltes Bild benötigen. Wenn wknd.social_image.walk_truncated true ist, wurde der Spaziergang bei 500 Ressourcen gestoppt und die Seite hat möglicherweise überhaupt kein soziales Bild.

Von @WithSpan erstellte Spannen enthalten den Instrumentierungsbereich (io.opentelemetry.opentelemetry-instrumentation-annotations-1.16) des Agenten, nicht Ihren.

Beispiel 3: Geschäftskontext zur aktuellen Spanne hinzufügen current-span

Was Sie erreichen möchten current-span-goal

Sie möchten Spuren nach der Tatsache filtern, dass Ihr Code weiß, woher das soziale Bild der Seite stammt, ohne einen weiteren Bereich zu erstellen.

Der Code current-span-code

Fügen Sie in SocialImageImpl dem Bereich, der bereits aktiv ist, ein Attribut hinzu:

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.trace.Span;

private static final AttributeKey<String> IMAGE_SOURCE = AttributeKey.stringKey("wknd.social_image.source");

@PostConstruct
protected void init() {
    if (currentPage == null) {
        return;
    }

    final String source;
    if (resolveFromFeaturedImage()) {
        source = "featured_image";
    } else if (resolveFromFirstImageOnPage()) {
        source = "first_image_on_page";
    } else {
        source = "none";
    }

    Span.current().setAttribute(IMAGE_SOURCE, source);
}

Das Ergebnis current-span-outcome

Der Bereich des customheaderlibs.html der Seite, in dem WKND dieses Modell lädt, enthält wknd.social_image.source mit dem Wert featured_image, first_image_on_page oder none. Suchen Sie nach Spuren, bei denen wknd.social_image.source none ist, um die Seiten zu finden, die ohne ein Social-Media-Bild veröffentlicht wurden.

Auf der WKND-Website meldet jede Seite first_image_on_page oder none: Keine Seite legt ein vorgestelltes Bild fest, sodass jede Seite für den Inhaltsbaum-Walk von Beispiel 2 bezahlt. Wenn Sie ein vorgestelltes Bild auf den am häufigsten besuchten Seiten festlegen, wird diese Arbeit entfernt.

Beispiel 4: Fehler aufzeichnen record-errors

Was Sie erreichen möchten record-errors-goal

Das WKND-ContentAIAvailabilityImpl überprüft, ob Inhaltskonfigurationen vorliegen, indem eine OSGi-KI-Suche gelesen wird. Wenn die Suche fehlschlägt, behandelt das Modell die Inhalts-KI als nicht konfiguriert und protokolliert eine Warnung. Die Seite wird weiterhin gerendert und die Anfrage ist erfolgreich, sodass der Fehler leicht zu übersehen ist. Sie möchten, dass der Fehler in den Fehleransichten Ihres APM-Anbieters angezeigt wird, die an den fehlgeschlagenen Vorgang angehängt sind.

Der Code record-errors-code

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.context.Scope;

private boolean resolveConfigured() {
    if (configurationAdmin == null) {
        return false;
    }
    final Span span = WkndTelemetry.TRACER.spanBuilder("ContentAIAvailability.resolveConfigured").startSpan();
    // Close the scope in finally, not with try-with-resources: try-with-resources closes it before
    // the catch block runs, and the warning logged there must carry this span's trace and span IDs.
    final Scope scope = span.makeCurrent();
    try {
        Configuration configuration = lookupConfiguration();
        // ... read the API key, as before
        span.setAttribute("wknd.content_ai.configured", isConfigured);
        return isConfigured;
    } catch (IOException e) {
        span.recordException(e);
        span.setStatus(StatusCode.ERROR, "Content AI configuration lookup failed");
        LOGGER.warn("Unable to determine whether Content AI is configured (PID {})", CONTENT_AI_CLIENT_PID, e);
        return false;
    } finally {
        scope.close();
        span.end();
    }
}

Das Ergebnis record-errors-outcome

Die Ablaufverfolgung enthält einen ContentAIAvailability.resolveConfigured mit dem Status Fehler und der Content AI configuration lookup failed. Der Bereich hat ein exception Ereignis:

Der Bereich wird in Ihrem APM-Provider als Fehler gezählt, sodass er immer dann angezeigt wird, wenn Ihr Provider fehlgeschlagene Vorgänge anzeigt. Der Anfragebereich behält seinen Status, da die Anfrage HTTP 200 zurückgab.

Beispiel 5: Protokolle mit Spuren korrelieren correlate-logs

Was Sie erreichen möchten correlate-logs-goal

Wenn die Suche nach Content-KI in Beispiel 4 fehlschlägt, sollten Sie von der Warnung in Ihren Protokollen zur Verfolgung der Anfrage, die sie erzeugt hat, und zurück gehen.

Der Code correlate-logs-code

Sie benötigen keinen OpenTelemetry-Code. Melden Sie sich wie gewohnt bei SLF4J an und aktivieren Sie Protokolle (logs: true) in Ihrer OpenTelemetry-Konfiguration:

LOGGER.warn("Unable to determine whether Content AI is configured (PID {})", CONTENT_AI_CLIENT_PID, e);

Der Agent fügt jedem Protokolleintrag die Trace- und span-IDs des aktuellen Bereichs hinzu. Da ContentAIAvailabilityImpl protokolliert, während sein Bereich von Beispiel 4 aktuell ist, wird die Warnung mit diesem Bereich verknüpft.

Das Ergebnis correlate-logs-outcome

Ihr APM-Anbieter erhält einen Protokolleintrag wie den folgenden und kann ihn mit seiner Ablaufverfolgung anzeigen:

Best Practices best-practices

Testen der Instrumentierung test

Fehlerbehebung troubleshooting

Verwandte Artikel related-articles