Demonstração do HackerNews Analyzer

TL;DRClone o HackerNews Analyzer, preencha o .env com seu endpoint OTLP e token e cole o prompt do agente. O backend não precisa importar o OpenTelemetry; o agente integra @hyperdx/node-opentelemetry na inicialização do processo.Tempo necessário: cerca de 10 minutos

O HackerNews Analyzer é um app Node.js que consulta o dataset HackerNews hospedado na demo pública do ClickHouse. Cada gráfico, tabela e caixa de busca corresponde a uma consulta real do ClickHouse. Portanto, cada interação produz um trace cujo span principal é a chamada HTTPS do backend ao ClickHouse. Esta é uma tarefa diferente da demo de replay de sessão, que instrumenta um app executado apenas no navegador usando um ClickStack local em Docker. Aqui, você conta com instrumentação automática do backend, spans de consultas do ClickHouse e replay de sessão no mesmo app.

Pré-requisitos

Node 18+ e npm
Um endpoint OTLP/HTTP do ClickStack e um token de ingestão:
- ClickHouse Cloud: abra o serviço e acesse ClickStack → Configure seu exporter do OpenTelemetry → Variáveis de ambiente. O protocolo é http/protobuf. O header é authorization=<ingestion token>, sem o prefixo Bearer.
- Collector local: use http://localhost:4318. Se o collector não estiver protegido, deixe authorization= em branco.

Clone o repositório

Clone o HackerNews Analyzer, instale as dependências e copie o modelo de arquivo de ambiente:

git clone https://github.com/ClickHouse/hn-news-analyzer.git
cd hn-news-analyzer
npm install
cp .env.example .env

Você preencherá o .env nas próximas etapas e, em seguida, instrumentará a aplicação a partir deste diretório.

Instrumente a aplicação

Execute a aplicação

No diretório hn-news-analyzer clonado, inicie o aplicativo. A fonte de dados do ClickHouse usa, por padrão, o cluster de demonstração público e somente leitura, portanto é executado sem nenhuma configuração adicional:

./run.sh

Abra http://localhost:5001. Você verá um seletor de ano, estatísticas resumidas, um gráfico de atividade, tabelas com os principais usuários e domínios e uma caixa de busca. Explore: alterne entre os anos e aprofunde-se nas histórias.

O aplicativo HackerNews Analyzer em execução localmente

Neste ponto, o aplicativo está em execução, mas ainda não está instrumentado. O ClickStack não exibe dados: está aguardando telemetria.

Configure o ambiente

Os SDKs leem as variáveis padrão do exporter do OpenTelemetry. Elas não estão codificadas diretamente no código-fonte. Abra o arquivo .env e defina:

OTEL_SERVICE_NAME=hn-analyzer-api
OTEL_EXPORTER_OTLP_ENDPOINT=<your-otlp-http-endpoint>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

OTEL_EXPORTER_OTLP_ENDPOINT é o endpoint OTLP/HTTP (porta 4318). OTEL_EXPORTER_OTLP_HEADERS é o cabeçalho de autorização, no formato authorization=<token>, sem o prefixo Bearer.Se o collector não exigir autenticação, deixe o token vazio (OTEL_EXPORTER_OTLP_HEADERS=authorization=). A variável ainda deve estar presente; o SDK ignora a inicialização se ela não estiver definida ou estiver totalmente vazia.O SDK do navegador reutiliza esses mesmos valores. O vite.config.ts incorpora o endpoint e o token ao pacote público durante a compilação; portanto, use um token de ingestão descartável, não um token de produção.

Instrumente a aplicação

Escolha um caminho. Todos os três levam ao mesmo aplicativo instrumentado.

Instrumentação com agente
Instrumentação manual
Usar uma branch pré-instrumentada

Com o repositório clonado e o .env preenchido, cole este prompt em um agente de programação nesse diretório para instrumentar o aplicativo.

A instrumentação tem três partes: instalar os SDKs, alterar o comando de inicialização e habilitar o SDK do navegador. Nada disso altera a regra de negócio do aplicativo.

Instale o SDK do Node

npm install @hyperdx/node-opentelemetry

Habilite o wrapper em run.sh

No final de run.sh, há duas linhas exec. Comente a linha simples de node e descomente a instrumentada:

 # ANTES: node simples, sem instrumentação:
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js

 # DEPOIS: mesmo código-fonte, envolvido por opentelemetry-instrument:
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js

Continue iniciando por scripts/entrypoint.js. Esse shim chama require('console'), permitindo que a captura do console envolva console.log. Apontar opentelemetry-instrument diretamente para dist/server/index.js envia traces, mas descarta os logs silenciosamente.

Habilite o SDK do navegador

npm install @hyperdx/browser

Em src/web/telemetry.ts, descomente a importação, o bloco HyperDX.init({...}) e HyperDX.addAction em recordAction():

-// import HyperDX from '@hyperdx/browser';
+import HyperDX from '@hyperdx/browser';

 export function initTelemetry(): void {
-  // HyperDX.init({
-  //   url: __OTLP_ENDPOINT__,
-  //   apiKey: __OTLP_AUTH_TOKEN__,
-  //   service: 'hn-analyzer-web',
-  //   tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
-  //   consoleCapture: true,
-  //   advancedNetworkCapture: true,
-  // });
+  HyperDX.init({
+    url: __OTLP_ENDPOINT__,
+    apiKey: __OTLP_AUTH_TOKEN__,
+    service: 'hn-analyzer-web',
+    tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
+    consoleCapture: true,
+    advancedNetworkCapture: true,
+  });
 }

__OTLP_ENDPOINT__ e __OTLP_AUTH_TOKEN__ são constantes de tempo de compilação injetadas por vite.config.ts a partir dos mesmos valores OTEL_EXPORTER_OTLP_* usados pelo backend.

O token de ingestão é incorporado ao pacote público do navegador e pode ser lido por qualquer pessoa que inspecione a aba Network. Use um token descartável.

Para pular a instrumentação e começar com um aplicativo já instrumentado, faça checkout da branch instrumented.

git checkout instrumented
npm install

Não execute ./reset.sh nessa branch, a menos que queira remover os SDKs.

Gere tráfego e visualize a telemetria

Reinicie a aplicação para que o novo comando de inicialização e o bundle do navegador recém-gerado entrem em vigor:

# Ctrl-C the previous run, then:
./run.sh

Confirme que o banner de inicialização exibe três linhas “Verificação de integridade aprovada” para /v1/traces, /v1/metrics e /v1/logs. Recarregue a aba do navegador para que o Vite sirva o pacote atualizado, depois alterne entre os anos e clique nas histórias para gerar tráfego.Abra a UI do ClickStack:

Vá para Busca e filtre os últimos 5 minutos. Os logs de hn-analyzer-api começam a ser exibidos.

Busca do ClickStack mostrando logs de hn-analyzer-api dos últimos cinco minutos

Clique em uma solicitação e percorra o trace até a origem. Você verá o span do handler do Express, um span HTTP filho apontando para sql-clickhouse.clickhouse.com com duração real de rede e registros console.log correlacionados no mesmo trace.

Trace do ClickStack com um span de handler do Express e um span HTTP filho para o ClickHouse

Abra Reprodução de sessão para reproduzir um vídeo de uma sessão do navegador que permite avançar e retroceder, sincronizado com a linha do tempo do trace.

Reprodução de sessão do ClickStack sincronizada com a linha do tempo do trace

Logs, métricas, traces e reproduções de sessão são exibidos na mesma UI, compartilham a mesma linguagem de consulta e são correlacionados automaticamente.

Saiba mais

HackerNews Analyzer: o repositório de demonstração instrumentado por este guia.

replay de sessão: visão geral da funcionalidade, opções de SDK e controles de privacidade.
replay de sessão Demo: uma demonstração completa com uma instância local do ClickStack.
ClickStack Primeiros passos: implante o ClickStack e faça a ingestão dos seus primeiros dados.
Todos os datasets de exemplo: outros datasets de exemplo e guias.

Primeiros passos

Recursos

Gerenciamento do ClickStack

Guias

Parceiros de integração

Pré-requisitos

Clone o repositório

Instrumente a aplicação

Instale o SDK do Node

Habilite o wrapper em run.sh

Habilite o SDK do navegador

Saiba mais

​Pré-requisitos

​Clone o repositório

​Instrumente a aplicação

​Instale o SDK do Node

​Habilite o wrapper em run.sh

​Habilite o SDK do navegador

​Saiba mais

Pré-requisitos

Clone o repositório

Instrumente a aplicação

Instale o SDK do Node

Habilite o wrapper em run.sh

Habilite o SDK do navegador

Saiba mais