Générer des traces et des métriques avec Java

Ce document explique comment modifier une application Java pour collecter des données de trace et de métrique à l'aide du framework Open Source OpenTelemetry et comment écrire des journaux JSON structurés pour la sortie standard. Il fournit également des informations sur un exemple d'application Java Spring Boot que vous pouvez installer et exécuter. L'application est configurée pour générer des métriques, des traces et des journaux. La procédure est la même, que vous utilisiez ou non le framework Spring Boot.

À propos des instrumentations manuelle et automatique

L'instrumentation décrite dans ce document s'appuie sur l'instrumentation automatique OpenTelemetry pour envoyer des données de télémétrie à votre projet Google Cloud. Pour Java, l'instrumentation automatique fait référence à la pratique qui consiste à injecter de manière dynamique du bytecode dans des bibliothèques et des frameworks, afin de capturer des données de télémétrie. L'instrumentation automatique peut collecter des données de télémétrie pour des éléments tels que les appels HTTP entrants et sortants. Pour en savoir plus, consultez la section Instrumentation automatique pour Java.

OpenTelemetry fournit également une API permettant d'ajouter une instrumentation personnalisée à votre propre code. OpenTelementry désigne ce principe comme étant de l'instrumentation manuelle. Le présent document n'aborde pas cette instrumentation manuelle. Pour obtenir des exemples et des informations à ce sujet, consultez la section Instrumentation manuelle.

Avant de commencer

Activer les API Cloud Logging API, Cloud Monitoring API, and Cloud Trace API.

Activer les API

Instrumenter votre application pour collecter des traces, des métriques et des journaux

Pour instrumenter votre application afin de collecter des données de trace et de métrique, et d'écrire un code JSON structuré pour la sortie standard, procédez comme suit, comme décrit dans les sections suivantes de ce document:

  1. Configurer votre application pour utiliser l'agent Java OpenTelemetry
  2. Configurer OpenTelementry
  3. Configurer la journalisation structurée
  4. Écrire des journaux structurés

Configurer votre application pour utiliser l'agent Java OpenTelemetry

Pour configurer l'application afin qu'elle écrive des journaux structurés et pour collecter des métriques et des données de trace à l'aide d'OpenTelemetry, mettez à jour l'appel de votre application afin qu'il utilise l'agent Java OpenTelemetry. Cette méthode d'instrumentation de votre application est appelée instrumentation automatique, car elle ne nécessite pas de modifier le code de l'application.

L'exemple de code suivant illustre un fichier Dockerfile qui télécharge le fichier JAR de l'agent Java OpenTelemetry et met à jour l'appel de ligne de commande pour transmettre l'option -javaagent.

RUN wget -O /opentelemetry-javaagent.jar https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.31.0/opentelemetry-javaagent.jar
CMD sh -c "java -javaagent:/opentelemetry-javaagent.jar -cp app:app/lib/* com.example.demo.DemoApplication \
	2>&1 | tee /var/log/app.log"

Vous pouvez également définir l'option -javaagent dans la variable d'environnement JAVA_TOOL_OPTIONS:

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"

Configurer OpenTelementry

La configuration par défaut de l'agent Java OpenTelemetry exporte les traces et les métriques à l'aide du protocole OTLP. Il configure également OpenTelemetry afin d'utiliser le format Contexte de trace W3C pour propager le contexte de trace. Cette configuration garantit que les délais ont la bonne relation parent-enfant au sein d'une trace.

Pour en savoir plus et obtenir des options de configuration, consultez la page Instrumentation automatique Java OpenTelemetry.

Configurer la journalisation structurée

Pour inclure les informations de trace dans les journaux au format JSON écrits dans la sortie standard, configurez votre application de sorte qu'elle génère des journaux structurés au format JSON. Nous vous recommandons d'utiliser Log4j2 comme implémentation de la journalisation. L'exemple de code suivant illustre un fichier log4j2.xml configuré pour générer des journaux structurés JSON à l'aide de la mise en page du modèle JSON:

<!-- Format JSON logs for the Cloud Logging agent
https://cloud.google.com/logging/docs/structured-logging#special-payload-fields -->

<!-- Log4j2's JsonTemplateLayout includes a template for Cloud Logging's special JSON fields
https://logging.apache.org/log4j/2.x/manual/json-template-layout.html#event-templates -->
<JsonTemplateLayout eventTemplateUri="classpath:GcpLayout.json">
  <!-- Extend the included GcpLayout to include the trace and span IDs from Mapped
  Diagnostic Context (MDC) so that Cloud Logging can correlate Logs and Spans -->
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace"
    format="JSON"
    value='{"$resolver": "mdc", "key": "trace_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/spanId"
    format="JSON"
    value='{"$resolver": "mdc", "key": "span_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace_sampled"
    format="JSON"
    value="true"
  />
</JsonTemplateLayout>

La configuration précédente extrait des informations sur le délai actif du contexte de diagnostic mappé de SLF4J et ajoute ces informations en tant qu'attributs au journal. Ces attributs peuvent ensuite être utilisés pour mettre en corrélation un journal et une trace:

  • logging.googleapis.com/trace: nom de ressource de la trace associée à l'entrée de journal.
  • logging.googleapis.com/spanId: ID de délai avec la trace associée à l'entrée de journal.
  • logging.googleapis.com/trace_sampled: la valeur de ce champ doit être true ou false.

Pour en savoir plus sur ces champs, consultez la structure LogEntry.

Écrire des journaux structurés

Pour écrire des journaux structurés qui renvoient vers une trace, utilisez l'API de journalisation SLF4J. Par exemple, l'instruction suivante montre comment appeler la méthode Logger.info():

logger.info("handle /multi request with subRequests={}", subRequests);

L'agent Java OpenTelemetry renseigne automatiquement le contexte de diagnostic mappé de SLF4J avec le contexte de segment du délai actif actuel dans le contexte OpenTelemetry. Le contexte de diagnostic mappé est ensuite inclus dans les journaux JSON, comme décrit dans la section Configurer la journalisation structurée.

Exécuter un exemple d'application configuré pour collecter les données de télémétrie

L'exemple d'application utilise des formats neutres du point de vue du fournisseur, y compris JSON pour les journaux, OTLP pour les métriques et les traces, ainsi que le framework Spring Boot. Pour acheminer la télémétrie vers Google Cloud, cet exemple utilise le Collector OpenTelemetry configuré avec les exportateurs Google. L'application possède deux points de terminaison:

  • Le point de terminaison /multi est géré par la fonction handleMulti. Le générateur de charge de l'application envoie des requêtes au point de terminaison /multi. Lorsque ce point de terminaison reçoit une requête, il envoie entre trois et sept requêtes au point de terminaison /single sur le serveur local.

    /**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/multi")
public Mono<String> handleMulti() throws Exception {
  int subRequests = ThreadLocalRandom.current().nextInt(3, 8);

  // Write a structured log with the request context, which allows the log to
  // be linked with the trace for this request.
  logger.info("handle /multi request with subRequests={}", subRequests);

  // Make 3-7 http requests to the /single endpoint.
  return Flux.range(0, subRequests)
      .concatMap(
          i -> client.get().uri("http://localhost:8080/single").retrieve().bodyToMono(Void.class))
      .then(Mono.just("ok"));
}

  • Le point de terminaison /single est géré par la fonction handleSingle. Lorsque ce point de terminaison reçoit une requête, il reste en veille pendant un court délai, puis répond par une chaîne.

    /**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/single")
public String handleSingle() throws InterruptedException {
  int sleepMillis = ThreadLocalRandom.current().nextInt(100, 200);
  logger.info("Going to sleep for {}", sleepMillis);
  Thread.sleep(sleepMillis);
  logger.info("Finishing the request");
  return String.format("slept %s\n", sleepMillis);
}

Télécharger et déployer l'application

Pour exécuter l'exemple , procédez comme suit :

  1. Dans la console Google Cloud, activez Cloud Shell.

    Activer Cloud Shell

    En bas de la fenêtre de la console Google Cloud, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

  2. Clonez le dépôt :

    git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java

  3. Accédez au répertoire de l'exemple :

    cd opentelemetry-operations-java/examples/instrumentation-quickstart

  4. Compilez et exécutez l'exemple.

    docker compose up --abort-on-container-exit

    Si vous n'exécutez pas sur Cloud Shell, exécutez l'application avec la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pointant vers un fichier d'identifiants. Les identifiants par défaut de l'application fournissent un fichier d'identifiants à l'adresse $HOME/.config/gcloud/application_default_credentials.json.

    # Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Afficher vos métriques

L'instrumentation OpenTelementry dans l'exemple d'application génère des métriques Prometheus que vous pouvez afficher à l'aide de l'explorateur de métriques:

  • Prometheus/http_server_duration_milliseconds/histogram enregistre la durée des requêtes du serveur et stocke les résultats dans un histogramme.

  • Prometheus/http_client_duration_milliseconds/histogram enregistre la durée des requêtes des clients et stocke les résultats dans un histogramme.

Pour afficher les métriques générées par l'exemple d'application, procédez comme suit :

  1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Surveillance, puis  Explorateur de métriques :

    Accéder à l'explorateur de métriques

  2. Dans l'élément Métrique, développez le menu Sélectionner une métrique, saisissez http_server dans la barre de filtre, puis utilisez les sous-menus pour sélectionner un type de ressource et des métriques spécifiques :
    1. Dans le menu Ressources actives, sélectionnez Cible Prometheus.
    2. Dans le menu Catégories de métriques actives, sélectionnez Http.
    3. Dans le menu Métriques actives, sélectionnez une métrique.
    4. Cliquez sur Appliquer.
  3. Configurez le mode d'affichage des données.

    Lorsque les mesures d'une métrique sont cumulatives, l'explorateur de métriques normalise automatiquement les données mesurées par période d'alignement, ce qui permet d'afficher un taux dans le graphique. Pour en savoir plus, consultez la section Genres, types et conversions.

    Lorsque des valeurs entières ou doubles sont mesurées, par exemple avec les deux métriques counter, l'explorateur de métriques additionne automatiquement toutes les séries temporelles. Pour afficher les données des routes HTTP /multi et /single, définissez le premier menu de l'entrée Agrégation sur Aucun.

    Pour plus d'informations sur la configuration d'un graphique, consultez la page Sélectionner des métriques lors de l'utilisation de l'explorateur de métriques.

Afficher vos traces

Pour afficher vos données de trace, procédez comme suit:

  1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Trace, puis Explorateur Trace:

    Accéder à Explorateur Trace

  2. Dans le graphique à nuage de points, sélectionnez une trace avec l'URI /multi.

  3. Dans le graphique de Gantt du panneau Détails des traces, sélectionnez le délai intitulé /multi.

    Un panneau contenant des informations sur la requête HTTP s'affiche. Ces informations incluent la méthode, le code d'état, le nombre d'octets et le user-agent de l'appelant.

  4. Pour afficher les journaux associés à cette trace, sélectionnez l'onglet Logs & Events (Journaux et événements).

    Cet onglet affiche les journaux individuels. Pour afficher les détails de l'entrée de journal, développez-la. Vous pouvez également cliquer sur Afficher les journaux et afficher le journal à l'aide de l'explorateur de journaux.

Pour en savoir plus sur l'utilisation de l'explorateur Cloud Trace, consultez la page Rechercher et explorer des traces.

Afficher les journaux

L'explorateur de journaux vous permet d'inspecter vos journaux et d'afficher les traces associées, lorsqu'elles existent.

  1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Logging, puis Explorateur de journaux :

    Accéder à l'explorateur de journaux

  2. Recherchez un journal avec la description suivante : handle /multi request.

    Pour afficher les détails du journal, développez l'entrée de journal.

  3. Cliquez sur Traces sur une entrée de journal contenant le message "handle /multi request", puis sélectionnez Afficher les détails des traces.

    Un panneau Trace details (Informations sur la trace) s'ouvre et affiche la trace sélectionnée.

Pour en savoir plus sur l'utilisation de l'explorateur de journaux, consultez la page Afficher les journaux à l'aide de l'explorateur de journaux.

Étapes suivantes