> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitoramento de traces no Node.js com ClickStack
> Monitoramento de traces de aplicações Node.js com ClickStack
export const TrackedLink = ({href, eventName, children, ...rest}) => {
const handleClick = () => {
try {
if (typeof window !== "undefined" && window.galaxy && eventName) {
window.galaxy.track(eventName, {
interaction: "click"
});
}
} catch (e) {}
};
return
{children}
;
};
export const Image = ({img, alt, size}) => {
return
;
};
**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](#demo-dataset).
##### 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
#### 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](/pt-BR/clickstack/ingesting-data/sdks/nodejs#getting-started) 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](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:
```bash theme={null}
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:
```bash theme={null}
# 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:
## 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.
#### Baixe o dataset de exemplo
Baixe o arquivo de traces de exemplo:
```bash theme={null}
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:
```bash theme={null}
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](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:
```bash theme={null}
export CLICKSTACK_API_KEY=your-api-key-here
```
#### Envie os traces para o ClickStack
```bash theme={null}
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](http://localhost:8080/) 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.
#### Baixe a configuração do dashboard
#### 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**
#### 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:
```bash theme={null}
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:**
```bash theme={null}
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:**
```bash theme={null}
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](/pt-BR/clickstack/features/alerts) 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](/pt-BR/clickstack/ingesting-data/opentelemetry) para ver padrões de implantação em produção e exemplos de configuração do collector.