SRE assistée par l’IA et débogage d’applications

Bienvenue dans le guide de l’atelier ClickHouse BUILD. En trois heures, vous allez déployer de bout en bout sur ClickHouse Cloud une application analytique de réservation de taxis new-yorkais (front-end React, back-end FastAPI et base de données source Postgres), en vous servant de votre propre outil de programmation agentique pour la construire. À la fin, vous disposerez d’une capture des modifications en temps réel depuis un Postgres managé, d’une BI conversationnelle sur vos données, d’une observabilité complète, d’un flux de travail SRE assisté par l’IA et d’un chat IA intégré à l’application et tracé de bout en bout. Vous aurez également appris à diagnostiquer un incident réel avec une SRE assistée par l’IA.

Le même atelier fonctionne sous macOS et Windows. Choisissez votre ordinateur une seule fois dans l’en-tête de la page ; le guide affichera partout la procédure adaptée. Sous Windows, la chaîne d’outils commune de l’atelier s’exécute dans Ubuntu sur WSL 2.

Vous repartez avec un prototype opérationnel et ce dépôt à présenter à votre équipe. Les artefacts ClickHouse managé, Postgres, ClickPipes, Agents et ClickStack restent disponibles pendant la période d’essai ; les traces Langfuse persistent dans Langfuse Cloud. À votre retour, redémarrez l’application locale et le transmetteur de télémétrie avec Docker. À la fin, vous pourrez présenter en direct cinq éléments :

• un tableau de bord opérationnel en temps réel sur ClickHouse Cloud ;
• un pipeline de capture des modifications diffusant les données depuis Postgres managé ;
• une BI conversationnelle sur vos données avec ClickHouse Agents ;
• un tableau de bord SRE et une alerte créés par l’IA à partir de votre télémétrie ;
• un chat IA intégré à l’application et tracé de bout en bout dans Langfuse.

Ce guide comporte deux parcours. Le parcours participant est la leçon suivie pendant la session. Le parcours formateur accompagne chaque module correspondant avec sa durée, sa trame d’animation, ses problèmes courants et ses procédures de réinitialisation.

Pour les participants

Vous avancerez module par module. Chaque module indique un point de départ, explique l’intérêt de l’étape, fixe un objectif concret, vous guide dans une procédure numérotée et se termine par une vérification que vous pouvez effectuer vous-même. Vous n’avez jamais besoin de suivre le rythme de toute la salle : si vous prenez du retard, la section Point de départ de chaque module précise exactement ce qui doit déjà être en place, afin que vous puissiez reprendre à votre propre rythme.

Ce dont vous aurez besoin le jour de l’atelier :

• Un ordinateur portable qui satisfait aux prérequis de 00 Configuration.
• Votre propre outil de programmation agentique (Claude Code, Cursor, Codex CLI ou Windsurf), avec une session ouverte et un abonnement actif.
• Un compte ClickHouse Cloud dont les crédits d’essai sont visibles (créé pendant la préparation).
• Le dépôt de l’application de l’atelier cloné localement et Docker en cours d’exécution.

Vous suivez l’atelier en autonomie ? Vous pouvez le terminer sans formateur : le parcours principal est entièrement en libre-service. Consultez Suivre cet atelier en autonomie pour connaître les adaptations, apprendre à utiliser votre agent de programmation comme formateur et accéder au Dépannage, qui couvre toutes les erreurs rencontrées pendant les tests.

Pour les formateurs

Le parcours formateur correspond point par point au parcours participant. Pour chaque module, vous disposez d’un budget de temps, d’une trame d’animation, des problèmes qui se produisent réellement en salle avec les moyens de les résoudre, ainsi que des procédures exactes permettant de ramener une personne, ou toute la salle, à un état opérationnel connu. Lisez d’abord la page d’accueil du parcours formateur pour connaître le programme de la salle et la liste de contrôle des ressources partagées.

Périmètre de l’atelier

L’application qui sert de base

L’application de l’atelier est une pile analytique autonome de type « cellule de crise » pour une entreprise new-yorkaise de réservation de taxis :

• Front-end — une application React monopage avec deux tableaux de bord : Ops (indicateurs opérationnels en direct) et Historical (agrégations sur de grandes plages et exploration détaillée). Elle accueille aussi le panneau de chat IA intégré que vous connecterez au module 08.
• Back-end — un service FastAPI exposant des points de terminaison analytiques sûrs et paramétrés.
• Base de données source — Postgres managé par ClickHouse comme source opérationnelle faisant autorité et origine de la capture des modifications vers ClickHouse.
• Entrepôt analytique — ClickHouse Cloud, vers lequel vous dirigerez le back-end au module 01 et qui recevra les données CDC, d’observabilité et les requêtes BI.

Vous ne construisez pas l’application à partir de zéro. L’application React/FastAPI s’exécute localement, tandis que tous les services avec état ou services produit sont hébergés dans le cloud dès le départ.

La plateforme utilisée

ClickHouse Cloud est une plateforme unique qui couvre toute la pile : de l’ingestion des données à sa base jusqu’à leur stockage et leur analyse dans ClickHouse, puis à leur observation et à l’ajout d’une couche d’IA. Cet atelier propose une visite guidée de ces composants : vous ingérez avec ClickPipes, analysez dans ClickHouse et observez avec ClickStack managé/HyperDX. Langfuse et OpenAI sont des services hébergés distincts.

Architecture (état final visé)

Commencez par regrouper les composants selon leur lieu d’exécution : l’application sans état et les outils sur votre ordinateur, les services avec état dans ClickHouse Cloud et les services d’IA hébergés séparément.

Circulation des données

Suivez maintenant un trajet en direct depuis le générateur de charge local, à travers Postgres managé et ClickPipes, jusqu’à default.realtime_trips, puis jusqu’aux tableaux de bord de l’application.

Les diagrammes ci-dessus sont générés à partir de workshops/build_workshop/docs/diagrams/gen_diagrams.py (modifiez le script et réexécutez-le pour régénérer les fichiers SVG) ; consultez ci-dessous le déroulement des modules.

Modules

Dix modules principaux, dans l’ordre. L’application est complète sur build-workshop-v1 ; à l’exception du module 07, aucun module ne nécessite donc de changement de branche : vous configurez et connectez des services au lieu de modifier le code de l’application. Les seuls changements de branche concernent les branches de panne du module 07.

Les durées totalisent environ 2 h 30 de travaux pratiques ; le reste de la session de trois heures est consacré à l’introduction, aux transitions et aux démonstrations finales.

Comment suivre l’atelier

Branches

L’application est déjà complète sur build-workshop-v1. Cet atelier porte sur la configuration et la connexion de services — CDC en temps réel, observabilité, agents et chat — et non sur la modification du code applicatif. Il n’y a donc rien à construire progressivement, branche après branche :

• Clonez l’application une seule fois au module 00, passez sur build-workshop-v1 et restez-y, sauf pendant les scénarios de panne du module 07.
• Les personnes qui arrivent en retard ne sont jamais bloquées : les ressources managées résident côté service, et l’application locale complète redémarre depuis la branche de l’atelier et .env.workshop. Aucun changement de branche par module n’est nécessaire pour rattraper le groupe.
• Les seuls changements de branche ont lieu au module 07 (panne et réparation), qui utilise les branches de panne (fault/01-map-not-loading, fault/02-zone-stats-500, fault/03-slow-dashboard). Vous en activez une, diagnostiquez la panne, conservez la correction, puis revenez à build-workshop-v1 en suivant la procédure de mise à l’abri et de changement de branche du module 07.

Variables d’environnement

La configuration de l’atelier se trouve dans un unique fichier .env.workshop à la racine du dépôt de l’application. Un fichier .env.workshop.example sûr est versionné ; copiez-le et ne renseignez que les valeurs qui vous appartiennent :

cp .env.workshop.example .env.workshop

La pile le lit explicitement grâce à --env-file :

docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d

Vous renseignerez les valeurs pendant la configuration du module 00, sauf le bloc ClickStack, ajouté au module 05 :

• CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD (ainsi que CLICKHOUSE_PORT=8443, CLICKHOUSE_USER=default, CLICKHOUSE_DATABASE=nyc_tlc_data, CLICKHOUSE_SECURE=true) — votre service Cloud (module 00). CLICKHOUSE_HOST est le simple nom d’hôte, sans schéma ni port.
• OPENAI_API_KEY, LLM_MODEL=gpt-5.4-mini, LLM_BASE_URL — le LLM d’exécution du chat intégré à l’application (module 00).
• LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL — votre projet Langfuse (module 00). LANGFUSE_BASE_URL est le nom de variable d’environnement de Langfuse v4 ; utilisez https://us.cloud.langfuse.com (États-Unis) ou https://cloud.langfuse.com (Europe).
• OTLP_AUTH_TOKEN, CLICKSTACK_DATABASE=otel, OTEL_SERVICE_NAME=nyc-taxi-backend — observabilité, dans la section ClickStack du même fichier .env.workshop (module 05).

Ne versionnez jamais votre fichier .env.workshop renseigné ; il est ignoré par Git.

Organisation du dépôt

Tout se trouve dans un seul dépôt (ClickHouse_Demos), sur la branche build-workshop-v1. Le code des exercices de chaque atelier se trouve sous workshops/ : l’application utilisée est donc workshops/build_workshop/. Le guide publié que vous consultez se trouve dans le site partagé à la racine du dépôt, site/, qui héberge aussi l’atelier Agent Arena et le guide RTA statique.

site/                           # the shared Next.js + Fumadocs site (all workshops)
  content/docs/build-workshop/  # this playbook (the site you are reading)
    index.mdx                   # this overview
    learner/                    # self-paced guide, the lessons 00-setup ... 09-wrap-up,
                                #   and a troubleshooting reference
    instructor/                 # facilitator notes: 00-setup ... 09-wrap-up
  src/                          # Next.js + Fumadocs app
  README.md                     # run, build, deploy, and authoring guide

workshops/build_workshop/
  app/                         # the NYC-taxi app you build on (cloned in module 00)
    frontend/                  # React SPA (Ops + Historical dashboards, chat panel)
    backend/                   # FastAPI analytics API + AI chat
    db/cloud/001_cloud_schema.sql   # maintainer fixture; Module 01 contains the copyable SQL
    docker-compose.workshop.yml     # the workshop stack (Cloud + ClickPipes)
    docker-compose.otel.yml         # the ClickStack observability overlay (module 05)
    .env.workshop.example      # single env template (Cloud + chat + observability);
                               #   copy to .env.workshop and fill in your values

Pour aller plus loin