Mejores prácticas de observabilidad

Alerta sobre los síntomas, no sobre cada seguimiento de pila. Estas reglas mantienen la observabilidad de Node.js accionable, asequible y correlacionada entre registros, métricas y trazas.

Cómo usar esta lista

• Aplícala al configurar un nuevo servicio o al migrar proveedores de APM.
• Combínala con SLOs y presupuestos de error para la política de paginación.
• Revisa la cardinalidad antes de exportar nuevas métricas personalizadas.
• Realiza días de juego para verificar que las trazas cubran los viajes críticos del usuario.

A - Métricas y SLOs

• Exporta métricas RED para cada servicio HTTP. Tasa, errores (5xx), histograma de duración.
• Añade la espera del pool y la profundidad de la cola donde sea aplicable. Indicadores principales antes de 5xx.
• Define el SLO con una política de presupuesto de error por escrito. No solo en el panel de control.
• Página en la quema de SLO de múltiples ventanas, no en una sola línea de registro. Reglas de quema rápida y lenta.
• Normaliza las etiquetas de ruta (/users/:id). Nunca UUIDs en las dimensiones de las métricas.

B - Trazas e instrumentación

• Carga instrumentation.ts antes de las importaciones del framework. Requisito de auto-instrumentación HTTP.
• Una ruta de instrumentación por proceso. OTel SDK XOR agente del proveedor, no ambos.
• Muestra las trazas en producción (1-10%). Muestra los errores si el proveedor lo soporta.
• Spans manuales en operaciones comerciales críticas. Pago, autenticación, encolamiento.
• Propaga W3C traceparent en HTTP saliente. Los servicios descendentes continúan la traza.

C - Registros y correlación

• Inyecta trace_id en los registros de Pino a través de mixin o ALS. Correlación de registro-traza en APM.
• Mantén requestId junto con trace_id durante la migración. Soporte y herramientas heredadas.
• Solo JSON estructurado; sin PII en atributos de span o campos de registro. IDs, no correos electrónicos.
• Separa los backends de telemetría de desarrollo/staging/producción. Sin fuga de trazas de producción a cuentas de desarrollo.
• info para el ciclo de vida; error para fallos que requieren acción. Las mismas reglas que la sección de registro.

D - Paneles y alertas

• Un panel de control dorado por servicio. RED + pool + cola + retardo de bucle.
• Runbooks vinculados desde las anotaciones de alerta. No incrustados en cada span.
• Alerta sobre umbrales de síntomas (p95, tasa de error). No solo la CPU.
• Revisa la fatiga de alertas trimestralmente. Elimina las alertas que nunca llevaron a una acción.
• La verificación de salud excluida del SLO o registrada en depuración. El tráfico de sondeo distorsiona las métricas.

E - Operaciones y costos

• sdk.shutdown() elegante en SIGTERM. Vacía los spans antes de la eliminación del pod.
• OTel Collector para la exportación del proveedor en k8s. La aplicación permanece agnóstica al proveedor OTLP.
• Documenta OTEL_SERVICE_NAME por despliegue. Precisión del catálogo de servicios.
• Supervisa el costo de ingesta de telemetría mensualmente. Ajustes de muestreo cuando el volumen de spans se dispara.
• Valida la observabilidad en pruebas de carga antes del lanzamiento. Métricas y trazas bajo el RPS esperado.

Preguntas frecuentes

Relacionado

• Conceptos básicos de observabilidad - introducción a los tres pilares
• OpenTelemetry Node SDK - configuración del SDK
• Métricas importantes - qué exportar
• Mejores prácticas de registro - reglas de registro estructurado

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.