Node.js
Observabilidad en servicios Node.js mediante logs estructurados, métricas, tracing, correlation IDs, contexto asíncrono y alertas orientadas a síntomas reales.
Observabilidad permite explicar el estado interno de una aplicación a partir de señales externas. Logs, métricas y traces responden preguntas distintas y se complementan.
| Señal | Pregunta principal |
|---|---|
| Log | ¿Qué ocurrió en un evento concreto? |
| Métrica | ¿Cómo cambia el sistema en el tiempo? |
| Trace | ¿Dónde pasó el tiempo de una operación distribuida? |
console.log(JSON.stringify({
level: "info",
event: "order.created",
orderId,
requestId,
durationMs
}));Usa campos estables y timestamps de la plataforma. Evita interpolar todo en mensajes imposibles de consultar.
Niveles comunes: debug, info, warn y error. Un error esperado del usuario no siempre merece nivel error.
Cada request puede recibir o generar un ID. Propágalo a logs, llamadas salientes y jobs.
No confíes ciegamente en IDs enviados por clientes; valida longitud y formato o genera uno interno.
import { AsyncLocalStorage } from "node:async_hooks";
const context = new AsyncLocalStorage();
context.run({ requestId }, () => handleRequest());Permite mantener contexto por cadena asíncrona sin pasar parámetros por cada función. No lo uses como contenedor global de negocio ni guardes objetos grandes o sensibles.
Evita labels con cardinalidad alta, como userId o URL completa dinámica; pueden volver inutilizable el sistema de métricas.
Un trace reúne spans de una operación. Cada span registra inicio, fin, atributos y relación con otros spans.
OpenTelemetry ofrece un estándar para instrumentación y exportación. Debe adoptarse progresivamente y con sampling para controlar costo.
Un endpoint de salud no reemplaza métricas ni alertas.
No expongas secretos, stacks ni configuración completa.
Agrupa errores por causa, versión y contexto. Conserva stack y cause, pero redacta datos sensibles.
Registra una vez en la capa que tiene contexto suficiente; logging repetido en cada catch genera ruido.
node:diagnostics_channel permite publicar y consumir eventos de diagnóstico con bajo acoplamiento. Es útil para instrumentación de librerías; úsalo con nombres y payloads estables.
Una alerta debe representar impacto o riesgo accionable. CPU alta por segundos puede ser normal; error rate y latencia sostenidos suelen ser señales más útiles.
¿Por qué requestId es buen campo de log pero mal label de métrica?
Porque ayuda a localizar eventos concretos, pero crea una serie distinta por request y una cardinalidad prácticamente ilimitada en métricas.
Configuración y producción utiliza estas señales para operar procesos reales.