Logs mostram eventos individuais e métricas mostram tendências, mas nem sempre revelam como o runtime distribuiu trabalho entre JavaScript, garbage collection, operações assíncronas e chamadas nativas. O recurso de Trace Events no Node.js gera uma linha do tempo detalhada que pode ser aberta em ferramentas compatíveis com o formato de tracing do Chrome.
Essa linha do tempo ajuda a investigar pausas, inicialização lenta, atividade do V8, processamento assíncrono e comportamento do event loop. Como o volume pode ser grande, trace events devem ser ativados por períodos curtos e com categorias específicas.
Neste guia, você aprenderá a habilitar tracing pela linha de comando, escolher categorias, definir o arquivo de saída, interpretar eventos, correlacionar PIDs e threads, usar o módulo node:trace_events, coletar dados em containers e evitar overhead ou exposição de informações sensíveis.
O que são Trace Events?
Trace events são registros estruturados com timestamp, categoria, fase, processo, thread e argumentos. Juntos, formam uma linha do tempo que ferramentas de visualização conseguem agrupar e exibir como faixas de execução.
A documentação oficial de Trace Events no Node.js descreve opções, categorias e APIs. O formato segue conceitos do projeto de tracing do Chromium.
Para medidas pontuais no código, consulte Performance Hooks no Node.js. Para perfis de CPU e heap, veja Inspector no Node.js.
Ativando pela linha de comando
node --trace-events-enabled server.jsO processo grava um arquivo de trace no diretório atual. O nome padrão depende da versão e da configuração. Em produção, prefira definir explicitamente um padrão para evitar colisões.
Escolhendo categorias
node \
--trace-events-enabled \
--trace-event-categories node,v8 \
server.jsCategorias controlam quais eventos entram no arquivo. Ativar tudo aumenta overhead e volume. Comece com o conjunto mínimo que responde à pergunta investigada.
Categorias comuns
node: eventos gerais do runtime;node.async_hooks: ciclo de recursos assíncronos;node.perf: eventos de desempenho;v8: atividade do motor JavaScript;node.bootstrap: inicialização;node.fs.sync: operações síncronas de arquivo, quando disponíveis.
Os nomes e a estabilidade podem variar. Consulte a documentação da versão instalada e teste antes de automatizar análises.
Definindo o padrão do arquivo
node \
--trace-events-enabled \
--trace-event-file-pattern='trace-${pid}-${rotation}.json' \
server.jsO suporte a placeholders depende da versão. Use nomes que diferenciem PID, instância e rotação. Em containers, grave em volume temporário com espaço limitado.
Abrindo o arquivo
Arquivos no formato de trace podem ser importados em visualizadores compatíveis. Em versões do Chrome que ainda oferecem a página apropriada, use a interface de tracing. Ferramentas de performance também podem importar JSON de trace.
Antes de enviar um arquivo para terceiros, revise o conteúdo. Nomes de funções, caminhos, URLs e argumentos podem revelar detalhes internos.
Estrutura de um evento
{
"name": "example",
"cat": "node",
"ph": "X",
"ts": 123456789,
"dur": 250,
"pid": 1200,
"tid": 1200,
"args": {}
}Campos importantes incluem:
name: nome do evento;cat: categoria;ph: fase ou tipo;ts: timestamp;dur: duração, quando aplicável;pid: processo;tid: thread;args: dados adicionais.
Não compare timestamps absolutos de máquinas diferentes sem sincronização. O valor principal costuma ser a relação temporal dentro do mesmo trace.
Interpretando a linha do tempo
Procure intervalos longos, atividade repetida e períodos em que a thread principal fica ocupada. Compare com a carga aplicada e com métricas de latência.
Um intervalo longo de JavaScript pode indicar função síncrona pesada. Pausas do V8 podem estar relacionadas ao garbage collector. Atividade assíncrona numerosa pode apontar criação excessiva de Promises, timers ou sockets.
Event loop bloqueado
Trace events ajudam a visualizar blocos contínuos de trabalho, mas não substituem métricas de atraso. Use também Event Loop no Node.js para entender fases e monitorEventLoopDelay() para acompanhar o problema continuamente.
Ao encontrar uma região suspeita, capture um CPU profile com o Inspector para identificar funções específicas.
Inicialização lenta
node \
--trace-events-enabled \
--trace-event-categories node.bootstrap,v8 \
server.jsEsse trace pode mostrar carregamento de módulos, compilação e bootstrap. Compare uma execução fria com outra após cache do sistema operacional. Dependências grandes, imports desnecessários e configuração síncrona podem aumentar o tempo.
Operações síncronas
APIs síncronas de filesystem, compressão ou criptografia podem bloquear a thread principal. Quando categorias específicas estiverem disponíveis, traces ajudam a localizar essas chamadas. Revise também o código e use ferramentas estáticas.
O guia de File System no Node.js apresenta alternativas assíncronas.
Trace Events e Async Hooks
Categorias ligadas a async hooks podem registrar criação e execução de recursos. O volume cresce rapidamente em aplicações com muitas Promises. Ative por poucos segundos e sob carga controlada.
Para compreender os identificadores e a causalidade, consulte Async Hooks no Node.js.
Usando node:trace_events
const traceEvents = require('node:trace_events');
const tracing = traceEvents.createTracing({
categories: [
'node.perf',
'node.async_hooks'
]
});
tracing.enable();A API permite ativar categorias em tempo de execução. Isso é útil para uma janela de diagnóstico controlada.
Desativando depois da coleta
setTimeout(() => {
tracing.disable();
}, 15000).unref();Defina duração máxima. Um endpoint administrativo que liga tracing e esquece de desligar pode gerar arquivos enormes e overhead prolongado.
Verificando categorias habilitadas
console.log(traceEvents.getEnabledCategories());O resultado ajuda em diagnósticos, mas pode mudar enquanto diferentes componentes ativam e desativam tracing. Não use como mecanismo de autorização.
Janela acionada por condição
Uma estratégia é ativar tracing quando a latência ultrapassa um limite, mantendo uma janela curta:
let tracing;
let active = false;
function startDiagnosticWindow() {
if (active) return;
active = true;
tracing = traceEvents.createTracing({
categories: ['node.perf', 'v8']
});
tracing.enable();
setTimeout(() => {
tracing.disable();
active = false;
}, 10000).unref();
}Implemente cooldown para evitar ativações repetidas. Registre o motivo e a instância onde o trace foi coletado.
Containers
Em Docker ou Kubernetes, grave o arquivo em um volume com limite. Não use a camada gravável do container para capturas longas. Após coletar, copie o arquivo e remova o volume temporário.
Associe o trace ao nome do pod, container, versão e horário. Esses metadados ajudam a comparar com logs e métricas.
Cluster
Cada worker do Cluster no Node.js é um processo separado. Os arquivos precisam de PID no nome para evitar sobrescrita. Um trace de apenas um worker pode não representar o serviço inteiro.
Escolha um worker afetado ou colete uma amostra coordenada. Cuidado com o volume multiplicado pelo número de processos.
Worker Threads
Eventos podem incluir diferentes threads. Use tid para distinguir a thread principal e workers. Uma tarefa pesada em Worker Thread não bloqueia a principal, mas ainda pode competir por CPU.
Veja Worker Threads no Node.js para pools e limites.
Correlacionando com logs
Registre horário de início, duração e identificador da captura:
logger.info('trace_started', {
traceId,
startedAt: new Date().toISOString(),
pid: process.pid,
categories
});Use relógios consistentes e não tente inserir payloads sensíveis no trace. Logs estruturados ajudam a localizar requisições no mesmo intervalo.
Correlacionando com OpenTelemetry
Trace events e distributed tracing têm finalidades diferentes. OpenTelemetry conecta operações entre serviços; trace events mostram detalhes internos do runtime. Use OpenTelemetry no Node.js para encontrar a instância e o período problemático, depois capture um trace local curto.
Overhead
O custo depende das categorias, da taxa de eventos e do armazenamento. Medir tudo em uma aplicação movimentada pode afetar justamente a latência investigada.
Faça benchmark com e sem tracing. Prefira categorias específicas, janela curta e ambiente de reprodução. Em produção, retire uma réplica do balanceador quando possível.
Tamanho dos arquivos
Defina orçamento de disco e política de remoção. Comprima depois da captura, não durante um caminho crítico. Arquivos incompletos podem ocorrer se o processo for encerrado abruptamente.
Monitore espaço livre e interrompa a coleta antes de atingir limites do host.
Segurança e privacidade
Traces podem revelar:
- caminhos de arquivos;
- nomes de módulos e funções;
- URLs internas;
- identificadores de recursos;
- arquitetura da aplicação;
- argumentos de execução.
Armazene com acesso restrito, criptografe no transporte e apague após a análise. Não disponibilize capturas em tickets públicos sem revisão.
Automação segura
Se houver um endpoint administrativo para iniciar captura, exija autenticação forte, autorização específica, prazo máximo, cooldown e auditoria. Nunca permita categorias arbitrárias ou caminhos de arquivo fornecidos pelo cliente.
Testando a configuração
Em homologação, execute uma carga conhecida e confirme que:
- o arquivo é criado;
- o nome não colide;
- as categorias esperadas aparecem;
- o arquivo abre na ferramenta;
- a coleta termina no prazo;
- o disco não cresce sem limite;
- dados sensíveis não são incluídos.
Erros comuns
- Ativar todas as categorias: volume e overhead ficam altos.
- Coletar por horas: arquivos ocupam o disco.
- Usar o mesmo nome em Cluster: workers sobrescrevem capturas.
- Analisar sem carga: o problema real não aparece.
- Confundir tracing interno com distributed tracing: perguntas diferentes exigem ferramentas diferentes.
- Compartilhar o arquivo sem revisão: detalhes internos vazam.
- Otimizar apenas pela imagem: mudanças precisam ser validadas por métricas.
Boas práticas
- Comece com uma pergunta específica.
- Ative categorias mínimas.
- Use janelas curtas.
- Inclua PID e instância no nome.
- Controle espaço em disco.
- Correlacione com logs e métricas.
- Compare com CPU profiles quando necessário.
- Proteja os arquivos.
- Teste overhead.
- Remova capturas antigas.
Conclusão
O recurso de Trace Events no Node.js fornece uma linha do tempo detalhada do runtime e ajuda a investigar inicialização, event loop, V8, recursos assíncronos e trabalho distribuído entre processos ou threads.
O valor depende de uma coleta disciplinada. Categorias específicas, duração curta, correlação com métricas e proteção dos arquivos reduzem custo e risco. Usado junto com Performance Hooks, Inspector, logs e OpenTelemetry, o tracing interno transforma sintomas vagos em evidências temporais que orientam correções mais precisas.
