05 ClickStack

Material do facilitador correspondente à lição 05 ClickStack do participante.

Cronograma

Cerca de 15 minutos. A telemetria precisa se acumular antes do laboratório de incidentes do módulo 07; por isso, inicie o coletor assim que este módulo permitir e mantenha-o em execução.

Roteiro de apresentação

• O Managed ClickStack armazena a telemetria no ClickHouse Cloud; o HyperDX é a interface hospedada. O coletor local apenas encaminha os dados. Mostre tanto um trace de solicitação de ponta a ponta quanto um registro recente DEBUG ... ClickHouse query ok na origem Log.
• Peça aos participantes que iniciem o coletor na etapa 1 antes de abrir o Managed ClickStack na etapa 2. Assim, a telemetria tem tempo para chegar e a primeira visualização na interface hospedada já será útil.
• Mostre no projetor um trace de solicitação de ponta a ponta.

Falhas comuns

• As portas OTLP 4317/4318 do host já estão em uso: peça aos participantes que definam OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT no .env.workshop (a verificação prévia sugere valores, por exemplo, 24317/24318) e, de qualquer lugar dentro do repositório clonado, executem cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh; o back-end acessa o coletor pela rede interna, portanto o remapeamento é seguro.
• A sobreposição do coletor não foi iniciada (o segundo -f docker-compose.otel.yml foi esquecido), então nada chega ao HyperDX.
• OTLP_AUTH_TOKEN não corresponde ao valor esperado, ou faltam variáveis CLICKHOUSE_* no .env.workshop (o coletor reutiliza CLICKHOUSE_HOST/PORT/USER/PASSWORD para acessar o serviço na nuvem).
• Ainda não foi gerado tráfego; peça aos participantes que naveguem pelos dois painéis.
• No Docker Desktop, o coletor opcional --profile container-logs não consegue montar o caminho de logs do host (o daemon está em uma VM); isso é esperado. Os logs do back-end ainda trafegam por OTLP. Use docker compose ... logs apenas para diagnosticar o encaminhador se o HyperDX estiver vazio.
• Antes, depois que a sobreposição recriava o back-end, o aplicativo retornava 502 (o nginx do front-end mantinha em cache o IP antigo do back-end). Agora o front-end resolve novamente o endereço a cada solicitação, portanto se recupera sozinho em cerca de 10 s e não precisa ser reiniciado manualmente. Correção confirmada no ensaio.
• Referência do ensaio: pipeline de telemetria validado de ponta a ponta — traces de nyc-taxi-backend com spans filhos clickhouse.query contendo db.statement / db.elapsed_ms / db.rows_returned. Comportamento confirmado no ensaio em ambiente limpo de julho de 2026.

Etapas de redefinição

• Reinicie usando os dois arquivos do Compose: docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build.
• No console do Cloud, abra o serviço, escolha ClickStack e reabra a interface hospedada caso a sessão de SSO tenha expirado.