Monitoramento de traces no Node.js com ClickStack

Monitoramento de traces de aplicações Node.js com ClickStack

Em resumo

Capture traces distribuídos de aplicações Node.js no ClickStack com a instrumentação automática do OpenTelemetry. Inclui um dataset de demonstração e um dashboard pré-configurado.

​

Integração com uma aplicação Node.js existente

Esta seção explica como adicionar rastreamento distribuído à sua aplicação Node.js existente usando a instrumentação automática do OpenTelemetry.

Se quiser testar a integração antes de configurar seu próprio ambiente, você pode usar nossa configuração pré-configurada e os dados de exemplo na seção de dataset de demonstração.

Pré-requisitos

• Instância do ClickStack em execução, com endpoints OTLP acessíveis (portas 4317/4318)
• Aplicação Node.js existente (Node.js 14 ou superior)
• Gerenciador de pacotes npm ou yarn
• Hostname ou endereço IP do ClickStack

1. ​

   Instale e configure o OpenTelemetry

   Instale o pacote @hyperdx/node-opentelemetry e inicialize-o no início da sua aplicação. Consulte o guia do SDK do Node.js para ver as etapas detalhadas de instalação.

2. ​

   Obtenha a API key do ClickStack

   Uma API key para enviar traces ao endpoint OTLP do ClickStack.

   1. Abra o HyperDX na URL do seu ClickStack (por exemplo, http://localhost:8080)
   2. Crie uma conta ou faça login, se necessário
   3. Vá para Team Settings → API Keys
   4. Copie sua API key de ingestão
3. ​

   Execute sua aplicação

   Inicie sua aplicação Node.js com as variáveis de ambiente definidas:

   export CLICKSTACK_API_KEY=your-api-key-here
   export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
   
4. ​

   Gere algum tráfego

   Faça requisições à sua aplicação para gerar traces:

   # Requisições simples
   curl http://localhost:3000/
   curl http://localhost:3000/api/users
   curl http://localhost:3000/api/products
   
   # Simule carga
   for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done
   
5. ​

   Verifique os traces no HyperDX

   Depois de configurar, faça login no HyperDX e verifique se os traces estão chegando. Você deverá ver algo como isto. Se não vir traces, tente ajustar o intervalo de tempo:

   Clique em qualquer trace para ver a visualização detalhada com spans, duração e atributos:

​

Dataset de demonstração

Para usuários que querem testar o tracing em Node.js com o ClickStack antes de instrumentar suas aplicações de produção, disponibilizamos um dataset de exemplo com traces pré-gerados de aplicações Node.js com padrões de tráfego realistas.

1. ​

   Baixe o dataset de exemplo

   Baixe o arquivo de traces de exemplo:

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json
   
2. ​

   Inicie o ClickStack

   Se você ainda não tiver o ClickStack em execução, inicie-o com:

   docker run -d --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CLICKHOUSE_USER=default \
     -e CLICKHOUSE_PASSWORD= \
     clickhouse/clickstack-all-in-one:latest
   
3. ​

   Obtenha a API key do ClickStack

   Você precisará de uma API key para enviar traces ao endpoint OTLP do ClickStack.

   1. Abra o HyperDX na URL do seu ClickStack (por exemplo, http://localhost:8080)
   2. Crie uma conta ou faça login, se necessário
   3. Acesse Team Settings → API Keys
   4. Copie sua API key de ingestão

   Defina sua API key como uma variável de ambiente:

   export CLICKSTACK_API_KEY=your-api-key-here
   
4. ​

   Envie os traces para o ClickStack

   curl -X POST http://localhost:4318/v1/traces \
     -H "Content-Type: application/json" \
     -H "Authorization: $CLICKSTACK_API_KEY" \
     -d @nodejs-traces-sample.json
   

   Você deverá ver uma resposta como {"partialSuccess":{}}, indicando que os traces foram enviados com sucesso.

5. ​

   Verifique os traces no HyperDX

   1. Abra o HyperDX e faça login na sua conta (talvez seja necessário criar uma conta primeiro)
   2. Acesse a visualização Search e defina a fonte como Traces
   3. Defina o intervalo de tempo como 2025-10-25 13:00:00 - 2025-10-28 13:00:00

   Exibição de fuso horário

   O HyperDX exibe os timestamps no fuso horário local do seu navegador. Os dados de demonstração abrangem 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC). O intervalo de tempo mais amplo garante que você verá os traces de demonstração independentemente da sua localização. Depois de vê-los, você pode reduzir o intervalo para um período de 24 horas para ter visualizações mais claras.

​

Dashboards e visualização

Para ajudar você a começar a monitorar o desempenho de aplicações Node.js, fornecemos um dashboard pré-configurado com visualizações essenciais de traces.

1. ​

   a configuração do dashboard

2. ​

   Importe o dashboard pré-configurado

   1. Abra o HyperDX e acesse a seção Dashboards
   2. Clique em Import Dashboard no canto superior direito (no menu de reticências)

   3. Faça upload do arquivo nodejs-traces-dashboard.json e clique em Finish Import
3. ​

   O dashboard será criado com todas as visualizações pré-configuradas

   Para o dataset de demonstração, defina o intervalo de tempo como 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) (ajuste com base no seu fuso horário local). Por padrão, o dashboard importado não terá um intervalo de tempo especificado.

​

Solução de problemas

​

Traces de demonstração não aparecem via curl

Se você enviou traces via curl, mas não os vê no HyperDX, tente enviá-los uma segunda vez:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

Este é um problema conhecido que ocorre ao usar a abordagem de demo via curl e não afeta aplicações de produção instrumentadas.

​

Nenhum trace é exibido no HyperDX

Verifique se as variáveis de ambiente estão definidas:

echo $CLICKSTACK_API_KEY
# Deve exibir sua API key

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Deve exibir http://localhost:4318 ou o host do seu ClickStack

Verifique a conectividade da rede:

curl -v http://localhost:4318/v1/traces

Deve se conectar com sucesso ao endpoint OTLP.

Verifique os logs da aplicação: Procure por mensagens de inicialização do OpenTelemetry quando o app iniciar. O SDK do HyperDX deve exibir uma confirmação de que foi inicializado.

​

Próximas etapas

• Configure alertas para métricas críticas (taxas de erro, limites de latência)
• Crie dashboards adicionais para casos de uso específicos (monitoramento de APIs, eventos de segurança)

​

Colocando em produção

Este guia usa o SDK do HyperDX, que envia traces diretamente para o endpoint OTLP do ClickStack. Isso funciona bem para desenvolvimento, testes e implantações de produção de pequeno e médio porte. Para ambientes de produção maiores ou se você precisar de mais controle sobre os dados de telemetria, considere implantar seu próprio OpenTelemetry Collector como agente. Consulte Ingestão com OpenTelemetry para ver padrões de implantação em produção e exemplos de configuração do collector.