05 ClickStack

Document d’accompagnement du formateur pour la leçon participant 05 ClickStack.

Durée

Environ 15 minutes. La télémétrie doit s’accumuler avant l’exercice d’incident du module 07 : démarrez le collecteur dès que ce module le permet et laissez-le fonctionner.

Trame d’animation

• ClickStack managé stocke la télémétrie dans ClickHouse Cloud ; HyperDX est l’interface hébergée. Le collecteur local ne fait que transmettre les données. Montrez à la fois la trace complète d’une requête et une entrée récente DEBUG ... ClickHouse query ok dans la source Log.
• Faites démarrer le collecteur à l’étape 1 avant de lancer ClickStack managé à l’étape 2. La télémétrie aura ainsi le temps d’arriver et la première vue de l’interface hébergée contiendra déjà des informations utiles.
• Montrez au projecteur la trace complète d’une requête.

Problèmes courants

• Les ports hôtes OTLP 4317/4318 sont déjà utilisés : demandez de définir OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT dans .env.workshop (la vérification préalable propose des valeurs, par exemple 24317/24318), puis, depuis n’importe quel emplacement du dépôt cloné, d’exécuter cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh ; le back-end communique avec le collecteur sur le réseau interne, ce remappage est donc sûr.
• La surcouche du collecteur n’a pas démarré (oubli du second -f docker-compose.otel.yml) : rien n’arrive donc dans HyperDX.
• Incohérence de OTLP_AUTH_TOKEN ou variables CLICKHOUSE_* manquantes dans .env.workshop (le collecteur réutilise CLICKHOUSE_HOST/PORT/USER/PASSWORD pour joindre le service Cloud).
• Aucun trafic n’a encore été généré ; demandez de parcourir les deux tableaux de bord.
• Sous Docker Desktop, l’outil de collecte facultatif du profil --profile container-logs ne peut pas monter le chemin des journaux de l’hôte (le démon s’exécute dans une machine virtuelle) ; c’est normal. Les journaux du back-end passent tout de même par OTLP. Utilisez docker compose ... logs uniquement pour diagnostiquer le transmetteur si HyperDX ne reçoit rien.
• Après la recréation du back-end par la surcouche, l’application renvoyait auparavant une erreur 502 (nginx côté front-end mettait en cache l’ancienne adresse IP du back-end). Le front-end résout désormais le nom à chaque requête : il récupère automatiquement en environ 10 s, sans redémarrage manuel. Correction confirmée pendant la répétition.
• Référence de la répétition : le pipeline de télémétrie a été validé de bout en bout — traces nyc-taxi-backend avec des spans enfants clickhouse.query contenant db.statement / db.elapsed_ms / db.rows_returned. Résultat confirmé lors de la répétition en environnement vierge de juillet 2026.

Procédures de réinitialisation

• Redémarrez avec les deux fichiers Compose : docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build.
• Dans la console Cloud, ouvrez le service, choisissez ClickStack, puis relancez l’interface hébergée si la session SSO a expiré.