Observabilidad en integraciones: logs, métricas, trazas y correlation IDs

Una integración cruza límites: entre tu código y el de un tercero, entre tu red y la suya, entre tus registros y los de otro equipo. Cuando algo falla, la pregunta «¿qué pasó con el pedido 1042?» exige reconstruir el recorrido a través de varios sistemas. La observabilidad es la capacidad de responder esas preguntas a partir de lo que el sistema registra, sin tener que agregar código nuevo cada vez.

Tres tipos de señales

No se trata de elegir una: las métricas avisan de que algo anda mal, las trazas indican dónde y los logs explican por qué.

Qué registrar en cada llamada externa

Para cada llamada a un servicio externo (o recepción de un webhook), un registro útil incluye:

• Fecha y hora con zona horaria.
• Servicio externo y operación (por ejemplo, «pasarela» y «consultar pago»).
• Identificador de correlación de la operación de negocio.
• Identificadores de negocio relevantes: número de pedido, referencia externa del pago.
• Duración de la llamada.
• Resultado: código de estado, tipo de error, número de intento.

Y, con la misma importancia, lo que no se debe registrar:

• Contraseñas, tokens, claves de API ni encabezados de autorización.
• Datos completos de tarjetas de pago.
• Datos personales innecesarios para diagnosticar; si se necesitan, enmascarados.

{
  "timestamp": "2026-10-03T14:22:05.311-05:00",
  "level": "warn",
  "event": "llamada_externa",
  "dependency": "pasarela_pagos",
  "operation": "consultar_pago",
  "correlation_id": "c1f3a9e2-5b7d-4e0a-9d1c-2f8b6a4e7c90",
  "order_id": "1042",
  "external_ref": "pay_8f2k1",
  "attempt": 2,
  "duration_ms": 3012,
  "outcome": "timeout"
}

Los valores del ejemplo son ficticios.

Identificadores de correlación

Un identificador de correlación es un valor único que se genera cuando empieza una operación (por ejemplo, cuando el cliente confirma un pedido) y se propaga a todas las llamadas y procesos relacionados. Así, filtrando por ese identificador, se obtiene la historia completa de la operación en todos los sistemas.

• Genéralo en el punto de entrada si no viene en la solicitud.
• Propágalo en un encabezado a cada servicio interno que llames.
• Inclúyelo en los mensajes que pongas en colas, para que el procesamiento asíncrono también quede vinculado.
• Guárdalo junto a la referencia que devuelve el sistema externo, para poder cruzar con sus registros o con su soporte.

El estándar W3C Trace Context define el encabezado traceparent para propagar este contexto entre servicios, y muchas herramientas de trazas lo reconocen de forma automática.

1. WebGenera el identificador al confirmar el pedido.
2. APILo recibe en el encabezado y lo registra.
3. ColaLo incluye en el mensaje.
4. Proceso de pagosLo registra junto a la referencia externa.
5. ERPLo recibe y lo registra al crear la venta.

Métricas por dependencia

Para cada servicio externo conviene medir, como mínimo:

• Tasa: cuántas llamadas por minuto.
• Errores: porcentaje de llamadas fallidas, separado por tipo.
• Duración: tiempos de respuesta en percentiles (p50, p95, p99), no solo el promedio. Un promedio aceptable puede ocultar que una de cada veinte llamadas tarda diez segundos.

A estas métricas técnicas conviene sumar métricas de negocio que revelan problemas invisibles para los checks técnicos: pedidos creados frente a pedidos pagados, pagos pendientes con más de cierto tiempo de antigüedad, tiempo desde el último webhook recibido o mensajes acumulados en una cola.

Alertas que sí sirven

Una alerta debe indicar algo que requiere acción humana. Si se dispara a menudo sin consecuencias, el equipo aprende a ignorarla. Las mejores alertas se basan en síntomas que afectan a usuarios o al negocio:

Los umbrales concretos dependen del volumen y del comportamiento normal de cada sistema; se ajustan observando datos reales.

Privacidad y retención

Los logs son datos y, como tales, están sujetos a las mismas consideraciones de protección que cualquier otra información. Define cuánto tiempo se conservan, quién puede acceder y cómo se eliminan. Guardar todo para siempre aumenta el costo y el riesgo sin aportar valor.

Errores frecuentes

• Logs en texto libre imposibles de filtrar.
• No registrar la referencia externa, lo que impide cruzar información con el proveedor.
• Registrar el cuerpo completo de solicitudes con datos sensibles.
• Medir solo promedios de tiempo de respuesta.
• Alertas sobre recursos (CPU, memoria) sin alertas sobre síntomas del usuario.
• Perder el contexto al pasar por una cola.

Lista de verificación

• Los logs son estructurados y tienen identificador de correlación.
• Cada llamada externa registra dependencia, operación, duración y resultado.
• No se registran secretos ni datos de tarjeta.
• Hay métricas de tasa, errores y percentiles por dependencia.
• Hay métricas de negocio y alertas basadas en síntomas.
• Está definida la retención de logs.

Preguntas frecuentes