05 ClickStack

Encaminhe a telemetria com um coletor local sem estado, ative o Managed ClickStack e inspecione os dados no HyperDX hospedado na nuvem.

Ponto de partida

Você está em build-workshop-v1 — não é necessário fazer checkout. Reserve cerca de 15 minutos. O aplicativo já está instrumentado para OpenTelemetry; neste módulo, você o ativa com a sobreposição do coletor.

Pré-requisito: seu serviço na nuvem em execução (módulo 01).

Por quê

Para diagnosticar o aplicativo mais tarde, primeiro você precisa enxergá-lo. O ClickStack (a pilha de observabilidade do ClickHouse, com o HyperDX como interface) armazena traces e logs do OpenTelemetry no ClickHouse. Neste módulo, você ativa o coletor para que cada solicitação que atravessa o aplicativo produza telemetria consultável.

Objetivo

Traces do aplicativo e logs de consultas do back-end fluindo para o ClickStack, com pelo menos um trace de solicitação de ponta a ponta e um fluxo visível de registros de consultas bem-sucedidas.

Etapa 1 — Execute a sobreposição do coletor OpenTelemetry

O HyperDX, o armazenamento e o processamento de consultas permanecem gerenciados no ClickHouse Cloud. O único componente local é um coletor OpenTelemetry sem estado ao lado do aplicativo local; ele encaminha a telemetria e não é uma implantação local do ClickStack ou do HyperDX.

Primeiro, verifique as portas do coletor

O coletor publica OTLP nas portas 4317 e 4318 do host, que frequentemente já estão em uso. Se ./preflight.sh em ClickHouse_Demos/workshops/build_workshop/app tiver exibido um AVISO sobre elas no módulo 00, defina OTEL_GRPC_HOST_PORT e OTEL_HTTP_HOST_PORT no .env.workshop com os valores sugeridos pela verificação prévia (por exemplo, 24317 / 24318) antes de iniciar a sobreposição. O back-end acessa o coletor pela rede interna, portanto é seguro remapear as portas do host. De qualquer lugar dentro do repositório clonado, execute novamente cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh para confirmar que as portas estão livres.

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

Esses valores ficam na seção de observabilidade do ClickStack em .env.workshop.example; preencha-os no seu .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

Não importe esse arquivo para o ambiente do shell. O comando do Compose abaixo o lê diretamente, o que mantém senhas e chaves de API fora das variáveis exportadas do shell e garante que alterações posteriores no arquivo entrem em vigor.

Agora inicie a pilha com a sobreposição. Ela define OTEL_ENABLED=true no back-end, adiciona o serviço otel-collector (clickhouse/clickstack-otel-collector) e recria o front-end com as configurações de telemetria do navegador:

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

O coletor reutiliza CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD do .env.workshop; o back-end exporta OTLP para http://otel-collector:4318 (HTTP/protobuf). Para também coletar a saída bruta dos contêineres em um host Linux, adicione --profile container-logs.

Etapa 2 — Ative o Managed ClickStack no seu serviço

O workshop usa o Managed ClickStack (HyperDX) dentro do seu próprio serviço ClickHouse Cloud: o coletor grava tabelas otel_* no serviço, e a interface do HyperDX as renderiza ali. Ative-o no console:

Console - seu serviço -> ClickStack -> Start Ingestion -> pule a etapa do coletor (o coletor do aplicativo já está em execução desde a etapa 1) -> Launch ClickStack

Isso inicia sua sessão no HyperDX via SSO. A telemetria já começou a fluir, portanto a interface hospedada pode exibir dados assim que abrir.

Managed ClickStack: diferenças em relação à configuração clássica

O back-end usa OpenTelemetry padrão, não o pacote de conveniência hyperdx-opentelemetry sugerido pela documentação do ClickStack. Esse pacote fixa opentelemetry-api==1.30.0, o que entra em conflito com o SDK v4 do Langfuse usado pelo recurso de chat (que requer opentelemetry-api>=1.33.1) — os dois não podem compartilhar o mesmo ambiente. O coletor do ClickStack recebe OTLP padrão, portanto a distribuição convencional se comporta da mesma forma; o workshop apenas define diretamente as variáveis de ambiente do exportador.
A telemetria do ClickStack fica em um banco de dados separado no seu serviço (CLICKSTACK_DATABASE=otel), distinto do banco de dados do aplicativo (CLICKHOUSE_DATABASE=nyc_tlc_data).
Os traces e logs Python do back-end fluem por OTLP a partir do back-end instrumentado automaticamente. O coletor opcional --profile container-logs serve apenas para serviços sem instrumentação, como o gravador de viagens; o caminho de logs do Docker no Linux pode não estar disponível no Docker Desktop.

Etapa 3 — Gere e encontre tráfego no ClickStack

Abra o painel Ops e mantenha o intervalo padrão 1m e a atualização automática 5s em execução por cerca de 30 segundos. Depois, abra o ClickStack:

Em Traces, acompanhe uma solicitação de ponta a ponta (front-end -> back-end -> ClickHouse).
Em Logs, selecione nyc-taxi-backend e encontre registros repetidos de ClickHouse query ok. Os carimbos de data e hora devem avançar a cada atualização.
Mantenha a gravidade significativa: consultas bem-sucedidas são DEBUG; novas tentativas reais após inatividade e falhas aparecem como WARNING ou ERROR.

Um serviço chamado nyc-taxi-backend deve aparecer no HyperDX, com solicitações a /api/... exibidas como traces, cada uma contendo um span filho clickhouse.query.

Visualização Search do HyperDX mostrando traces de nyc-taxi-backend — uma lista ao vivo de spans GET /api/health e POST com colunas de data e hora, serviço e duração

O HyperDX renderizando os traces do aplicativo: o serviço nyc-taxi-backend com seus spans de solicitação /api/....

Como verificar se você terminou

Um serviço chamado nyc-taxi-backend aparece no HyperDX.
As solicitações a /api/... aparecem como traces, cada uma com um span filho clickhouse.query contendo db.statement, db.elapsed_ms e db.rows_returned.
A origem Log mostra novos registros DEBUG ... ClickHouse query ok enquanto o painel Ops permanece aberto.
Você ainda não verá erros de consulta: um aplicativo íntegro e com dados carregados não aciona os limites de segurança, e solicitações 4xx nunca chegam ao ClickHouse. No módulo 07, a falha injetada torna observável um span clickhouse.query com erro (e error.category).

Resumo

O aplicativo agora é observável: traces e logs de consultas do back-end são registrados no ClickHouse e podem ser explorados no ClickStack. O perfil opcional container-logs adiciona a saída padrão do gravador de viagens em hosts Linux compatíveis. Essa telemetria é a base para o trabalho de SRE com IA que vem a seguir.

Estado final

A telemetria está fluindo para o ClickStack. Continue em 06 SRE com IA para que seu agente a utilize.