Resumen
Este documento es la fuente de verdad del modelo de observabilidad del proyecto Pedido Sugerido. Define qué se monitorea, cómo se notifica, quién responde y en qué tiempo. Combina tres capas de observabilidad:
- Operacional (Nivel 1) · fallos de pipeline, alertas, throughput
- De modelo (Nivel 2) · data drift, métricas de calidad, schema drift
- De gobernanza (Nivel 3) · audit trail, aprobaciones, retraining events
El catálogo cubre ~25 alarmas, 3 dashboards y 2 SNS topics distribuidos por los 3 Niveles. Define también la definición operacional (¿qué significa "alerta llegó en <5 min"?) requerida por la propuesta v2.
Alarmas CloudWatch · Nivel 1
Configuradas en el deploy del Nivel 1. Existen ya 2 de las que siguen (executionfailedalarm, executionstoppedalarm); las demás se agregan en sem 3-4.
| # | Nombre | Métrica | Threshold | Severity | Acción | Responsable |
|---|---|---|---|---|---|---|
| 1 | aje-dev-ps-executionfailedalarm-cloudwatch (existe) |
AWS/SageMaker / ExecutionsFailed agregado por hora |
≥ 1 en ventana de 1h | Critical | Notificar SNS aje-dev-ps-alert-topic-sns |
AJE oncall |
| 2 | aje-dev-ps-executionstoppedalarm-cloudwatch (existe) |
AWS/SageMaker / ExecutionsStopped agregado por hora |
≥ 1 en ventana de 1h | Warning | Notificar SNS | AJE oncall |
| 3 | aje-dev-ps-limpiezaduration-{pais}-cloudwatch (uno por país) |
Duración del step Limpieza | > 15 min | Warning | Notificar SNS | Tuxpas durante warranty |
| 4 | aje-dev-ps-modelado-duration-{pais}-cloudwatch |
Duración del step Modelado | > 30 min | Warning | Notificar SNS | Tuxpas durante warranty |
| 5 | aje-dev-ps-pipeline-totalduration-{pais}-cloudwatch |
Duración total del pipeline por país | > 60 min | Warning | Notificar SNS | Tuxpas durante warranty |
| 6 | aje-dev-ps-lambdaerrors-cloudwatch |
AWS/Lambda / Errors en aje-dev-ps-triggerfunction-lambda |
≥ 1 en ventana de 5 min | Critical | Notificar SNS | AJE oncall |
| 7 | aje-dev-ps-lambdathrottles-cloudwatch |
AWS/Lambda / Throttles |
≥ 1 en ventana de 5 min | Warning | Notificar SNS | AJE oncall |
| 8 | aje-dev-ps-eventbridgefailures-cloudwatch |
AWS/Events / FailedInvocations |
≥ 1 en ventana de 15 min | Warning | Notificar SNS | AJE oncall |
| 9 | aje-dev-ps-codepipelinefailure-cloudwatch |
AWS/CodePipeline / FailedPipeline |
≥ 1 | Critical | Notificar SNS · bloquea deploys | Tuxpas durante desarrollo |
Total Nivel 1: 9 alarmas (2 base + 7 nuevas con scope por país aplicado donde corresponde)
Alarmas CloudWatch · Nivel 2
Se agregan durante sem 5-7 (Desarrollo Nivel 2). Foco en calidad del modelo y data drift.
| # | Nombre | Métrica | Threshold | Severity | Acción | Responsable |
|---|---|---|---|---|---|---|
| 10 | aje-dev-ps-datadrift-{pais}-cloudwatch (uno por país) |
Model Monitor · DataDriftScore |
PSI > 0.25 en ≥ 2 features clave | Warning | Notificar SNS y log a DynamoDB | AJE + Tuxpas |
| 11 | aje-dev-ps-schemadrift-{pais}-cloudwatch |
Model Monitor · MissingColumns o NewColumns |
Cualquier cambio | Critical | Notificar SNS + halt pipeline | Tuxpas + AJE |
| 12 | aje-dev-ps-ndcgdrop-{pais}-cloudwatch |
Métrica custom · NDCG@10 vs baseline | Caída > 5% por 2 semanas consecutivas | Warning | Notificar SNS · trigger reentreno en Nivel 3 | AJE |
| 13 | aje-dev-ps-modelapproval-pendingtoolong-cloudwatch |
Tiempo desde Register hasta Approval | > 72h sin aprobación | Warning | Notificar al analista AJE | AJE |
| 14 | aje-dev-ps-trainpipeline-fail-cloudwatch |
AWS/SageMaker / TrainPipelineFailed |
≥ 1 | Critical | Notificar SNS | AJE + Tuxpas |
| 15 | aje-dev-ps-infpipeline-fail-cloudwatch |
AWS/SageMaker / InfPipelineFailed |
≥ 1 | Critical | Notificar SNS (igual que la global de Nivel 1, pero distinguible por pipeline) | AJE oncall |
Total Nivel 2 nuevas: 6 → Acumulado: 15 alarmas
Alarmas CloudWatch · Nivel 3
Foco en gobernanza y retraining.
| # | Nombre | Métrica | Threshold | Severity | Acción | Responsable |
|---|---|---|---|---|---|---|
| 16 | aje-dev-ps-retrainfailure-{pais}-cloudwatch |
Fallo del pipeline de retraining | ≥ 1 | Critical | Notificar SNS + log a DynamoDB de retrain history | AJE + Tuxpas |
| 17 | aje-dev-ps-cooldownviolation-cloudwatch |
Intento de retrain antes de los 14 días de cooldown | ≥ 1 | Info | Log only · NO bloquea pero indica drift frecuente | AJE |
| 18 | aje-dev-ps-modelrejected-{pais}-cloudwatch |
Modelo nuevo no supera baseline · marcado Rejected | ≥ 1 | Warning | Notificar SNS | AJE |
| 19 | aje-dev-ps-multiplereainsamewindow-cloudwatch |
Más de 2 retrains en una semana | ≥ 3 retrains/sem | Warning | Notificar SNS · sugerir investigación de drift root cause | AJE |
| 20 | aje-dev-ps-cloudtrailunavailable-cloudwatch |
CloudTrail trail · IsLogging = false |
≥ 1 | Critical | Notificar SNS · governance broken | AJE |
| 21 | aje-dev-ps-costanomaly-cloudwatch |
Costo total del proyecto · anomaly detection | > 1.5× del promedio mensual | Warning | Notificar SNS | AJE FinOps |
Total Nivel 3 nuevas: 6 → Acumulado total proyecto: 21 alarmas
Dashboards CloudWatch
Dashboard 1 · Operacional (Nivel 1)
| Campo | Valor |
|---|---|
| Nombre | aje-dev-ps-monitoringdashboard-cloudwatch (ya existe parcialmente) |
| Audiencia | AJE oncall + Tuxpas durante el Desarrollo |
| Frecuencia de revisión esperada | Mañanas L-V (post ejecución de schedules) + bajo demanda en respuesta a alertas |
Widgets (propuestos, a confirmar con AJE en Sesión 2):
| Widget | Tipo | Contenido |
|---|---|---|
| Status diario por país | Single value × 7 | Verde si última ejecución Succeeded, rojo si Failed |
| Ejecuciones por país · últimas 24h | Stacked bar × 7 | Succeeded (verde) + Failed (rojo) + Stopped (amarillo) |
| Duración promedio por step · por país | Line × 21 | 7 países × 3 steps (Limpieza · Modelado · Reglas) |
| Tendencia de fallos · últimos 7 días | Line | Total de Failed por día |
| Latencia EventBridge → SM trigger | Line | Tiempo entre cron firing y StartPipelineExecution |
| Top errores recientes (CloudWatch Logs Insights query) | Query result | Errores únicos agrupados con count en 24h |
Dashboard 2 · Calidad de modelo (Nivel 2)
| Campo | Valor |
|---|---|
| Nombre | aje-dev-ps-modelquality-dashboard-cloudwatch (nuevo en Nivel 2) |
| Audiencia | AJE analyst (Athenea) + Tuxpas durante desarrollo |
| Frecuencia de revisión esperada | Semanal (post ejecución del pipeline de entrenamiento) |
Widgets:
| Widget | Tipo | Contenido |
|---|---|---|
| NDCG@10 actual por país | Single value × 7 | Última métrica vs baseline aprobado |
| Tendencia NDCG@10 · últimos 12 meses | Line × 7 | Una línea por país |
| Precision@5 y @10 por país | Bar grouped × 7 | Comparación contra baseline |
| Coverage por país | Bar × 7 | Con threshold mínimo (30%) marcado |
| Modelos por status en Registry | Pie | PendingManualApproval · Approved · Rejected |
| Drift score por país · 30 días | Heatmap | Color escala por PSI |
Dashboard 3 · Gobernanza (Nivel 3)
| Campo | Valor |
|---|---|
| Nombre | aje-dev-ps-governance-dashboard-cloudwatch (nuevo en Nivel 3) |
| Audiencia | AJE compliance / data governance |
| Frecuencia de revisión esperada | Mensual (o ante auditoría) |
Widgets:
| Widget | Tipo | Contenido |
|---|---|---|
| Retrains por país · últimos 90 días | Bar × 7 | Cuántos retrains se dispararon (automatic + manual) |
| Tiempo promedio aprobación humana | Single value | Hours mean entre Register y Approval |
| Eventos CloudTrail · UpdateModelPackage · 30 días | Table | Lista de aprobaciones recientes con principal + timestamp |
| Costo mensual estimado | Bar | Por servicio AWS (SageMaker, S3, ECR, CloudWatch) |
| Model Cards completeness | Bar × 7 | Porcentaje de campos completos por país |
SNS Topics y suscriptores
Topic 1 · aje-dev-ps-alert-topic-sns (ya existe)
Propósito: alertas operacionales y de calidad de modelo. Subscriber pool single.
Suscriptores propuestos (a confirmar en Sesión 1 con AJE):
| Rol | Severities que recibe | |
|---|---|---|
mlops-oncall@ajegroup.com (propuesto · grupo distribuido) |
AJE oncall principal | All (Critical + Warning) |
miguel.espinoza@ajegroup.com |
AJE Arquitecto Datos | Critical only |
gherald.barzola@ajegroup.com |
AJE Analítica | Critical + Warning |
adrian.ulloa@tuxpas.com |
Tuxpas Squad Lead | All (durante desarrollo + warranty) |
joseph.garcia@tuxpas.com |
Tuxpas Dev Senior | All (durante desarrollo) |
Mecanismo de filtrado por severity: SNS message attributes con severity=critical|warning|info. Cada suscriptor configura un Filter Policy si quiere recibir solo Critical.
Topic 2 · aje-dev-ps-governance-topic-sns (nuevo en Nivel 3)
Propósito: notificaciones de gobernanza. Eventos como "modelo aprobado", "retrain disparado", "drift detectado".
Suscriptores propuestos:
| Rol | Eventos que recibe | |
|---|---|---|
governance@ajegroup.com (propuesto) |
AJE compliance | Todos |
miguel.espinoza@ajegroup.com |
AJE Arquitecto Datos | Aprobaciones de modelo |
adrian.ulloa@tuxpas.com |
Tuxpas Squad Lead | Todos durante handover |
Definición operacional
"Alerta llega en <5 min" (requerimiento propuesta v2)
Definimos tiempo de alerta como el tiempo entre:
- t0 =
EndTimedel ProcessingJob fallido (reportado por SageMaker) - t1 = timestamp del email recibido por el suscriptor (headers SMTP)
El criterio se cumple si t1 − t0 ≤ 5 minutos, validado en VT1 con demos provocadas.
Componentes que contribuyen al tiempo total:
| Etapa | Tiempo típico |
|---|---|
| SageMaker reporta fallo al CloudWatch Events | ~30s |
| CloudWatch Events evalúa la alarma (período de 1h) | hasta 1 min |
| Alarma cambia estado a ALARM y publica al SNS | ~10s |
| SNS entrega email | ~10s − 2 min según provider |
| Total esperado | 1.5 − 4 min |
Riesgo conocido: la alarma usa ventana agregada de 1 hora. Si el fallo ocurre justo después de un evaluation period, podría tardar más del threshold. Mitigación: usar evaluation periods cortos (1 min) en métricas críticas.
"Severity Critical · Warning · Info"
| Severity | Significado | Tiempo de respuesta esperado | Quién responde |
|---|---|---|---|
| Critical | Pipeline o servicio AWS roto. Recomendaciones del día NO se generan. | < 30 min en horario laboral · < 4h fuera de horario | AJE oncall (post handover) / Tuxpas (warranty) |
| Warning | Degradación detectada pero el servicio sigue funcionando. Acción correctiva en las próximas 24h. | < 4h en horario laboral · < 24h en general | AJE oncall (relajado) |
| Info | Evento notificable pero no requiere acción inmediata. Log only en muchos casos. | No requiere respuesta · revisión semanal | AJE analyst |
On-call durante warranty post-handover
El proyecto incluye un periodo de warranty (propuesto: 2 semanas post-entrega · a confirmar en DOC-AF-09) donde Tuxpas mantiene oncall paralelo:
- L-V horario laboral (9 AM – 6 PM Lima) · respuesta Tuxpas + AJE
- L-V fuera de horario · sábados · domingos · AJE responde primero · Tuxpas escala si AJE no responde en 2h
Post-warranty, AJE asume oncall completo.
Escalation paths
| Escenario | Path |
|---|---|
| Critical alarm + AJE oncall no responde en 30 min | Auto-escalation SMS (si AJE configura) + Tuxpas durante warranty |
| Multiple Critical alarms en una hora | Posible incidente sistémico · convoca war room (zoom) en 1h |
| Warning alarms recurrentes (>3 en una semana del mismo tipo) | Tuxpas + AJE revisan en sync semanal · puede indicar issue de fondo |
Procedimientos de respuesta · enlaces a runbooks
Las alarmas notifican el problema. Los runbooks (documentados en DOC-AF-09) definen el paso a paso de mitigación. Resumen:
| Alarma | Runbook asociado |
|---|---|
executionfailedalarm |
RB-01 · "Pipeline falló · ¿qué hago?" |
lambdaerrors, lambdathrottles |
RB-01 (mismo flow inicial) + sección Lambda |
datadrift-* |
RB-02 · "Drift detectado · ¿qué hago?" |
schemadrift-* |
RB-02 + escalation manual (no auto-retrain en schema drift) |
modelapproval-pendingtoolong |
RB-03 · "Promoción manual de modelo · paso a paso" |
retrainfailure-* |
RB-04 · "Retraining automático falló · ¿qué hago?" |
costanomaly |
RB-05 · "Costos anormales · investigar" |
Storage de métricas y reportes
| Item | Ubicación |
|---|---|
| CloudWatch metrics nativas | Retención default 15 meses (suficiente para análisis temporal) |
| Logs de ProcessingJobs | /aws/sagemaker/ProcessingJobs (retención 30 días default · ajustable) |
| Logs de Lambda | /aws/lambda/aje-dev-ps-triggerfunction-lambda (retención 14 días default) |
| Reportes Model Monitor | s3://aje-dev-analytics-artifacts-s3/ps-pipeline/<PAIS>/drift_reports/<fecha>/ |
| DynamoDB histórico de métricas | aje-dev-ps-modelmetrics-dynamodb (Nivel 2) |
| DynamoDB histórico de retrain | aje-dev-ps-retrainhistory-dynamodb (Nivel 3) |
| CloudTrail logs | s3://aje-dev-ps-audittrailbucket-s3/ (Nivel 3) · retención 1 año |
Próximos pasos
- Sesión 1 (Lun 18-may) · confirmar con AJE la lista de emails suscriptores del topic
aje-dev-ps-alert-topic-sns. Sin esto, las alarmas existen pero no notifican. - Sesión 2 (Mié 20-may) · validar las 21 alarmas propuestas con AJE. Acordar severities y thresholds (especialmente
costanomalyque requiere context de baseline). - Sem 3 (Desarrollo Nivel 1) · implementar las 7 alarmas nuevas del Nivel 1 (2 ya existen). CloudWatch dashboard completo.
- VT1 (sem 4) · demo de "alerta llega en <5 min" (provocar fallo intencional · cronometrar).
- Sem 5-7 (Desarrollo Nivel 2) · agregar las 6 alarmas del Nivel 2 + nuevo dashboard de calidad.
- Sem 8-10 (Desarrollo Nivel 3) · agregar las 6 alarmas del Nivel 3 + dashboard de gobernanza.
- Handover · capacitación a AJE de cómo leer cada dashboard y responder a cada tipo de alarma (integrado al DOC-AF-09).