Conceptos Básicos de Observabilidad

8 ejemplos para que empieces con la Observabilidad para backends de Node.js: 6 básicos y 2 intermedios.

Prerrequisitos

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

Fija Node 24.18.0 y carga el SDK de OTel antes de otras importaciones en los puntos de entrada de producción.

Ejemplos Básicos

1. Tres Pilares en Una Solicitud

Los registros, las métricas y las trazas describen el mismo incidente desde diferentes ángulos.

// Registro (Pino)
logger.info({ requestId, statusCode: 200, durationMs: 45 }, "request_complete");
 
// Métrica (contador)
requestCounter.add(1, { method: "GET", route: "/users", status: "200" });
 
// Traza (atributo de span)
span.setAttribute("http.status_code", 200);

• Registros: eventos discretos con contexto, excelentes para depurar un fallo.
• Métricas: agregados a lo largo del tiempo, excelentes para SLOs y alertas.
• Trazas: desglose de latencia entre servicios, excelentes para solicitudes lentas.

Relacionado: Métricas Importantes - método RED

2. Endpoints de Salud vs Preparación

La vivacidad y la preparación sirven para diferentes sondas del orquestador.

app.get("/health", (_req, res) => res.json({ ok: true }));
 
app.get("/ready", async (_req, res) => {
  const dbOk = await db.ping();
  res.status(dbOk ? 200 : 503).json({ ready: dbOk });
});

• /health - proceso activo (vivacidad). Sin comprobaciones de dependencia.
• /ready - puede servir tráfico (preparación). Falla cuando la base de datos está inactiva.
• No registres fallos de preparación en error en cada sonda de kube; muestrea o usa métricas.

Relacionado: Conceptos Básicos de Resiliencia - falla rápido al inicio

3. Esquema de Métricas RED

Tasa, Errores, Duración - métricas mínimas de servicio HTTP.

import { metrics } from "@opentelemetry/api";
 
const meter = metrics.getMeter("orders-api");
const requestDuration = meter.createHistogram("http.server.duration", { unit: "ms" });
const requestCount = meter.createCounter("http.server.requests");
 
function recordRequest(method: string, route: string, status: number, ms: number) {
  requestCount.add(1, { method, route, status: String(status) });
  requestDuration.record(ms, { method, route, status: String(status) });
}

• Tasa - contador http.server.requests.
• Errores - mismo contador filtrado por status=5xx.
• Duración - histograma para p50/p95/p99 en Prometheus o Datadog.

Relacionado: SLOs y Presupuestos de Errores - SLO a partir de histogramas

4. Registro Estructurado con trace_id

Correlaciona los registros con las trazas en las UIs de APM.

import { trace } from "@opentelemetry/api";
 
const span = trace.getActiveSpan();
const traceId = span?.spanContext().traceId;
 
logger.info({ trace_id: traceId, event: "payment_captured" }, "payment ok");

• Muchas herramientas de APM vinculan líneas de registro a la cascada de trazas por trace_id.
• Usa un nombre de campo consistente (trace_id) en todos los servicios.
• Pino mixin puede inyectar trace_id automáticamente.

Relacionado: IDs de Correlación de Solicitudes - requestId vs trace_id

5. Contador para Eventos de Negocio

Las métricas no son solo HTTP, rastrea los eventos de dominio.

const ordersCreated = meter.createCounter("orders.created");
ordersCreated.add(1, { plan: "pro", region: "eu" });

• Los contadores de negocio impulsan los paneles de productos, no solo las operaciones.
• Solo etiquetas de baja cardinalidad, no userId en cada métrica.
• Combina con registros para la depuración de pedidos individuales.

Relacionado: Conceptos Básicos de Registro - nomenclatura de campos de eventos

6. Span para Instrumentación Manual

La instrumentación automática omite los límites de tu lógica de negocio.

import { trace } from "@opentelemetry/api";
 
const tracer = trace.getTracer("billing");
 
async function capturePayment(orderId: string) {
  return tracer.startActiveSpan("capturePayment", async (span) => {
    span.setAttribute("order.id", orderId);
    try {
      return await stripeCapture(orderId);
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: 2 });
      throw err;
    } finally {
      span.end();
    }
  });
}

• Nombra los spans según las operaciones (capturePayment), no según los detalles internos de la función.
• recordException adjunta el error a la traza para el seguimiento de errores de APM.
• Finaliza los spans en finally: evita spans filtrados en un retorno temprano.

Relacionado: SDK de OpenTelemetry Node - configuración del SDK

Ejemplos Intermedios

7. Arranque Mínimo del SDK de OTel

Carga la instrumentación antes de las importaciones de Express/Fastify.

// src/instrumentation.ts - importa primero en main.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318/v1/traces",
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();

• instrumentation.ts debe cargarse antes de import express en el archivo de entrada.
• El exportador OTLP HTTP envía a un sidecar de colector (4318) o a un agente SaaS.
• La instrumentación automática cubre HTTP, fetch y controladores de bases de datos comunes.

Relacionado: SDK de OpenTelemetry Node - configuración completa

8. Alerta sobre Síntomas, No sobre Registros

Alerta sobre el consumo de SLO, no sobre cada pila de llamadas.

# Regla de pseudo-alerta
alert: HighErrorRate
expr: rate(http_server_requests{status=~"5.."}[5m]) / rate(http_server_requests[5m]) > 0.05
for: 10m

• Síntoma: tasa elevada de 5xx durante 5 minutos.
• No: una sola línea de registro ERROR de un reinicio de pod.
• Vincula las alertas a SLOs y Presupuestos de Errores.

Relacionado: Mejores Prácticas de Observabilidad - reglas de alerta

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