7. Observabilidad y operación

Conclusión. Logs, métricas y trazas con OpenTelemetry, unidos por dos identificadores: el traceId técnico y el correlationId de negocio, que el partner puede enviar y que viaja en cada respuesta, evento y registro de auditoría. Con un correlationId se reconstruye la historia completa de una orden. Hay 17 métricas, 10 alertas ligadas a objetivos de servicio y un runbook por alerta. Aquí van las 10 primeras métricas, las 6 primeras alertas y el runbook de la falla de stock y precio; el resto de métricas y alertas está en el anexo B, y los demás runbooks en el diseño (docs/to-be/10-observabilidad.md).

OTel (OpenTelemetry) es el estándar abierto para generar y exportar logs, métricas y trazas. Los servicios no implementan esto a mano: la malla aporta las métricas de red, la autoinstrumentación aporta las trazas, el recolector lee las métricas de negocio que cada servicio expone en /metrics y un recolector por nodo toma los logs de la salida estándar. Trade-off: dependencia fuerte de la plataforma; a cambio, ningún equipo reinventa la telemetría y el contrato no depende del lenguaje.

7.1 Campos mínimos de logging

JSON por línea, a la salida estándar.

Campo	Ejemplo
`timestamp`	`2026-11-10T18:04:30.123Z`
`level`	`INFO`
`service`, `version`, `env`	`order-service`, `1.4.2`, `prod`
`message`	`Orden aceptada`
`correlationId`	`5e1d0c7a-...`
`traceId`, `spanId`	Contexto de traza
`partnerId`, `channel`	`mkp-andino`
`route`, `method`, `status`, `durationMs`	En logs de acceso
`orderId`, `sku`, `eventId`	Cuando aplica
`errorCode`	El `code` del modelo de errores

Prohibido en logs: nombres, correos, teléfonos, direcciones, tokens, secretos y cualquier dato de pago. Un filtro enmascara patrones conocidos y la prueba F8 falla si aparecen en los logs de los servicios y del borde (hoy se ejecuta con make f4-e2e, sin compuerta; sección 3.8).

7.2 Métricas

#	Métrica	Dimensiones	Para qué
M1	Peticiones por segundo	Ruta, partner, código	Tráfico y mezcla
M2	Tasa de error (5xx y 4xx por separado)	Ruta, partner	Disponibilidad
M3	Latencia p50, p95, p99	Ruta, partner	Objetivo de 300 ms
M4	Frescura del modelo de lectura (`now - asOf`)	Stock o precio	Calidad del dato servido
M5	Aciertos del modelo de lectura frente a respaldo en base	Servicio	Salud de Redis
M6	Retraso de consumidores de Kafka (lag)	Grupo, tópico	Acumulación
M7	Llamadas al legado por segundo y concurrencia en uso	Sistema	Protección del legado
M8	Estado del circuit breaker	Sistema	Legado degradado
M9	Peticiones rechazadas por cuota (429)	Partner, nivel	Cuotas mal dimensionadas o abuso
M10	Órdenes por estado y antigüedad en estado	Estado, canal	Órdenes atascadas

Las métricas se ligan a SLO (service level objective: meta medible de calidad, contra la que se alerta):

SLO	Meta	Ventana
Disponibilidad de APIs externas	99.9% de peticiones sin 5xx	30 días
Latencia de stock y precio	95% bajo 300 ms	30 días
Frescura de stock	95% de lecturas con dato de menos de 10 s	7 días
Confirmación de orden	99% en menos de 60 s desde el pago aprobado	7 días

7.3 Trazas distribuidas y correlación

traceparent, la cabecera del estándar W3C Trace Context (el formato del W3C, el consorcio que publica los estándares de la web, para propagar el contexto de una traza), se propaga por HTTP, gRPC y cabeceras de Kafka. Una traza une la petición del canal con la reserva, el cobro, el registro en OMS y el webhook.
El consumo de un evento abre un tramo enlazado al que lo produjo, así el flujo asíncrono se ve como una sola historia.
correlationId: lo envía el partner en X-Correlation-Id o lo genera el gateway; vuelve en toda respuesta y viaja en cada evento.
Muestreo (diseño; el demo no lo tiene configurado todavía): 100% de errores y de órdenes; 5% de lecturas de stock y precio. Trade-off: una lectura lenta que no cae en el 5% no tiene traza, pero sí métrica y log; se acepta para no pagar el almacenamiento de 2.000 trazas por segundo en pico.
Auditoría de punta a punta: con un correlationId se obtienen la traza, los logs de todos los servicios, los eventos publicados y los registros de auditoría (sección 5.7). Hoy F6 comprueba el correlationId en los logs de los cinco componentes de la orden (sección 3.8); los eventos y la auditoría completa son diseño.

7.4 Alertas

#	Alerta	Condición	Severidad
AL1	Consumo acelerado del presupuesto de error de disponibilidad	Ritmo 14 veces el permitido durante 1 hora, o 6 veces durante 6 horas	Página
AL2	Latencia de stock y precio	p95 mayor a 300 ms por 5 minutos	Página
AL3	Frescura de stock	Mayor a 60 s por 5 minutos	Página en horario de promo; aviso fuera
AL4	Circuit breaker abierto	ERP, WMS u OMS abierto por más de 2 minutos	Aviso
AL5	Órdenes atascadas	Más de 10 órdenes en `PENDING_PAYMENT` con más de 20 minutos	Página
AL6	Registro en OMS atrasado	Alguna orden con `omsSync` pendiente por más de 10 minutos	Aviso; página a los 30

Toda alerta enlaza a su tablero y a su runbook. La alerta AL1 se basa en el ritmo de consumo del presupuesto de error y no en un umbral fijo: avisa rápido ante una caída fuerte y no despierta a nadie por un pico breve.

7.5 Runbook: falla stock o precio

Síntoma: alerta AL2 o AL3, o partners reportando errores o datos viejos en GET /v1/stock o GET /v1/prices.

Clasificar en el tablero de lecturas, en menos de 2 minutos: ¿errores 5xx o latencia? Paso 2. ¿Responde bien pero con dato viejo (stale: true, frescura alta)? Paso 3.
La ruta de lectura falla:
- Redis caído o saturado: confirmar que el respaldo a base está activo; promover réplica.
- Servicio: revisar reinicios y saturación; escalar réplicas.
- Gateway o cuotas: si los 429 se dispararon para todos, revisar el servicio de cuotas (falla abierta) y el tope general.
- Despliegue reciente: si coincide en el tiempo, devolver a la versión anterior antes de investigar.
La ruta de alimentación falla (el canal sigue recibiendo 200):
- Lag de Kafka alto: revisar el consumidor del servicio.
- Adaptador con circuit breaker abierto o cursor detenido: el problema está en el legado o en el enlace on-prem. Confirmar con el equipo del ERP o del WMS.
- Mientras dure, se sirve el último dato con stale: true. Si es stock y supera 15 minutos, subir el colchón de seguridad de los SKU de alta rotación para reducir el riesgo de sobreventa.
Comunicar: estado a soporte y a los partners afectados si supera 10 minutos.
Recuperación: al volver la fuente, el adaptador retoma desde su cursor; verificar que la frescura baje al objetivo. Si hubo pérdida de cambios, disparar la conciliación completa.
Cierre: revisión sin culpables en 5 días hábiles; si el aprendizaje es repetible, se convierte en alerta, función de aptitud o paso de este runbook.

Lo que no se hace: apuntar los canales directo al ERP o al WMS "mientras tanto". Eso recrea el AS-IS en el peor momento.

7.6 Herramientas

En producción: OpenTelemetry Collector, Amazon Managed Service for Prometheus (métricas), Loki u OpenSearch (logs), Tempo o AWS X-Ray (trazas) y Amazon Managed Grafana (tableros y alertas). En el demo, las mismas piezas de código abierto dentro del clúster.