Déployer un pipeline d'observabilité complet avec Agent et Gateway avec correction

Ce que vous allez apprendre dans ce TP

• Déployer un backend de visualisation complet (Grafana, Prometheus, Loki, Tempo)
• Configurer et lancer un collecteur OTel en mode Gateway
• Configurer et lancer un collecteur OTel en mode Agent
• Instrumenter une application pour envoyer sa télémétrie à l'Agent
• Visualiser les traces, métriques et logs dans Grafana
• Cloner le dépôt de configuration
• Démarrer l'infrastructure via Docker Compose
• Valider l'accès aux outils de visualisation
• Comprendre la structure d'une trace distribuée
• Générer du trafic et retrouver la trace correspondante
• Analyser le parcours d'une requête
• Comprendre comment l'appel à l'API météo est effectué
• Simuler une mise en production pour activer la propagation de contexte
• Vérifier l'instrumentation et la corrélation des traces dans la console
• Créer le fichier de configuration pour la gateway
• Lancer le conteneur de la gateway
• Créer la configuration pour l'agent
• Lancer l'agent et l'application de démo

Architecture Cible #

Ce que vous allez apprendre dans cette section

• Déployer un backend de visualisation complet (Grafana, Prometheus, Loki, Tempo)
• Configurer et lancer un collecteur OTel en mode Gateway
• Configurer et lancer un collecteur OTel en mode Agent
• Instrumenter une application pour envoyer sa télémétrie à l'Agent
• Visualiser les traces, métriques et logs dans Grafana

L'objectif est de construire un pipeline où une application instrumentée envoie ses données à un **agent OTel local**. Cet agent transmet ensuite les données à une **gateway OTel centralisée**, qui se charge de les traiter et de les exporter vers notre backend de stockage et de visualisation (stack : Loki, Grafana, Tempo, Prometheus).

Pourquoi cette architecture Agent + Gateway ?

• Résilience : L'agent peut mettre en cache les données si la gateway est indisponible.
• Performance : L'agent, étant local, a une latence très faible pour l'application. Le traitement lourd (filtrage, enrichissement) est déporté sur la gateway.
• Scalabilité : On peut scaler la gateway indépendamment des applications pour gérer la charge de milliers d'agents.
• Sécurité : Seule la gateway a besoin des credentials pour se connecter aux backends finaux.

Déploiement du Backend d'observabilité #

Ce que vous allez apprendre dans cette section

• Cloner le dépôt de configuration
• Démarrer l'infrastructure via Docker Compose
• Valider l'accès aux outils de visualisation

Nous allons commencer par déployer notre backend qui centralisera et visualisera toutes les données de télémétrie.

1. Récupérer les fichiers de configuration

   Récupérez les fichiers de configuration nécessaires pour le déploiement du backend.

   git clone https://github.com/RousselTM/otel-formation.git 
   cd otel-formation

2. Déployer le backend via Docker Compose

   Lancez le déploiement des services : Prometheus pour les métriques, Loki pour les logs, Tempo pour les traces et Grafana pour la visualisation.

   docker compose up -d

3. Vérification de l'accès à l'application de démo

   Assurez-vous que l'application de démo Java/Wildfly est bien accessible. Accédez à l'URL

   http://localhost:8090

   et générez un peu de trafic en naviguant sur le site.

4. Vérification de l'accès à la console Grafana

   Assurez-vous que l'interface Grafana est accessible. Accédez à l'URL

   http://localhost:3000

   et connectez-vous avec les identifiants admin/grafanapassword.

5. Vérification des sources de données

   Une fois connecté, nous allons vérifier la présence des logs, métriques et traces.
   
   Allez dans **Explore**, sélectionnez la source de données appropriée (Loki pour les logs, Mimir pour les métriques, Tempo pour les traces) et vérifiez que des données apparaissent.
   
   

   Note : Si vous voyez déjà des données, c'est normal. L'application de démo est pré-instrumentée avec le SDK OpenTelemetry. Elle envoie sa télémétrie à une gateway Grafana Alloy (une version d'OTel Collector adaptée par Grafana Labs) qui redirige les données vers le backend.
   
   L'objectif de ce TP sera justement de reconfigurer l'application pour qu'elle envoie ses données vers un pipeline de collecte que nous allons paramétrer nous-mêmes.

   La commande `docker compose up -d` a déployé une stack complète qui inclut l'application de démo, le backend de stockage (Loki, Mimir, Tempo) et une gateway de collecte préconfigurée (Grafana Alloy).

Analyse d'une trace #

Ce que vous allez apprendre dans cette section

• Comprendre la structure d'une trace distribuée
• Générer du trafic et retrouver la trace correspondante
• Analyser le parcours d'une requête

Exploration avec Grafana.

1. Rappel sur la définition d'une trace

   Une trace distribuée représente le parcours complet d'une requête à travers les différents services de votre application. Elle est composée de 'spans', chaque span représentant une unité de travail (ex: un appel HTTP, une requête en base de données). Pour un rappel complet, nous vous recommandons de lire cet article sur les bonnes pratiques OpenTelemetry.

2. Génération et recherche d'une trace

   Ouvrez la page météo de l'application de démo à l'adresse http://localhost:8090/meteo.jsp et affichez la météo pour le Cameroun et la France. Ensuite, dans Grafana, allez dans **Explore** > **Tempo**. Utilisez la recherche (Search) pour filtrer par nom de service (`service.name="wildfly-app"`) et retrouvez la trace correspondant à l'appel de la page `/meteo.jsp`.

   Chaque interaction avec l'application génère une trace unique. En filtrant par le nom du service et en cherchant le 'span' racine correspondant au point d'entrée de votre requête (ici, la page JSP), vous pouvez isoler la trace qui vous intéresse.

3. Comprendre les appels de la page

   En analysant la trace que vous avez trouvée, identifiez les différents appels internes et externes effectués par la page `/meteo.jsp` pour construire la réponse. Observez la durée de chaque span pour identifier les éventuels points de latence.

   La vue en cascade (waterfall) de la trace montre que la page `/meteo.jsp` effectue elle-même plusieurs appels HTTP sortants vers des services externes pour récupérer les données météo. Chaque appel est représenté par un 'span' enfant, vous permettant de voir le temps passé dans chaque service distant.

4. Analyser les attributs (Span vs Resource)

   Dans les détails d'un span, vous trouverez les **Span Attributes** (spécifiques à cette opération) et les **Resource Attributes** (communs à tous les spans de ce service). Explorez les spans liés à la base de données et, en utilisant les attributs, retrouvez le type de base de données contactée, son IP/port et la requête exécutée.
   
   Pour en savoir plus sur la différence entre attributs et ressources, consultez cet article.

   Les **Resource Attributes** vous donnent le contexte global (ex: `service.name`, `telemetry.sdk.language`). Les **Span Attributes** vous donnent les détails de l'opération (ex: `db.system`, `db.statement`, `net.peer.name`, `net.peer.port`). C'est en combinant ces deux types d'attributs que l'on obtient une vision complète.

Propagation de contexte #

Ce que vous allez apprendre dans cette section

• Comprendre comment l'appel à l'API météo est effectué
• Simuler une mise en production pour activer la propagation de contexte
• Vérifier l'instrumentation et la corrélation des traces dans la console

Comprendre l'importance et la mise en place de la propagation de contexte pour lier les actions frontend et backend.

1. Analyse de l'appel API Météo

   Dans les traces précédentes, nous n'avons pas vu l'appel vers l'API de météo. Pour comprendre comment cet appel est fait, utilisez les outils de développement de votre navigateur ('Inspecter' ou 'Voir le code source de la page') sur la page météo.

   En inspectant le code source de la page `meteo.jsp`, on s'aperçoit que l'appel à l'API météo est effectué directement en JavaScript côté client (frontend), et non depuis le backend Java. C'est pourquoi il n'apparaît pas dans la trace du service `wildfly-app` qui ne couvre que le backend. Pour lier la partie frontend et backend, il faut mettre en place la propagation de contexte.

2. Simuler une mise en production

   Pour activer la propagation de contexte, nous allons simuler une mise en production en déployant une nouvelle version de l'application. Pour ce faire, allez dans le dossier `app` du projet et exécutez les commandes suivantes pour remplacer l'ancienne version par la nouvelle :

   mv app/ROOT.war app/ROOT-old.war
   mv app/ROOT-new.war app/ROOT.war

   Ensuite, redémarrez le conteneur de l'application pour que les changements soient pris en compte :

   sudo docker compose restart wildfly

   Cette manipulation remplace l'artefact de déploiement de l'application par une nouvelle version qui inclut l'instrumentation nécessaire pour la propagation de contexte entre le frontend et le backend.

3. Vérification de l'instrumentation

   Après avoir redémarré l'application, retournez sur la page météo, ouvrez la console JavaScript de votre navigateur et vérifiez que l'instrumentation OpenTelemetry est bien active. Vous devriez voir des messages liés à OTel s'afficher.
   
   

   La présence de logs OpenTelemetry dans la console du navigateur confirme que le code d'instrumentation est bien injecté côté client. Désormais, lorsque vous générerez une trace, vous verrez que les spans du frontend (JavaScript) et du backend (Java) sont correctement corrélés sous un même Trace ID, offrant une vue de bout en bout.

4. Analyse de l'instrumentation dans Grafana

   Après avoir généré du trafic sur la page météo, retournez dans Grafana et analysez la nouvelle trace. Vous devriez maintenant voir une trace complète qui commence par un span frontend (JavaScript) et qui est suivie par les spans backend (Java).

   La corrélation est rendue possible grâce à la propagation du 'Trace Context' (via les en-têtes W3C `traceparent`). Le SDK JavaScript frontend crée la trace et son contexte, qui est ensuite transmis au backend lors de l'appel AJAX. Le SDK Java backend détecte cet en-tête et continue la trace existante au lieu d'en créer une nouvelle.

5. Ajout d'informations métier aux spans

   L'instrumentation automatique est puissante, mais souvent les entreprises le combinent avec l'instrumentation manuelle pour transférer les données métiers. Analysez la trace 'meteo-app-js' pour retrouver les informations métiers (pays, température et vitesse du vent) qui ont été injectées dans le nouveau code source.
   
   

   Cas d'usage en entreprise : En production, on utilise cette technique pour injecter des informations cruciales comme l'ID client, le montant d'un panier, le type d'abonnement ou toute autre donnée métier. Cela permet de créer des tableaux de bord qui ne se contentent pas de montrer la performance technique, mais qui répondent à des questions business : 'Quel est le temps de réponse moyen pour nos clients VIP ?' ou 'Quelles sont les erreurs les plus fréquentes pour les paniers supérieurs à 100€ ?'.

   

   Pour ajouter des attributs, il faut utiliser l'instrumentation manuelle. Dans le code JavaScript qui traite la réponse de l'API météo, on récupère le 'span' actif et on lui ajoute des attributs avec `span.setAttribute('clé', 'valeur')`. Une fois les modifications appliquées, vous pourrez voir ces nouveaux attributs (ex: `weather.country`, `weather.temp`, `weather.wind_speed`) directement dans les détails du span dans Grafana/Tempo.

Configuration de la Gateway OTel #

Ce que vous allez apprendre dans cette section

• Créer le fichier de configuration pour la gateway
• Lancer le conteneur de la gateway

La gateway est le point de collecte central. Elle reçoit les données de tous les agents, les traite et les exporte vers le backend.

1. Configurer les Receivers

   Modifiez la configuration pour que la gateway écoute les requêtes OTLP via gRPC et HTTP sur leurs ports par défaut.
   
   

   Note : Un receiver est le point d'entrée des données dans le collecteur. Il définit comment le collecteur reçoit la télémétrie (ex: via le protocole OTLP, Jaeger, ou Prometheus).

   Ajoutez la section `receivers` suivante à votre fichier `otel-gateway-config.yaml` :

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318

2. Configurer un Processeur

   Ajoutez deux processeurs à votre configuration :
   • Un processeur `batch` pour regrouper les données de télémétrie en lots avant de les exporter, ce qui améliore les performances et réduit le nombre de requêtes sortantes.
   • Un processeur `resource` pour enrichir toutes les données de télémétrie avec un attribut statique. Ajoutez l'attribut `collector.name` avec la valeur `serveurx`.
   
   

   Note : Un processor s'exécute sur les données entre leur réception et leur exportation.

   • Le processeur batch est essentiel : il regroupe les données en lots avant de les envoyer, ce qui optimise les performances réseau et réduit la charge sur les backends.
   • Le processeur resource permet d'enrichir automatiquement toutes les données avec des attributs de contexte (ex: nom du collecteur, région cloud, version de l'application), ce qui est crucial pour le filtrage et l'analyse.

   Ajoutez la section `processors` suivante à votre fichier `otel-gateway-config.yaml` :

   processors:
     batch:
     resource:
       attributes:
         - key: collector.name
           value: "serveurx"
           action: upsert

3. Configurer un Exporter

   Configurez les exportateurs pour envoyer les données vers les backends appropriés. Chaque type de signal (trace, métrique, log) a sa destination.
   
   
   • Pour le débogage : Ajoutez un exportateur debug pour afficher toutes les données reçues directement dans les logs du conteneur. C'est un outil indispensable pour vérifier que le collecteur reçoit bien les données.
   • Traces : Configurez un exportateur otlp/tempo pour envoyer les traces vers Tempo sur son port gRPC (tempo:4317).
   • Métriques : Utilisez l'exportateur prometheusremotewrite pour envoyer les métriques à Prometheus/Mimir via son endpoint d'écriture à distance (sachant que voici l'URL de Prometheus http://prometheus:9090).
   • Logs : Utilisez l'exportateur otlphttp/loki pour envoyer les logs vers Loki via OTLP/HTTP (sachant que voici l'URL de Loki http://loki:3100).
   
   

   Note : Un exporter est la destination finale des données de télémétrie. Il définit où et comment le collecteur envoie les données après qu'elles ont été reçues et traitées.
   
   L'exportateur logging a été déprécié et remplacé par l'exportateur debug. Bien que logging puisse encore fonctionner, il est recommandé d'utiliser debug pour bénéficier des dernières améliorations et garantir la compatibilité future.

   Ajoutez la section `exporters` suivante à votre fichier `otel-gateway-config.yaml` :

   exporters:
     # Pour le débogage : affiche les données reçues dans les logs du conteneur. (remplace l'ancien 'logging')
     debug:
       verbosity: detailed
   
     # Exporte les métriques vers Prometheus via remote write
     prometheusremotewrite:
       endpoint: http://prometheus:9090/api/v1/write
   
     # Exporte les traces vers Tempo via OTLP/GRPC
     otlp/tempo:
       endpoint: tempo:4317
       tls:
         insecure: true
   
     # Exporte les logs vers Loki via OTLP/HTTP
     otlphttp/loki:
       endpoint: http://loki:3100/otlp

4. Configurer les Extensions

   Ajoutez une extension `health_check` à votre configuration. Elle expose un point de terminaison HTTP qui permet de vérifier que le collecteur est en bonne santé.
   
   

   Note : Les extensions fournissent des fonctionnalités qui ne font pas directement partie du pipeline de traitement des données (recevoir, traiter, exporter), mais qui améliorent la gestion et la supervision du collecteur lui-même. L'extension health_check est cruciale en production : elle permet à des orchestrateurs comme Kubernetes de savoir si le collecteur est prêt à recevoir du trafic, assurant ainsi des déploiements et des redémarrages sans interruption de service.

   Ajoutez la section `extensions` suivante à votre fichier `otel-gateway-config.yaml` :

   extensions:
     health_check:
       endpoint: 0.0.0.0:13133

5. Configurer les Services (Pipelines)

   Maintenant que les receivers, processors et exporters sont définis, il faut les assembler dans des pipelines. Chaque pipeline définit le chemin que suivra un type de signal (trace, métrique ou log).
   
   

   Note : La section service et plus particulièrement pipelines est le cœur de la configuration du collecteur. C'est ici que l'on définit le chemin de traitement pour chaque type de signal en connectant les `receivers`, `processors` et `exporters` que nous avons définis précédemment. Sans cette section, le collecteur ne sait pas quoi faire des données qu'il reçoit.

   
   Configurez les pipelines pour que :
   • Les traces reçues via OTLP soient traitées par le processeur `batch` puis envoyées vers `debug` et `otlp/tempo`.
   • Les métriques reçues via OTLP soient traitées par le processeur `batch` puis envoyées vers `debug` et `prometheusremotewrite`.
   • Les logs reçus via OTLP soient traités par le processeur `batch` puis envoyés vers `debug` et `otlphttp/loki`.
   
   Activez également l'extension `health_check` pour exposer un point de terminaison de santé, ainsi que la télémétrie interne du collecteur pour surveiller son propre état.

   Ajoutez la section `service` suivante à votre fichier `otel-gateway-config.yaml` pour lier tous les composants :

   service:
     extensions: [health_check]
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [debug, otlp/tempo]
       metrics:
         receivers: [otlp]
         processors: [batch]
         exporters: [debug, prometheusremotewrite]
       logs:
         receivers: [otlp]
         processors: [batch]
         exporters: [debug, otlphttp/loki]
     telemetry:
       logs:
         level: "info"

6. Changement de gateway

   Vous devez modifier le fichier compose.yaml pour modifier la variable OTEL_EXPORTER_OTLP_ENDPOINT pour qu'il pointe vers la nouvelle gateway 'http://otel-collector:4317' et relancer le service.

   - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

Configuration de l'Agent OTel et de l'Application #

Ce que vous allez apprendre dans cette section

• Créer la configuration pour l'agent
• Lancer l'agent et l'application de démo

L'agent s'exécute au plus près de l'application. Son rôle est simple : collecter les données et les transférer à la gateway. Nous déploierons également une application de démo qui génère des traces, logs et métriques.

1. Créer la configuration de l'Agent

   Créez un fichier `otel-agent-config.yaml`. La configuration de l'agent est minimale : il reçoit les données de l'application (sur le port 5317 pour ne pas entrer en conflit avec la gateway) et les exporte vers la gateway.

   Voici la configuration pour `otel-agent-config.yaml` :

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:5317
   
   processors:
     batch:
   
   exporters:
     otlp:
       endpoint: otel-gateway:4317
       tls:
         insecure: true
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlp]
       metrics:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlp]
       logs:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlp]

2. Lancer l'Agent et l'Application de Démo

   Ajoutez les services `otel-agent` et `app-demo` à votre `docker-compose.yaml` et démarrez-les. L'application est configurée pour envoyer sa télémétrie à l'agent.

   Ajoutez ces deux services à votre `docker-compose.yaml` :

     otel-agent:
       image: otel/opentelemetry-collector-contrib:latest
       container_name: otel-agent
       command: ["--config=/etc/otel-agent-config.yaml"]
       volumes:
         - ./otel-agent-config.yaml:/etc/otel-agent-config.yaml
       ports:
         - "5317:5317"
       depends_on:
         - otel-gateway
   
     app-demo:
       image: ghcr.io/open-telemetry/opentelemetry-demo-community/otel-demo-client:latest
       container_name: app-demo
       environment:
         - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-agent:5317
         - OTEL_SERVICE_NAME=app-demo
       ports:
         - "8080:8080"
       depends_on:
         - otel-agent

   Puis lancez-les :

   docker compose up -d otel-agent app-demo

   Générez du trafic en accédant à `http://localhost:8080`.

Niveau de difficulté : ●●●○○ (3/5)