Instrumentation personnalisée avec OpenTelemetry custom-instrumentation

Lorsque la fonction OpenTelemetry est activée pour votre environnement, AEM as a Cloud Service effectue le suivi de chaque requête et exporte automatiquement les mesures JVM, HTTP et AEM. Cette télémétrie décrit AEM. Cela indique qu’une page a mis 900 millisecondes pour s’afficher et quels composants elle a rendus. Il ne peut pas afficher ce que faisait votre propre code, par exemple pour quel élément de liste une requête de référentiel était destinée et s’il a trouvé quelque chose, ou quelles pages sont renvoyées à une recherche coûteuse parce qu’un auteur a oublié un champ.

Vous pouvez ajouter ces connaissances vous-même avec l’API OpenTelemetry. Les étendues et attributs créés par votre code se déplacent avec la télémétrie automatique : même nom de service, même traitement, même fournisseur APM. Vous ne configurez pas de point d’entrée, d’informations d’identification ou d’exportateur dans votre code.

Si vous découvrez OpenTelemetry sur AEM as a Cloud Service, commencez par le tutoriel Observability via OpenTelemetry pour découvrir comment il fonctionne. Suivez ensuite Configuration d’OpenTelemetry pour obtenir des informations sur les applications AEM afin de l’activer pour votre environnement.

Les exemples de cette page instrumentent le site de référence WKND. Chaque exemple décrit ce que vous souhaitez accomplir, le code à ajouter et le résultat attendu de la part de votre fournisseur APM. Le code instrumenté complet, y compris les tests unitaires qui s’appuient sur les étendues, se trouve sur la branche tutorial/otel-custom-instrumentation du référentiel WKND.

Fonctionnement des instruments personnalisés how-it-works

Configurer votre projet set-up-project

Étape 1 : ajouter l’API OpenTelemetry add-api

Ajoutez l’API OpenTelemetry et les annotations d’instrumentation à la section dependencyManagement du pom.xml parent de votre projet, avec la portée 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>

Ajoutez ensuite les deux dépendances, sans versions, au pom.xml de chaque lot qui les utilise, par exemple 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>

Utilisez opentelemetry-api 1.61.0 et opentelemetry-instrumentation-annotations 2.27.0, ou des versions antérieures. Elles correspondent à l’agent Java OpenTelemetry qu’AEM as a Cloud Service exécute et les versions ultérieures de l’agent continuent de les prendre en charge. Les fonctionnalités d’API ajoutées après la version prise en charge par l’agent n’ont aucun effet.

Étape 2 : incorporation de l’API dans votre lot embed-api

AEM as a Cloud Service n’exporte pas les packages d’API OpenTelemetry, de sorte que chaque lot qui utilise l’API doit contenir sa propre copie. Ajoutez les instructions suivantes à la configuration de liaison de votre lot. Avec l’archétype de projet ​, il s’agit de la configuration bnd-maven-plugin dans core/pom.xml. Conservez toutes les entrées de votre instruction Import-Package.

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

Chaque lot qui utilise l’API incorpore sa propre copie et l’agent connecte chaque copie séparément.

Étape 3 : créer un traceur create-tracer

Créez une Tracer pour votre base de code et réutilisez-la partout. Dans WKND, une petite classe la contient :

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() {
    }
}

Le nom de la portée s’affiche sur chaque étendue que vous créez par l’intermédiaire de ce traceur, sous la forme de portée d’instrumentation (ou nom de bibliothèque). Utilisez un nom qui identifie votre code, tel que le package Java de base de votre projet.

Emplacement de vos étendues where-spans-appear

Sur AEM as a Cloud Service, une requête de page produit déjà des plages à partir d’AEM. Les plages créées par votre code y sont ajoutées. Par exemple, voici le chemin d’accès au composant Liste d’images dans une trace de la page WKND Magazine :

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

Lorsqu’un composant effectue le rendu, la portée de son script HTL est la portée actuelle. Un modèle Sling que le script charge avec data-sly-use s’exécute à l’intérieur de cette étendue, de sorte que les étendues créées par le modèle deviennent ses enfants.

Chaque plage de requêtes est nommée GET /* (ou POST /*, etc.). Pour rechercher les traces d’une page particulière, recherchez l’attribut url.path de l’étendue de la requête ou ajoutez vos propres attributs, comme indiqué dans Exemple 3.

Exemples examples

Exemple 1 : suivi d’une opération coûteuse trace-operation

Ce que vous souhaitez accomplir trace-operation-goal

Le composant Liste d’images WKND (wknd/components/image-list) affiche une liste de pages, chacune avec sa première image. Pour trouver cette image, son modèle Sling, ImageListImpl, exécute une requête QueryBuilder pour chaque élément de la liste. Les propres étendues AEM affichent déjà ces requêtes : sur la page du magazine WKND, qui répertorie cinq articles, la trace contient cinq étendues de JCR query sous l’étendue HTL de la liste d’images. Elles n’indiquent pas à quel élément de liste chaque requête correspondait, si elle a trouvé une image ou le temps passé à traiter les résultats. Le code d’origine a minuté la requête avec System.currentTimeMillis() et a écrit le résultat dans une entrée de journal DEBUG, qui n’est pas disponible en production. Vous souhaitez que chaque requête apparaisse dans la trace sous la forme d’une opération nommée, avec ce contexte.

Le code trace-operation-code

Dans ImageListImpl.findPageComponentResources(), créez une étendue autour de la requête :

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;

Le résultat trace-operation-outcome

Sur la page du magazine WKND, qui répertorie cinq articles, la trace contient désormais cinq plages d’ImageList.findPageComponentResources dans la liste d’images, une pour chaque élément de liste. Chacune d’elles est le parent de l’étendue de JCR query créée par AEM pour sa requête :

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

Chacune de vos plages possède la portée d’instrumentation com.adobe.aem.guides.wknd et les attributs suivants :

Vous pouvez désormais voir, pour chaque élément de liste, quelle page la requête a recherchée, si elle a trouvé une image (wknd.query.result_count est 0 alors que ce n’est pas le cas) et combien de temps a pris l’ensemble de la recherche, y compris le traitement des résultats. Sur la page du magazine WKND, chaque recherche prend environ 6,5 millisecondes, dont environ 3,5 millisecondes pour la requête de référentiel elle-même : la moitié du temps est consacrée au traitement des résultats, ce que les plages propres à AEM n’affichent pas. Étant donné que le nombre de requêtes augmente avec la longueur de la liste, vous pouvez également voir le temps de rendu du composant pris en compte par les recherches.

Exemple 2 : suivi d’une méthode avec une annotation with-span

Ce que vous souhaitez accomplir with-span-goal

Le modèle de SocialImageImpl de WKND s’exécute sur chaque page pour renseigner la balise meta og:image. Si un auteur n’a pas défini d’image en vedette, le modèle parcourt l’arborescence de contenu de la page pour trouver la première image, visitant jusqu’à 500 ressources. Vous voulez savoir à quelle fréquence cette marche court, et quelle partie de l’arbre elle visite, sans restructurer la méthode.

Le code with-span-code

Annotez la méthode avec @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
}

Le résultat with-span-outcome

Une étendue de SocialImage.resolveFromFirstImageOnPage apparaît uniquement dans les traces des pages qui n’ont pas d’image en vedette :

Recherchez ce nom d’étendue pour répertorier les pages qui ont besoin d’une image en vedette. Si wknd.social_image.walk_truncated est true, la marche s’est arrêtée à 500 ressources et la page peut ne pas avoir d’image sociale du tout.

Les plages créées par @WithSpan portent la portée d’instrumentation de l’agent (io.opentelemetry.opentelemetry-instrumentation-annotations-1.16), et non la vôtre.

Exemple 3 : ajouter un contexte métier à la plage actuelle current-span

Ce que vous souhaitez accomplir current-span-goal

Vous souhaitez filtrer les traces en fonction d’un fait que votre code connaît, ici, l’origine de l’image du réseau social de la page, sans créer d’autre étendue.

Le code current-span-code

Dans SocialImageImpl, ajoutez un attribut à l’étendue déjà active :

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

Le résultat current-span-outcome

L’étendue du script de customheaderlibs.html de la page, où WKND charge ce modèle, transporte les wknd.social_image.source avec la valeur featured_image, first_image_on_page ou none. Recherchez les traces où wknd.social_image.source est none pour trouver les pages publiées sans image de réseau social.

Sur le site WKND, chaque page indique first_image_on_page ou none : aucune page ne définit une image en vedette, de sorte que chaque page paie pour la présentation de l’arborescence de contenu à partir de Exemple 2. La définition d’une image en vedette sur les pages les plus visitées supprime ce travail.

Exemple 4 : enregistrement d’une erreur record-errors

Ce que vous souhaitez accomplir record-errors-goal

Le modèle ContentAIAvailabilityImpl de WKND vérifie si la Recherche optimisée par l’IA de contenu est configurée en lisant une configuration OSGi. Si la recherche échoue, le modèle traite l’IA dédiée au contenu comme non configurée et consigne un avertissement. La page est toujours rendue et la requête réussit. Il est donc facile de manquer l’échec. Vous souhaitez que l’échec apparaisse dans les vues d’erreur de votre fournisseur APM, associées à l’opération ayant échoué.

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

Le résultat record-errors-outcome

La trace contient une étendue ContentAIAvailability.resolveConfigured avec le statut Erreur et la description Content AI configuration lookup failed. L’étendue comporte un événement exception :

L’étendue compte comme une erreur dans votre fournisseur APM. Elle apparaît donc partout où votre fournisseur affiche des opérations ayant échoué. L’étendue de la requête conserve son statut, car la requête a renvoyé un HTTP 200.

Exemple 5 : corréler les logs avec les traces correlate-logs

Ce que vous souhaitez accomplir correlate-logs-goal

Lorsque la recherche de l’IA dédiée au contenu dans Exemple 4 échoue, vous devez passer de l’avertissement dans vos journaux à la trace de la requête qui l’a générée, puis revenir en arrière.

Le code correlate-logs-code

Vous n’avez pas besoin de code OpenTelemetry. Connectez-vous avec SLF4J comme d’habitude et activez les journaux (logs: true) dans votre configuration OpenTelemetry :

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

L’agent ajoute les identifiants de suivi et d’étendue de l’étendue actuelle à chaque entrée du journal. Étant donné que ContentAIAvailabilityImpl enregistre tant que son étendue de Exemple 4 est actuelle, l’avertissement est lié à cette étendue.

Le résultat correlate-logs-outcome

Votre fournisseur APM reçoit une entrée de journal telle que la suivante et peut l’afficher avec sa trace :

Bonnes pratiques best-practices

Tester votre instrumentation test

Résolution des problèmes troubleshooting

Articles connexes related-articles