OpenTelemetry para Node.js — el cableado que de verdad funciona en producción

OpenTelemetry ha ganado en la práctica el debate del distributed tracing. Datadog, Honeycomb, Grafana Tempo, AWS X-Ray, Azure Monitor — todos ingestan OTLP directamente, lo que significa que instrumentar tu servicio con OpenTelemetry una vez te da portabilidad entre vendedores y herramientas.

El cableado estándar para un servicio Node.js está bien documentado pero lleno de pequeñas minas. Este es el setup que funciona en producción, incluyendo la auto-instrumentación que activamos y las ruidosas que desactivamos explícitamente.

Cableado al arranque del proceso

// otel.js — importado primero vía `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 },        // demasiado ruidoso
      '@opentelemetry/instrumentation-net': { enabled: false },       // demasiado ruidoso
    }),
  ],
}).start();

El flag --import es crítico — OpenTelemetry tiene que cargarse antes que el código de tu app para poder monkey-patchear los módulos correctos.

El artículo completo cubre:

• Por qué la auto-instrumentación es el punto de inicio correcto (no instrumentes cada span a mano)
• Sampling: head sampling, tail sampling, y el trade-off latencia-vs-presupuesto
• Propagación de contexto vía async_hooks y los pocos sitios donde se fuga
• Atributos de recurso que hacen las trazas buscables (pod k8s, versión de deploy, región)
• El patrón collector (un sidecar por host, exportación en batch)
• Exporters por vendedor — Datadog OTLP, Honeycomb, Grafana Tempo

Entregamos este cableado como parte de cada engagement Node.js gestionado.