SRE com IA e depuração de aplicativos

Boas-vindas ao guia do ClickHouse BUILD Workshop. Ao longo de três horas, você levará um aplicativo de análise de corridas de táxi de Nova York (front-end em React, back-end em FastAPI e Postgres como banco de dados de origem) de ponta a ponta para o ClickHouse Cloud, usando sua própria ferramenta de programação com agentes para construir tudo. Ao final, você terá captura de dados alterados em tempo real a partir de um Postgres gerenciado, BI conversacional sobre seus dados, observabilidade completa, um fluxo de trabalho de SRE assistido por IA e um chat com IA dentro do aplicativo, rastreado de ponta a ponta. Além disso, terá praticado o diagnóstico de um incidente ao vivo com um SRE de IA.

O mesmo workshop é compatível com macOS e Windows. Escolha seu computador uma vez no cabeçalho da página; o guia manterá visível em todas as páginas a configuração correta. No Windows, as ferramentas compartilhadas do workshop são executadas no Ubuntu com WSL 2.

Você sairá com um protótipo em execução e este repositório para mostrar à sua equipe. Os artefatos gerenciados do ClickHouse, Postgres, ClickPipes, Agents e ClickStack persistem durante o período de avaliação; os traces do Langfuse permanecem no Langfuse Cloud. Quando voltar ao projeto, reinicie o aplicativo local e o encaminhador de telemetria com o Docker. Ao final, você poderá demonstrar cinco recursos ao vivo:

• um painel operacional em tempo real no ClickHouse Cloud;
• um pipeline de captura de dados alterados que transmite dados do Postgres gerenciado;
• BI conversacional sobre seus dados com o ClickHouse Agents;
• um painel e um alerta de SRE criados por IA com base na sua telemetria;
• um chat com IA no aplicativo rastreado de ponta a ponta no Langfuse.

Este guia tem duas trilhas. A trilha do participante contém as lições que você acompanha durante a sessão. A trilha do instrutor é o material correspondente para o facilitador em cada módulo: cronograma, roteiro de apresentação, falhas comuns e etapas de redefinição.

Para participantes

Você avançará módulo por módulo. Cada um identifica um ponto de partida, explica por que a etapa é importante, define um objetivo concreto, orienta você em etapas numeradas e termina com uma verificação que você mesmo pode fazer. Não é necessário acompanhar o ritmo de toda a turma: se você ficar para trás, a seção Ponto de partida de cada módulo informa exatamente o que precisa estar pronto, para que você possa retomar dali no seu próprio ritmo.

O que você precisa no dia:

• Um laptop que atenda aos pré-requisitos de 00 Configuração.
• Sua própria ferramenta de programação com agentes (Claude Code, Cursor, Codex CLI ou Windsurf), com uma sessão iniciada e um plano ativo.
• Uma conta do ClickHouse Cloud com créditos de avaliação visíveis (criada durante a preparação prévia).
• O repositório do aplicativo do workshop clonado localmente e o Docker em execução.

Vai fazer no seu próprio ritmo? Você pode concluir todo o workshop sem instrutor; o percurso principal é totalmente autoguiado. Consulte Como fazer este workshop no seu próprio ritmo para saber o que muda, como usar seu agente de programação como instrutor e como recorrer à referência de solução de problemas para cada falha observada nos testes.

Para instrutores

A trilha do instrutor corresponde à trilha do participante, módulo a módulo. Em cada módulo, você recebe o tempo previsto, um roteiro de apresentação, as falhas que realmente ocorrem durante a sessão e como desbloquear os participantes, além das etapas exatas de redefinição para levar um participante (ou toda a turma) de volta a um estado conhecido e funcional. Leia primeiro a página inicial da trilha do instrutor para ver o roteiro geral da sessão e a lista de recursos compartilhados.

Escopo do workshop

O aplicativo usado como base

O aplicativo do workshop é uma pilha independente de análise no estilo “sala de crise” para uma empresa de corridas de táxi em Nova York:

• Front-end — um aplicativo de página única em React com dois painéis: Ops (métricas operacionais ao vivo) e Historical (agregações e detalhamentos em intervalos amplos). Ele também hospeda o painel de chat com IA que você conectará no módulo 08.
• Back-end — um serviço FastAPI que expõe endpoints de análise seguros e parametrizados.
• Banco de dados de origem — Postgres gerenciado pelo ClickHouse como fonte operacional oficial, de onde se origina a captura de dados alterados enviada ao ClickHouse.
• Data warehouse analítico — ClickHouse Cloud, ao qual você direciona o back-end no módulo 01 e que recebe CDC, dados de observabilidade e consultas de BI.

Você não construirá o aplicativo do zero. O aplicativo React/FastAPI é executado localmente, enquanto todos os serviços de produto ou de dados com estado ficam hospedados na nuvem desde o início.

A plataforma usada como base

O ClickHouse Cloud é uma plataforma única que abrange toda a pilha — desde a ingestão de dados na base, passando pelo armazenamento e pela análise no ClickHouse, até a observação e a inclusão de uma camada de IA por cima. Este workshop é um tour guiado por esses componentes: você faz a ingestão com ClickPipes, analisa no ClickHouse e observa com Managed ClickStack/HyperDX. Langfuse e OpenAI são serviços hospedados separados.

Arquitetura (estado final desejado)

Primeiro, agrupe os componentes de acordo com o local em que são executados: o aplicativo sem estado e as ferramentas no seu laptop, os serviços com estado no ClickHouse Cloud e os serviços de IA hospedados separadamente.

Como os dados fluem

Agora acompanhe uma viagem ao vivo desde o gerador de carga local, passando pelo Postgres gerenciado e pelo ClickPipes, até default.realtime_trips e, por fim, os painéis do aplicativo.

Os diagramas acima são gerados a partir de workshops/build_workshop/docs/diagrams/gen_diagrams.py (edite o script e execute-o novamente para regenerar os SVGs) — veja abaixo o fluxo dos módulos.

Módulos

Dez módulos principais, na ordem. O aplicativo está completo em build-workshop-v1, portanto nenhum módulo, exceto o 07, exige um checkout específico — você configura e conecta serviços, em vez de alterar o código do aplicativo. As únicas trocas de branch são para os branches de falha no módulo 07.

Os tempos somam aproximadamente 2 horas e 30 minutos de trabalho prático; o restante da sessão de três horas cobre a abertura, as transições e as demonstrações finais.

Como acompanhar o workshop

Branches

O aplicativo já está completo em build-workshop-v1. Este workshop trata da configuração e da conexão de serviços — CDC em tempo real, observabilidade, agentes e chat —, não da edição do código do aplicativo. Portanto, não há nada para construir branch por branch:

• Clone o aplicativo uma vez no módulo 00, mude para build-workshop-v1 e permaneça nesse branch, exceto durante a execução dos cenários de falha no módulo 07.
• Quem entrar mais tarde nunca ficará sem saída: os recursos gerenciados ficam no serviço, e o aplicativo local completo é reiniciado a partir do branch do workshop junto com .env.workshop. Não há checkout por módulo para recuperar o atraso.
• As únicas trocas de branch ocorrem no módulo 07 (Identificar e corrigir falhas), que usa os branches de falha (fault/01-map-not-loading, fault/02-zone-stats-500, fault/03-slow-dashboard). Você faz checkout de um deles, diagnostica a falha, preserva a correção e volta para build-workshop-v1 usando a redefinição do módulo 07, que guarda as alterações e troca de branch.

Variáveis de ambiente

A configuração do workshop fica em um único arquivo .env.workshop, na raiz do repositório do aplicativo. Um .env.workshop.example seguro está versionado; copie-o e preencha apenas os valores que pertencem a você:

cp .env.workshop.example .env.workshop

A pilha lê o arquivo explicitamente por meio de --env-file:

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

Você preenche os valores durante a configuração do módulo 00, exceto o bloco do ClickStack, que será adicionado no módulo 05:

• CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD (além de CLICKHOUSE_PORT=8443, CLICKHOUSE_USER=default, CLICKHOUSE_DATABASE=nyc_tlc_data, CLICKHOUSE_SECURE=true) — seu serviço na nuvem (módulo 00). CLICKHOUSE_HOST é apenas o nome do host, sem esquema nem porta.
• OPENAI_API_KEY, LLM_MODEL=gpt-5.4-mini, LLM_BASE_URL — a LLM em tempo de execução para o chat no aplicativo (módulo 00).
• LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL — seu projeto do Langfuse (módulo 00). LANGFUSE_BASE_URL é o nome da variável de ambiente no Langfuse v4; use https://us.cloud.langfuse.com (EUA) ou https://cloud.langfuse.com (UE).
• OTLP_AUTH_TOKEN, CLICKSTACK_DATABASE=otel, OTEL_SERVICE_NAME=nyc-taxi-backend — observabilidade, na seção ClickStack do mesmo .env.workshop (módulo 05).

Nunca adicione o .env.workshop preenchido ao repositório; o arquivo é ignorado pelo Git.

Estrutura do repositório

Tudo está em um único repositório (ClickHouse_Demos), no branch build-workshop-v1. O código de laboratório de cada workshop fica em workshops/, portanto o aplicativo usado como base é workshops/build_workshop/; este guia publicado fica no site compartilhado na raiz do repositório, em site/, que também hospeda o workshop Agent Arena e o guia estático 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

Próximos passos