SRE con IA y depuración de aplicaciones

Te damos la bienvenida a la guía del ClickHouse BUILD Workshop. Durante tres horas, llevarás una aplicación de analítica de taxis de Nueva York (front-end en React, back-end en FastAPI y Postgres como base de datos de origen) de extremo a extremo a ClickHouse Cloud, utilizando tu propia herramienta de programación con agentes para construirla. Al terminar, dispondrás de captura de datos modificados en tiempo real desde un Postgres administrado, BI conversacional sobre tus datos, observabilidad completa, un flujo de trabajo de SRE asistido por IA y un chat con IA dentro de la aplicación, registrado de extremo a extremo. Además, habrás practicado el diagnóstico de un incidente en directo con un SRE de IA.

El mismo taller es compatible con macOS y Windows. Elige tu equipo una sola vez en el encabezado de la página; la guía mantendrá visible la configuración correcta en todas partes. En Windows, las herramientas compartidas del taller se ejecutan dentro de Ubuntu en WSL 2.

Te llevarás un prototipo en ejecución y este repositorio para enseñárselo a tu equipo. Los artefactos administrados de ClickHouse, Postgres, ClickPipes, Agents y ClickStack se conservan durante la prueba; los traces de Langfuse permanecen en Langfuse Cloud. Cuando retomes el proyecto, reinicia con Docker la aplicación local y el reenviador de telemetría. Al final podrás mostrar cinco funciones en directo:

• un panel operativo en tiempo real en ClickHouse Cloud;
• una canalización de captura de datos modificados que transmite desde Postgres administrado;
• BI conversacional sobre tus datos con ClickHouse Agents;
• un panel y una alerta de SRE creados por IA a partir de tu telemetría;
• un chat con IA dentro de la aplicación registrado de extremo a extremo en Langfuse.

Esta guía tiene dos itinerarios. El itinerario del participante contiene la lección que sigues en la sesión. El itinerario del instructor es el material complementario del facilitador para el mismo módulo: tiempos, guion de presentación, fallos habituales y pasos de restablecimiento.

Para participantes

Avanzarás módulo a módulo. Cada uno indica un punto de partida, explica por qué es importante el paso, establece un objetivo concreto, te guía mediante pasos numerados y termina con una comprobación que puedes realizar por tu cuenta. No tienes que mantener el ritmo de todo el grupo: si te retrasas, la sección Punto de partida de cada módulo especifica exactamente qué debe estar listo, para que puedas retomar desde ahí a tu propio ritmo.

Lo que necesitas ese día:

• Un portátil que cumpla los requisitos de 00 Configuración.
• Tu propia herramienta de programación con agentes (Claude Code, Cursor, Codex CLI o Windsurf), con la sesión iniciada y un plan activo.
• Una cuenta de ClickHouse Cloud con créditos de prueba visibles (creada durante la preparación previa).
• El repositorio de la aplicación del taller clonado en local y Docker en ejecución.

¿Lo harás a tu ritmo? Puedes completar todo el taller sin instructor; el recorrido principal es totalmente autoguiado. Consulta Cómo realizar este taller a tu ritmo para saber qué cambia, cómo utilizar tu agente de programación como instructor y cómo recurrir a la referencia de solución de problemas para cada fallo observado durante las pruebas.

Para instructores

El itinerario del instructor corresponde punto por punto al del participante. Para cada módulo recibirás un tiempo asignado, un guion de presentación, los fallos que realmente se producen durante la sesión y cómo desbloquearlos, además de los pasos exactos para devolver a un asistente (o a todo el grupo) a un estado conocido y funcional. Lee primero la página de inicio del itinerario del instructor para ver el programa general y la lista de recursos compartidos.

Alcance del taller

La aplicación sobre la que trabajas

La aplicación del taller es una pila autónoma de analítica, a modo de «sala de crisis», para una empresa de transporte en taxi de Nueva York:

• Front-end: una aplicación de página única en React con dos paneles: Ops (métricas operativas en directo) y Historical (agregaciones y desgloses de intervalos amplios). También contiene el panel de chat con IA que conectarás en el módulo 08.
• Back-end: un servicio FastAPI que expone endpoints de analítica seguros y parametrizados.
• Base de datos de origen: Postgres administrado por ClickHouse como fuente operativa de referencia, origen de la captura de datos modificados que se envían a ClickHouse.
• Almacén analítico: ClickHouse Cloud, al que apuntas el back-end en el módulo 01 y que recibe CDC, datos de observabilidad y consultas de BI.

No construirás la aplicación desde cero. La aplicación React/FastAPI se ejecuta localmente, mientras que todos los servicios con estado, tanto de datos como de producto, están alojados en la nube desde el principio.

La plataforma sobre la que trabajas

ClickHouse Cloud es una sola plataforma que abarca toda la pila: desde la ingesta de datos en la base, pasando por el almacenamiento y el análisis en ClickHouse, hasta la observación y la incorporación de una capa de IA encima. Este taller ofrece una visita guiada por esos componentes: ingieres con ClickPipes, analizas en ClickHouse y observas con Managed ClickStack/HyperDX. Langfuse y OpenAI son servicios alojados independientes.

Arquitectura (estado final objetivo)

Primero, agrupa los componentes según dónde se ejecutan: la aplicación sin estado y las herramientas en tu portátil, los servicios con estado en ClickHouse Cloud y los servicios de IA alojados por separado.

Cómo fluyen los datos

Ahora sigue un viaje en directo desde el generador de carga local, a través de Postgres administrado y ClickPipes, hasta default.realtime_trips y, por último, los paneles de la aplicación.

Los diagramas anteriores se generan desde workshops/build_workshop/docs/diagrams/gen_diagrams.py (edita el script y vuelve a ejecutarlo para regenerar los SVG); consulta a continuación el flujo de los módulos.

Módulos

Diez módulos principales, en orden. La aplicación está completa en build-workshop-v1, por lo que ningún módulo salvo el 07 necesita un checkout específico: configuras y conectas servicios en lugar de modificar el código de la aplicación. Los únicos cambios de branch son a los branches de fallos del módulo 07.

Los tiempos suman unas 2 horas y 30 minutos de trabajo práctico; el resto de la sesión de tres horas cubre la apertura, las transiciones y las demostraciones finales.

Cómo seguir el taller

Branches

La aplicación ya está completa en build-workshop-v1. Este taller consiste en configurar y conectar servicios — CDC en tiempo real, observabilidad, agentes y chat —, no en editar el código de la aplicación, así que no hay que construirla branch a branch:

• Clona la aplicación una vez en el módulo 00, cambia a build-workshop-v1 y permanece ahí, excepto mientras ejecutes los escenarios de fallos del módulo 07.
• Quienes lleguen tarde nunca se quedarán bloqueados: los recursos administrados están en el servicio, y la aplicación local completa se reinicia desde el branch del taller junto con .env.workshop. No hay checkouts por módulo para ponerse al día.
• Los únicos cambios de branch ocurren en el módulo 07 (Detección y corrección de fallos), que usa los branches de fallo (fault/01-map-not-loading, fault/02-zone-stats-500, fault/03-slow-dashboard). Haces checkout de uno, diagnosticas el fallo, conservas la corrección y vuelves a build-workshop-v1 con el restablecimiento del módulo 07 para guardar cambios y cambiar de branch.

Variables de entorno

La configuración del taller se encuentra en un único archivo .env.workshop, en la raíz del repositorio de la aplicación. Se incluye un .env.workshop.example seguro; cópialo y rellena solo los valores que te pertenecen:

cp .env.workshop.example .env.workshop

La pila lo lee de forma explícita mediante --env-file:

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

Rellenas los valores durante la configuración del módulo 00, salvo el bloque de ClickStack, que añadirás en el módulo 05:

• CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD (además de CLICKHOUSE_PORT=8443, CLICKHOUSE_USER=default, CLICKHOUSE_DATABASE=nyc_tlc_data, CLICKHOUSE_SECURE=true): tu servicio en la nube (módulo 00). CLICKHOUSE_HOST contiene solo el nombre de host, sin esquema ni puerto.
• OPENAI_API_KEY, LLM_MODEL=gpt-5.4-mini, LLM_BASE_URL: la LLM en tiempo de ejecución del chat dentro de la aplicación (módulo 00).
• LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL: tu proyecto de Langfuse (módulo 00). LANGFUSE_BASE_URL es el nombre de la variable de entorno en Langfuse v4; utiliza https://us.cloud.langfuse.com (EE. UU.) o https://cloud.langfuse.com (UE).
• OTLP_AUTH_TOKEN, CLICKSTACK_DATABASE=otel, OTEL_SERVICE_NAME=nyc-taxi-backend: observabilidad, en la sección ClickStack del mismo .env.workshop (módulo 05).

Nunca añadas al repositorio tu .env.workshop relleno; Git lo ignora.

Estructura del repositorio

Todo se encuentra en un solo repositorio (ClickHouse_Demos), en el branch build-workshop-v1. El código de laboratorio de cada taller está en workshops/, por lo que la aplicación sobre la que trabajas es workshops/build_workshop/; esta guía publicada se encuentra en el sitio compartido de la raíz del repositorio, en site/, que también aloja el taller Agent Arena y la guía estática de RTA.

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

Siguientes pasos