Monitoramento de traces no Node.js com ClickStack

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.

• 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

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.

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

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

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

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:

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.

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

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

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

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.

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

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.

Baixar a configuração do dashboard

Baixe o arquivo de configuração do dashboard.

Importar 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

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

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.

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.

• 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)

Este guia usa o SDK do HyperDX, que envia traces diretamente para o endpoint OTLP do ClickStack. Isso funciona bem em ambientes de 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 coletor.