Distributed Tracing no Node.js acompanha uma requisição enquanto ela atravessa gateway, serviços, banco, filas e integrações externas. Cada etapa gera um span; todos compartilham o mesmo trace ID.
Sem tracing, uma falha distribuída aparece como logs isolados. Com contexto propagado, é possível visualizar a árvore de chamadas, latência por componente e ponto exato do erro.
Trace, span e contexto
- trace: jornada completa da operação;
- span: uma unidade de trabalho;
- trace ID: identifica a jornada;
- span ID: identifica a etapa;
- parent: relaciona spans.
Propagação W3C
O header traceparent transporta trace ID, parent span e flag de sampling. Não invente um formato próprio quando o padrão W3C atende ao caso.
Instrumentação automática
OpenTelemetry pode instrumentar HTTP, Undici, Express e bibliotecas de banco. Carregue a instrumentação antes dos módulos da aplicação para que hooks sejam aplicados corretamente.
Spans personalizados
const tracer = trace.getTracer('orders');
await tracer.startActiveSpan('calculate-order', async (span) => {
try {
span.setAttribute('order.type', 'standard');
await calculateOrder();
} catch (error) {
span.recordException(error);
span.setStatus({ code: SpanStatusCode.ERROR });
throw error;
} finally {
span.end();
}
});Não use dados de alta cardinalidade
Evite IDs de usuário, e-mail ou URL completa como atributos usados para agregação. Atributos podem conter contexto técnico, mas dados sensíveis devem ser redigidos.
Mensageria
Em filas, injete o contexto nos headers da mensagem e extraia no consumidor. O processamento assíncrono pode criar relação parent-child ou span link, dependendo da semântica.
Consulte RabbitMQ no Node.js e Kafka no Node.js.
Banco de dados
Registre sistema, operação e nome lógico do banco. Não coloque SQL completo com parâmetros sensíveis. Spans devem ajudar a identificar queries lentas sem vazar conteúdo.
Logs correlacionados
Inclua trace ID e span ID nos logs. Assim, um alerta de erro pode levar diretamente ao trace correspondente. Veja Pino no Node.js.
Sampling
Respeite a decisão do parent e preserve traces relevantes. Consulte Trace Sampling no Node.js.
Latência
O trace mostra onde o tempo foi gasto: fila, DNS, conexão, serviço ou banco. Combine com deadlines para evitar que uma etapa consuma todo o prazo. Veja Timeout Budget no Node.js.
Exportação OTLP
Envie spans ao OpenTelemetry Collector por OTLP. O collector pode aplicar batch, retry, sampling e exportar para diferentes backends sem acoplar a aplicação a um fornecedor.
Resource attributes
Configure nome do serviço, versão e ambiente. Esses atributos permitem comparar deploys e localizar regressões.
Observabilidade do pipeline
Monitore filas do exporter, falhas de exportação, spans descartados, latência do collector e tamanho dos batches. Tracing não deve derrubar a aplicação quando o backend estiver indisponível.
Erros comuns
- inicializar instrumentação tarde;
- não propagar contexto em filas;
- criar span para cada detalhe irrelevante;
- registrar payloads sensíveis;
- não encerrar spans;
- exportar sincronicamente por requisição;
- usar tracing sem logs e métricas correlacionados.
Conclusão
Distributed Tracing no Node.js revela a jornada completa de uma operação e permite atribuir latência e falhas ao componente correto. Use propagação W3C, instrumentação automática, spans de negócio seletivos e exportação em batch.
Consulte OpenTelemetry no Node.js, a documentação JavaScript do OpenTelemetry e a especificação W3C Trace Context.
