OpenTelemetry para Node.js — o wiring que de fato funciona em produção

OpenTelemetry venceu, na prática, o debate do distributed tracing. Datadog, Honeycomb, Grafana Tempo, AWS X-Ray, Azure Monitor — todos ingerem OTLP diretamente, o que significa que instrumentar seu serviço com OpenTelemetry uma vez te dá portabilidade entre vendors e ferramentas.

O wiring padrão para um serviço Node.js está bem documentado mas cheio de pequenas minas. Este é o setup que funciona em produção, incluindo a auto-instrumentação que habilitamos e as barulhentas que desabilitamos explicitamente.

Wiring no início do processo

// otel.js — importado primeiro via `node --import ./otel.js app.js`
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
 
new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME,
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': { enabled: false },        // barulhento demais
      '@opentelemetry/instrumentation-net': { enabled: false },       // barulhento demais
    }),
  ],
}).start();

A flag --import é crítica — OpenTelemetry precisa carregar antes do código da sua app para poder fazer monkey-patch dos módulos certos.

O artigo completo cobre:

• Por que a auto-instrumentação é o ponto de partida certo (não instrumente cada span à mão)
• Sampling: head sampling, tail sampling, e o trade-off latência-vs-orçamento
• Propagação de contexto via async_hooks e os raros lugares onde vaza
• Resource attributes que tornam os traces pesquisáveis (pod k8s, versão de deploy, região)
• O padrão de collector (um sidecar por host, export em batch)
• Exporters por vendor — Datadog OTLP, Honeycomb, Grafana Tempo

Entregamos este wiring como parte de cada engagement Node.js gerenciado.