SDK de Node para OpenTelemetry

Q: ¿Qué paquetes instalar?

@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, exportadores OTLP, @opentelemetry/api para spans manuales.

Q: ¿Jaeger local?

Ejecuta el colector con el receptor OTLP en 4318. Apunta OTEL_EXPORTER_OTLP_ENDPOINT allí.

Q: ¿NestJS?

opentelemetry-instrumentation-nestjs-core o spans manuales en interceptores. Aún así, carga el SDK primero en main.ts.

Q: ¿Workers de BullMQ?

service.name separado (por ejemplo, orders-worker). Inicia el SDK en la entrada del worker de la misma manera que HTTP.

Instrumenta servicios Node.js 24 con el SDK de Node para OpenTelemetry: instrumenta automáticamente HTTP y controladores de bases de datos, exporta trazas OTLP y añade spans manuales para la lógica de negocio.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

// src/instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { Resource } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({ [ATTR_SERVICE_NAME]: "orders-api" }),
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

// src/main.ts
import "./instrumentation.js";
import { startServer } from "./server.js";
startServer();

Cuándo usarlo:

Necesitas trazas distribuidas entre microservicios.
Estás depurando la latencia p99 con vistas de cascada en Honeycomb/Datadog/Jaeger.
Estás estandarizando la instrumentación antes de elegir un proveedor de APM.
Estás reemplazando la temporización ad-hoc de console.time en producción.

Ejemplo de trabajo

// instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { Resource } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME ?? "orders-api",
    [ATTR_SERVICE_VERSION]: process.env.APP_VERSION ?? "0.0.0",
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
    }),
    exportIntervalMillis: 60_000,
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      "@opentelemetry/instrumentation-fs": { enabled: false },
    }),
  ],
});
 
sdk.start();
 
process.on("SIGTERM", () => sdk.shutdown());

// server.ts
import express from "express";
import { trace } from "@opentelemetry/api";
 
const app = express();
const tracer = trace.getTracer("orders");
 
app.get("/orders/:id", async (req, res) => {
  await tracer.startActiveSpan("loadOrder", async (span) => {
    span.setAttribute("order.id", req.params.id);
    const order = await db.findOrder(req.params.id);
    res.json(order);
  });
});
 
app.listen(3000);

Lo que esto demuestra:

Los atributos de recurso identifican el servicio en el backend de trazas.
Puntos finales OTLP separados para trazas y métricas (común en colectores).
Instrumentación de FS deshabilitada para reducir el ruido.
sdk.shutdown() elegante en SIGTERM vacía los spans pendientes.

Análisis profundo

Cómo funciona

El SDK registra tracers y meters con la API global @opentelemetry/api.
La instrumentación automática parchea http, https, fetch, pg, ioredis, etc. en el momento de la importación.
Los spans se exportan a través de OTLP (OpenTelemetry Protocol) a un colector o agente.
El encabezado traceparent de W3C propaga el contexto a las llamadas HTTP posteriores.

Variables de entorno

Variable	Propósito
`OTEL_SERVICE_NAME`	Atributo de recurso `service.name`
`OTEL_EXPORTER_OTLP_ENDPOINT`	URL base de OTLP
`OTEL_TRACES_SAMPLER`	`parentbased_traceidratio` etc.
`OTEL_NODE_RESOURCE_DETECTORS`	cloud, container, host

Orden de carga

// CORRECTO
import "./instrumentation";
import express from "express";
 
// INCORRECTO - spans HTTP perdidos
import express from "express";
import "./instrumentation";

NestJS: import "./instrumentation" en la primera línea de main.ts.
tsx dev: node --import ./src/instrumentation.ts src/main.ts.

Muestreo

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Muestreo inicial del 10% para servicios de alto RPS: ajusta el costo frente a la cobertura.
Siempre muestrea errores si el proveedor admite el muestreo basado en la cola.

Errores comunes

Instrumentación después de las importaciones - pérdida de spans HTTP. Solución: instrumentación en la primera línea.
Doble instrumentación - conflicto entre el agente del proveedor y el SDK de OTel. Solución: elige una ruta por señal.
Atributos de span de alta cardinalidad - userId en cada span dispara el costo. Solución: solo atributos de baja cardinalidad.
Ruido de spans de FS - miles de spans de readFile. Solución: deshabilita @opentelemetry/instrumentation-fs.
No hay apagado en SIGTERM - spans perdidos en el despliegue. Solución: sdk.shutdown() en el manejador de terminación.
Desarrollo sin colector - errores de exportación inundan los registros. Solución: OTEL_TRACES_EXPORTER=none localmente o ejecuta Jaeger docker.

Alternativas

Alternativa	Usar cuándo	No usar cuándo
SDK de OTel Node	Neutral al proveedor, multi-señal	Un agente de un solo proveedor sin configuración es suficiente
Datadog dd-trace	Todo en Datadog APM	Quieres portabilidad OTLP
Agente de New Relic	Stack solo de NR	OTLP multi-backend
Solo registros manuales	Herramienta interna pequeña	APIs de SLA de producción

Preguntas frecuentes

¿Qué paquetes instalar?

@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, exportadores OTLP, @opentelemetry/api para spans manuales.

¿Funciona con Fastify?

Sí. La instrumentación automática de HTTP cubre el servidor subyacente de Fastify. Carga la instrumentación antes de la importación de Fastify.

¿Señales de logs en OTel?

El SDK de logs de OTel está evolucionando. La mayoría de los equipos usan Pino stdout + inyección de trace_id para la correlación de logs y trazas.

¿Instrumentación de Prisma?

Instrumentación de la comunidad o spans manuales alrededor de las consultas. Habilita @opentelemetry/instrumentation-pg para controladores SQL puros.

¿Jaeger local?

Ejecuta el colector con el receptor OTLP en 4318. Apunta OTEL_EXPORTER_OTLP_ENDPOINT allí.

¿NestJS?

opentelemetry-instrumentation-nestjs-core o spans manuales en interceptores. Aún así, carga el SDK primero en main.ts.

¿Sobrecarga de rendimiento?

Típicamente un bajo porcentaje de un solo dígito con muestreo. Perfila con y sin en staging a pico de RPS.

¿Workers de BullMQ?

service.name separado (por ejemplo, orders-worker). Inicia el SDK en la entrada del worker de la misma manera que HTTP.

Relacionado

Conceptos básicos de observabilidad - introducción a los tres pilares
Métricas importantes - métricas RED
Herramientas APM - patrones de Datadog, Honeycomb
IDs de correlación de solicitudes - encabezado traceparent

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

// src/instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { Resource } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({ [ATTR_SERVICE_NAME]: "orders-api" }),
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

// src/main.ts
import "./instrumentation.js";
import { startServer } from "./server.js";
startServer();

Cuándo usarlo:

Necesitas trazas distribuidas entre microservicios.
Estás depurando la latencia p99 con vistas de cascada en Honeycomb/Datadog/Jaeger.
Estás estandarizando la instrumentación antes de elegir un proveedor de APM.
Estás reemplazando la temporización ad-hoc de console.time en producción.

Ejemplo de trabajo

// instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { Resource } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME ?? "orders-api",
    [ATTR_SERVICE_VERSION]: process.env.APP_VERSION ?? "0.0.0",
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
    }),
    exportIntervalMillis: 60_000,
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      "@opentelemetry/instrumentation-fs": { enabled: false },
    }),
  ],
});
 
sdk.start();
 
process.on("SIGTERM", () => sdk.shutdown());

// server.ts
import express from "express";
import { trace } from "@opentelemetry/api";
 
const app = express();
const tracer = trace.getTracer("orders");
 
app.get("/orders/:id", async (req, res) => {
  await tracer.startActiveSpan("loadOrder", async (span) => {
    span.setAttribute("order.id", req.params.id);
    const order = await db.findOrder(req.params.id);
    res.json(order);
  });
});
 
app.listen(3000);

Lo que esto demuestra:

Los atributos de recurso identifican el servicio en el backend de trazas.
Puntos finales OTLP separados para trazas y métricas (común en colectores).
Instrumentación de FS deshabilitada para reducir el ruido.
sdk.shutdown() elegante en SIGTERM vacía los spans pendientes.

Análisis profundo

Cómo funciona

El SDK registra tracers y meters con la API global @opentelemetry/api.
La instrumentación automática parchea http, https, fetch, pg, ioredis, etc. en el momento de la importación.
Los spans se exportan a través de OTLP (OpenTelemetry Protocol) a un colector o agente.
El encabezado traceparent de W3C propaga el contexto a las llamadas HTTP posteriores.

Variables de entorno

Variable	Propósito
`OTEL_SERVICE_NAME`	Atributo de recurso `service.name`
`OTEL_EXPORTER_OTLP_ENDPOINT`	URL base de OTLP
`OTEL_TRACES_SAMPLER`	`parentbased_traceidratio` etc.
`OTEL_NODE_RESOURCE_DETECTORS`	cloud, container, host

Orden de carga

// CORRECTO
import "./instrumentation";
import express from "express";
 
// INCORRECTO - spans HTTP perdidos
import express from "express";
import "./instrumentation";

NestJS: import "./instrumentation" en la primera línea de main.ts.
tsx dev: node --import ./src/instrumentation.ts src/main.ts.

Muestreo

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Muestreo inicial del 10% para servicios de alto RPS: ajusta el costo frente a la cobertura.
Siempre muestrea errores si el proveedor admite el muestreo basado en la cola.

Errores comunes

Instrumentación después de las importaciones - pérdida de spans HTTP. Solución: instrumentación en la primera línea.
Doble instrumentación - conflicto entre el agente del proveedor y el SDK de OTel. Solución: elige una ruta por señal.
Atributos de span de alta cardinalidad - userId en cada span dispara el costo. Solución: solo atributos de baja cardinalidad.
Ruido de spans de FS - miles de spans de readFile. Solución: deshabilita @opentelemetry/instrumentation-fs.
No hay apagado en SIGTERM - spans perdidos en el despliegue. Solución: sdk.shutdown() en el manejador de terminación.
Desarrollo sin colector - errores de exportación inundan los registros. Solución: OTEL_TRACES_EXPORTER=none localmente o ejecuta Jaeger docker.

Alternativas

Alternativa	Usar cuándo	No usar cuándo
SDK de OTel Node	Neutral al proveedor, multi-señal	Un agente de un solo proveedor sin configuración es suficiente
Datadog dd-trace	Todo en Datadog APM	Quieres portabilidad OTLP
Agente de New Relic	Stack solo de NR	OTLP multi-backend
Solo registros manuales	Herramienta interna pequeña	APIs de SLA de producción

Preguntas frecuentes

¿Qué paquetes instalar?

@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, exportadores OTLP, @opentelemetry/api para spans manuales.

¿Funciona con Fastify?

Sí. La instrumentación automática de HTTP cubre el servidor subyacente de Fastify. Carga la instrumentación antes de la importación de Fastify.

¿Señales de logs en OTel?

El SDK de logs de OTel está evolucionando. La mayoría de los equipos usan Pino stdout + inyección de trace_id para la correlación de logs y trazas.

¿Instrumentación de Prisma?

Instrumentación de la comunidad o spans manuales alrededor de las consultas. Habilita @opentelemetry/instrumentation-pg para controladores SQL puros.

¿Jaeger local?

Ejecuta el colector con el receptor OTLP en 4318. Apunta OTEL_EXPORTER_OTLP_ENDPOINT allí.

¿NestJS?

opentelemetry-instrumentation-nestjs-core o spans manuales en interceptores. Aún así, carga el SDK primero en main.ts.

¿Sobrecarga de rendimiento?

Típicamente un bajo porcentaje de un solo dígito con muestreo. Perfila con y sin en staging a pico de RPS.

¿Workers de BullMQ?

service.name separado (por ejemplo, orders-worker). Inicia el SDK en la entrada del worker de la misma manera que HTTP.

Relacionado

Conceptos básicos de observabilidad - introducción a los tres pilares
Métricas importantes - métricas RED
Herramientas APM - patrones de Datadog, Honeycomb
IDs de correlación de solicitudes - encabezado traceparent

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

SDK de Node para OpenTelemetry

Buscar en la documentación

SDK de Node para OpenTelemetry