05 ClickStack

Transmettez la télémétrie avec un collecteur local sans état, activez ClickStack managé et examinez-la dans HyperDX hébergé dans le cloud.

Point de départ

Vous êtes sur build-workshop-v1 ; aucun changement de branche n’est nécessaire. Prévoyez environ 15 minutes. L’application est déjà instrumentée pour OpenTelemetry ; dans ce module, vous l’activez avec la surcouche du collecteur.

Prérequis : votre service Cloud est en cours d’exécution (module 01).

Pourquoi

Pour diagnostiquer l’application plus tard, il faut d’abord pouvoir l’observer. ClickStack, la pile d’observabilité de ClickHouse dont HyperDX est l’interface, stocke les traces et journaux OpenTelemetry dans ClickHouse. Dans ce module, vous activez le collecteur afin que chaque requête traversant l’application produise une télémétrie interrogeable.

Objectif

Faire circuler les traces de l’application et les journaux de requêtes du back-end vers ClickStack, avec au moins une trace complète de requête et un flux visible d’enregistrements de requêtes réussies.

Étape 1 — Exécuter la surcouche du collecteur OpenTelemetry

HyperDX, le stockage et le calcul des requêtes restent managés dans ClickHouse Cloud. Le seul composant local est un collecteur OpenTelemetry sans état placé à côté de l’application locale ; il transmet la télémétrie et ne constitue pas un déploiement local de ClickStack ou d’HyperDX.

Vérifiez d’abord les ports du collecteur

Le collecteur publie OTLP sur les ports hôtes 4317 et 4318, souvent déjà occupés. Si ./preflight.sh dans ClickHouse_Demos/workshops/build_workshop/app a signalé un avertissement à leur sujet au module 00, définissez OTEL_GRPC_HOST_PORT et OTEL_HTTP_HOST_PORT dans .env.workshop avec les valeurs proposées par la vérification préalable (par exemple 24317 / 24318) avant de démarrer la surcouche. Le back-end rejoint le collecteur sur le réseau interne ; le remappage des ports hôtes ne présente donc aucun risque. Depuis n’importe quel emplacement du dépôt cloné, réexécutez cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh pour confirmer que les ports sont libres.

`.env.workshop` et `docker-compose.otel.yml`

Ces valeurs se trouvent dans la section d’observabilité ClickStack de .env.workshop.example ; renseignez-les dans votre .env.workshop :

OTLP_AUTH_TOKEN=change-me-workshop-token   # shared secret securing OTLP ingest
CLICKSTACK_DATABASE=otel                   # ClickStack's own otel_* tables
OTEL_SERVICE_NAME=nyc-taxi-backend         # the service name shown in HyperDX
LOG_LEVEL=DEBUG                            # show successful queries in Log source

Ne chargez pas ce fichier dans votre interpréteur. La commande Compose ci-dessous le lit directement, ce qui évite d’exporter ses mots de passe et clés API dans des variables de l’interpréteur et garantit la prise en compte des modifications ultérieures.

Démarrez maintenant la pile avec la surcouche. Celle-ci définit OTEL_ENABLED=true sur le back-end, ajoute le service otel-collector (clickhouse/clickstack-otel-collector) et reconstruit le front-end avec les paramètres de télémétrie du navigateur :

docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build

Le collecteur réutilise CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD depuis .env.workshop ; le back-end exporte OTLP vers http://otel-collector:4318 (HTTP/protobuf). Pour collecter aussi la sortie standard brute des conteneurs sur un hôte Linux, ajoutez --profile container-logs.

Étape 2 — Activer ClickStack managé sur votre service

L’atelier utilise ClickStack managé (HyperDX) dans votre propre service ClickHouse Cloud : le collecteur écrit les tables otel_* dans votre service et l’interface HyperDX les restitue sur place. Activez-le dans la console :

Console - votre service -> ClickStack -> Start Ingestion -> ignorez l’étape du collecteur (le collecteur de l’application fonctionne déjà depuis l’étape 1) -> Launch ClickStack

Vous êtes alors connecté à HyperDX par authentification unique. La télémétrie a déjà commencé à circuler ; l’interface hébergée peut donc se remplir dès son ouverture.

ClickStack managé : différences avec la configuration classique

Le back-end utilise OpenTelemetry standard, et non le paquet pratique hyperdx-opentelemetry recommandé dans la documentation ClickStack. Ce paquet impose opentelemetry-api==1.30.0, qui entre en conflit avec le SDK Langfuse v4 utilisé par la fonction de chat (il nécessite opentelemetry-api>=1.33.1) : les deux ne peuvent pas cohabiter dans un même environnement. Le collecteur ClickStack ingère du protocole OTLP standard ; la distribution standard se comporte donc de la même manière. L’atelier définit simplement lui-même les variables d’environnement de l’exportateur.
La télémétrie ClickStack réside dans une base distincte sur votre service (CLICKSTACK_DATABASE=otel), séparée de la base de données de l’application (CLICKHOUSE_DATABASE=nyc_tlc_data).
Les traces et les journaux Python du back-end passent par OTLP depuis le back-end auto-instrumenté. Le collecteur facultatif --profile container-logs est réservé aux services non instrumentés, tels que le générateur de trajets ; son chemin de journaux Docker Linux peut être indisponible sous Docker Desktop.

Étape 3 — Générer et retrouver du trafic dans ClickStack

Ouvrez le tableau de bord Ops et laissez son intervalle 1m et son actualisation automatique 5s par défaut fonctionner pendant environ 30 secondes. Ouvrez ensuite ClickStack :

Dans Traces, suivez une requête de bout en bout (front-end -> back-end -> ClickHouse).
Dans Logs, sélectionnez nyc-taxi-backend et repérez des enregistrements ClickHouse query ok répétés. Leur horodatage doit avancer à chaque actualisation.
Conservez des niveaux de gravité pertinents : les requêtes réussies sont en DEBUG ; les véritables nouvelles tentatives après une période d’inactivité et les échecs apparaissent en WARNING ou ERROR.

Un service nommé nyc-taxi-backend doit apparaître dans HyperDX, avec des requêtes /api/... affichées sous forme de traces, chacune contenant un span enfant clickhouse.query.

Vue Search d’HyperDX montrant les traces de nyc-taxi-backend : une liste en direct de spans GET /api/health et POST, avec les colonnes d’horodatage, de service et de durée

HyperDX restitue les traces de l’application : le service nyc-taxi-backend et ses spans de requêtes /api/....

Comment vérifier que vous avez terminé

Un service nommé nyc-taxi-backend apparaît dans HyperDX.
Les requêtes vers /api/... s’affichent sous forme de traces, chacune avec un span enfant clickhouse.query contenant db.statement, db.elapsed_ms et db.rows_returned.
La source Log affiche de nouveaux enregistrements DEBUG ... ClickHouse query ok pendant que le tableau de bord Ops reste ouvert.
Vous ne verrez pas encore d’erreurs de requête : une application saine et amorcée n’atteint pas les limites de sécurité, et les requêtes 4xx ne parviennent jamais à ClickHouse. Au module 07, la panne injectée rend observable un span clickhouse.query en erreur, accompagné de error.category.

Récapitulatif

L’application est maintenant observable : les traces et les journaux de requêtes du back-end sont enregistrés dans ClickHouse et peuvent être explorés dans ClickStack. Le profil facultatif container-logs ajoute la sortie standard du générateur de trajets sur les hôtes Linux compatibles. Cette télémétrie servira de base au travail de SRE assistée par l’IA qui suit.

État final

La télémétrie circule vers ClickStack. Passez à 06 SRE assistée par l’IA pour demander à votre agent de construire à partir de celle-ci.