Guia passo a passo do HyperDX

O HyperDX é a interface de observabilidade integrada ao ClickStack — incluída em todos os serviços do ClickHouse Cloud. Este guia apresenta as quatro tarefas que você precisa realizar no HyperDX para o laboratório de migração:

1. Iniciar o ClickStack pelo console do Cloud.
2. Criar três fontes de dados — uma para traces, uma para logs e uma para métricas OTEL — apontando para o banco de dados otel preenchido na Etapa 2.
3. Pesquisar logs em tempo real na visualização Search para confirmar o fluxo dos dados.
4. Criar um gráfico com o assistente de IA para demonstrar a visualização ad hoc sem escrever SQL.

Pré-requisitos: A Etapa 4 do README.md foi concluída sem erros — otel.otel_logs_v2, otel.otel_traces e otel.otel_metrics_* estão recebendo dados, e você pode confirmar com bash scripts/validate_migration.sh.

---

Etapa A — Iniciar o ClickStack

1. Entre em clickhouse.cloud e abra o serviço provisionado na Etapa 1 do README.
2. Na barra lateral esquerda do console SQL, role até o final. Clique no ícone de abertura (↗) ao lado de ClickStack (Beta).
3. O ClickStack é aberto em uma nova guia e autentica você pelo SSO do Cloud — não é necessário um login separado.

O que você deve ver primeiro no console SQL: o banco de dados otel no seletor de bancos de dados (parte superior central), com as 11 tabelas, 3 views materializadas e 2 dicionários criados na Etapa 2 — otel_logs, otel_logs_v2, otel_traces, otel_metrics_* (5 tabelas), geoip_data + geoip_country/geoip_city (1 tabela + 2 dicionários), alert_error_rate*, logs_summary_1min*. Se algum item estiver ausente, execute novamente clickhouse/dictionaries.sql, clickhouse/schema.sql e clickhouse/alert-tables.sql antes de continuar.

---

Etapa B — Criar as três fontes de dados

O HyperDX consulta o ClickHouse por meio de "fontes" nomeadas que vinculam uma guia da interface (Search, Service Map, Chart Explorer etc.) a uma tabela específica e a uma convenção de mapeamento de colunas. Você criará uma fonte por tipo de sinal.

Abra Team Settings na barra lateral inferior esquerda e depois Data → Sources. Clique em Add source para criar cada uma das três fontes abaixo.

B.1 — Fonte de traces

Clique em Save Source. O resumo Trace, Default, otel.otel_traces deve aparecer no topo da lista Sources.

B.2 — Fonte de logs

Clique novamente em Add source e configure:

Por que TimestampTime e não Timestamp? Timestamp é DateTime64(9) (nanossegundos). O seletor de intervalo de tempo e os buckets de histograma do HyperDX usam por padrão a precisão de DateTime; apontar para a coluna materializada TimestampTime evita conversões implícitas em todas as consultas de dashboard.

B.3 — Fonte de métricas OTEL

Clique novamente em Add source e configure:

A fonte de métricas OTEL abrange todas as cinco tabelas de métricas, pois o modelo de dados do OTel codifica tipos diferentes de métricas em linhas/formatos diferentes. O HyperDX direciona a consulta à tabela correta conforme o tipo de métrica. Definir Correlated Log Source = log permite ao HyperDX saltar de um gráfico de métricas para os logs correspondentes com um clique.

Depois de salvar as três fontes, a lista Sources deve mostrar Traces, log e otel_metrics — com o mesmo formato da captura acima (uma entrada recolhida por fonte).

---

Etapa C — Pesquisar logs em tempo real

Clique em Search na barra lateral esquerda. No topo, selecione a fonte log que acabou de criar.

Você deve ver:

• Um histograma das contagens de eventos ao longo do tempo (use o seletor de intervalo para definir "Last 15 minutes" ou "Last 1 hour")
• Uma tabela de linhas de log com as colunas Timestamp, service, level, body
• Uma barra lateral de facetas à esquerda, listando campos de alta cardinalidade como ServiceName (com contagens por serviço) e SeverityText

Experimente:

• Filtrar por um serviço: clique em inventory-service (ou qualquer serviço) na faceta ServiceName — a tabela é recarregada, filtrada por esse serviço, em uma fração de segundo.
• Pesquisar por string: digite error na barra de pesquisa superior. Os índices de texto do ClickHouse (o índice de salto text(tokenizer='sparseGrams') em Body no schema.sql) aceleram muito essa busca em comparação com uma varredura completa.
• Inspecionar uma linha: clique em qualquer linha de log para expandir a visualização estruturada — cada chave do Map LogAttributes se torna um filtro clicável.

Observação sobre o intervalo de tempo: a configuração start_at: end no coletor baseado em arquivos significa que as linhas históricas existentes antes da Etapa 3b não estão em otel_logs_v2. Se "Last 24 hours" parecer ter poucos dados nas primeiras horas, isso é esperado — os dados começam quando o coletor foi iniciado.

---

Etapa D — Criar um gráfico com o assistente de IA

O AI Assistant do HyperDX (atualmente identificado como Experimental) traduz descrições em linguagem natural em configurações de gráficos.

1. Clique em Chart Explorer na barra lateral esquerda.

2. Clique no botão AI Assistant [A] na parte superior do painel do gráfico.

3. Com a fonte log selecionada, digite uma instrução em linguagem natural na caixa de entrada, por exemplo:

   Error count by services for past 2 hours

4. Pressione Enter. O assistente preenche a configuração do gráfico abaixo: tipo de gráfico (Line/Bar), fonte de dados (log), agregação (Count of Events) e uma cláusula Where (SeverityText = 'ERROR').

5. O gráfico é renderizado imediatamente. Ajuste o intervalo de tempo ou o tipo de gráfico nas guias superiores (Line/Bar, Table, Number, Pie, Search, Markdown).

Salve gráficos úteis pelo campo Chart Name e pelo ícone de salvar — eles aparecerão em Saved Searches / Dashboards na barra lateral para reutilização posterior.

Biblioteca de instruções — recrie todos os painéis do Kibana da Parte 1

Os seis dashboards do Kibana da Parte 1 contêm 30 painéis no total. As tabelas abaixo oferecem uma receita de uma instrução por painel para você reconstruir cada gráfico no HyperDX. Para cada entrada:

• Fonte — defina-a no AI Assistant antes de enviar a instrução (log para tudo de otel_logs_v2, Traces para tudo de otel_traces, otel_metrics para gráficos de métricas).
• Gráfico — a guia de tipo de gráfico do HyperDX a selecionar (ou deixe o assistente escolher) antes de salvar. Consulte a legenda abaixo.
• Filtro — muitos painéis do Kibana tinham escopo implícito por fluxo de dados (por exemplo, o dashboard Web Traffic consultava apenas logs-web_access-lab). No ClickHouse, isso é expresso por uma cláusula Where; as instruções abaixo incluem o filtro ou usam o filtro da fonte no HyperDX. Se o AI Assistant não aplicar o filtro, altere o gráfico para o modo SQL e adicione a expressão Where sugerida.
• Alternativa para o nome do campo — o AI Assistant mapeia termos em linguagem natural às colunas do esquema. Se uma instrução produzir um gráfico vazio, edite manualmente o campo Where / agregação gerado usando as dicas da coluna Dica de campo.

Tipos de gráfico do HyperDX — legenda de referência

O painel Chart Explorer tem seis guias na parte superior (Line/Bar, Table, Number, Pie, Search, Markdown). O mapeamento entre os tipos de gráfico do HyperDX e as visualizações do Kibana que eles substituem é:

Onde está "Histogram"? O Kibana tem uma visualização explícita "Histogram" (contagens divididas em buckets por campo numérico ou de data). O HyperDX a incorpora à guia Line/Bar — escolha um groupBy numérico ou de data, selecione bar como formato e você terá um histograma. A faixa de histograma independente exibida no topo da visualização Search na Etapa C é renderizada automaticamente e não é um gráfico criado manualmente.

Principais diferenças de nomes de colunas em relação ao ECS do Kibana: request_path → RequestPath (bruto) ou RequestPage (somente caminho, recomendado para agrupamento); request_type → RequestType (método HTTP); status → StatusCode; geo.country_name → GeoCountry; user_agent_parsed.name → BrowserFamily; service / service.name → ServiceName; level → LogLevel ou SeverityText; event.severity → SeverityText; hostname → HostName; event.outcome → derivado de StatusCode (1xx–3xx sucesso / 4xx–5xx falha nos traces); transaction.duration.us (μs) → Duration (nanossegundos — divida por 1000 para μs).

Visão geral do tráfego web — 8 painéis

Filtre todos apenas para logs de acesso web: no AI Assistant ou no campo Where do gráfico, adicione RequestType != ''.

Integridade dos aplicativos — 5 painéis

Logs de aplicativos são as linhas nas quais o nível está definido, mas RequestType está vazio (o acesso web tem ambos). Filtro: LogLevel != '' AND RequestType = ''.

Visão geral da infraestrutura — 4 painéis

As linhas de infraestrutura (syslog) têm ServiceName começando por k8s- (o regex_parser promove o hostname do syslog a service.name). Filtro: ServiceName LIKE 'k8s-%'.

OTel Demo — Traces APM — 6 painéis

Os traces fluem para otel.otel_traces. Troque a fonte de dados do AI Assistant para Traces antes de executar estas instruções.

OTel Demo — Latência — 4 painéis

OTel Demo — Logs — 3 painéis

Os registros de log da OTel Demo chegam a otel.otel_logs_v2 a partir dos serviços da OTel Demo (frontend-proxy, cart, checkout etc.). Eles não têm RequestType nem LogLevel materializados — diferencie-os com ServiceName NOT LIKE 'k8s-%' AND RequestType = ''.

Dicas para quando o AI Assistant errar

1. Troque para o modo SQL no seletor Where. O AI Assistant gera um gráfico parcialmente preenchido; você pode editar qualquer campo manualmente. O seletor de esquema (botão Schema ao lado da fonte de dados) mostra todas as colunas e seus tipos.
2. Fixe o intervalo de tempo. O assistente respeita "for the past N hours / today / yesterday", mas usa o seletor de intervalo do gráfico por padrão se você omitir isso. Defina explicitamente o intervalo no seletor antes de salvar.
3. Colunas do tipo Map (LogAttributes, ResourceAttributes, SpanAttributes) costumam ser um obstáculo para o assistente. Se ele gerar WHERE process = 'kernel' em vez de WHERE LogAttributes['process'] = 'kernel', corrija no modo SQL.
4. Salve a versão funcional com Chart Name preenchido e adicione os gráficos a um dashboard do HyperDX para ter uma visualização de página única equivalente ao dashboard original do Kibana.

---

Próximos passos

• Service Map (barra lateral, beta) — visualiza o grafo de chamadas dos microsserviços da OTel Demo a partir de otel_traces. Nenhuma configuração além da fonte Traces é necessária.
• Alerts — defina alertas em qualquer pesquisa ou gráfico salvo. Você usará esse recurso na Etapa 8 do README principal; consulte README.md § Etapa 8 Opção A para ver os dois alertas recomendados (web-5xx-errors, heartbeat do serviço).
• Notebooks (prévia) — combine gráficos, consultas e comentários em Markdown em investigações compartilháveis.

Quando terminar a exploração, volte à Etapa 6 do README.md para verificar se o TTL está configurado.

---

Solução de problemas

A lista Sources fica vazia após salvar. O HyperDX armazena em cache as definições de fontes por sessão do navegador. Faça uma recarga forçada da guia (Cmd-Shift-R / Ctrl-Shift-R). Se continuar vazia, verifique Team Settings → Data → Server Connection — deve ser Default e apontar para o mesmo serviço do CH Cloud.

Search não mostra linhas, mas validate_migration.sh relata milhares.

• Verifique o seletor de intervalo — o padrão é "Last 15 minutes". Aumente para "Last 24 hours" se o coletor foi iniciado recentemente.
• Confirme que Default Select da fonte usa TimestampTime (não Timestamp). Sintoma: o histograma aparece, mas a tabela mostra "no rows".
• Confirme que Database da fonte é otel (não default).

O AI Assistant retorna "I couldn't translate that." O assistente é limitado ao esquema da fonte selecionada. Correções comuns:

• Troque a fonte de dados: perguntas sobre traces ("p95 latency") precisam da fonte Traces, não de log.
• Seja explícito quanto ao campo: count by ServiceName funciona melhor que count by service.