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

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

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

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`.

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.

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.

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

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.

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

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.
   
   

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).

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€ ?'.

   

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

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).

2. Configurer un Processeur

   Ajoutez un processeur `batch` à votre configuration. Ce processeur est essentiel 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.
   
   

   Note : Un processor s'exécute sur les données entre leur réception et leur exportation. Il peut les modifier (ex: ajouter un attribut), les filtrer (ex: supprimer une donnée sensible) ou, comme ici, les regrouper.

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 logging 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 loki pour envoyer les logs vers Loki (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.

4. 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 `logging` et `otlp/tempo`.
   • Les métriques reçues via OTLP soient traitées par le processeur `batch` puis envoyées vers `logging` et `prometheusremotewrite`.
   • Les logs reçus via OTLP soient traités par le processeur `batch` puis envoyés vers `logging` et `loki`.
   
   Activez également la télémétrie interne du collecteur pour surveiller son propre état.

5. 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.

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

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.

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.