monitoring-setup

name	monitoring-setup
description	Configurar observabilidad del servicio. Activar cuando el usuario quiera configurar logging, integrar Sentry, implementar error tracking, definir metricas, configurar alertas, mejorar la observabilidad o monitorizar un servicio.

Configurar observabilidad

Resumen

Este skill configura las tres patas de la observabilidad: logging estructurado, error tracking y métricas. Sin observabilidad, operar un servicio en producción es como conducir de noche sin luces: todo va bien hasta que no. El objetivo es poder responder a tres preguntas fundamentales: qué está pasando ahora, qué ha pasado antes y por qué algo falla.

Proceso

1. Configurar logging estructurado. Los logs en texto plano son difíciles de buscar y analizar. Usar JSON como formato estándar:

   {
     "timestamp": "2024-03-15T10:30:00Z",
     "level": "error",
     "message": "Fallo al procesar pago",
     "service": "payment-service",
     "requestId": "abc-123",
     "userId": "usr-456",
     "error": {
       "type": "PaymentGatewayError",
       "message": "Timeout after 30s",
       "stack": "..."
     }
   }
   

   Principios del logging:

   • Cada entrada tiene timestamp, nivel, mensaje y contexto.
   • Los request IDs permiten trazar un flujo a través de múltiples servicios.
   • Los datos sensibles (contraseñas, tokens, datos personales) NUNCA aparecen en logs.
   • Niveles: debug (desarrollo), info (flujo normal), warn (situación inusual), error (algo falló).

2. Configurar error tracking. Herramientas como Sentry, Bugsnag o Rollbar proporcionan contexto rico para cada error:

   • Instalación del SDK en la aplicación.
   • Configuración del DSN (endpoint de reporte).
   • Source maps para errores de frontend (si aplica).
   • Agrupación de errores para evitar ruido.
   • Alertas para errores nuevos o con picos de frecuencia.
   • Integración con el sistema de issues (GitHub, Jira) para seguimiento.

3. Definir métricas de negocio y técnicas. Las métricas cuentan la historia del sistema en números:

   • Técnicas: latencia de requests (p50, p95, p99), tasa de error, uso de CPU/memoria, conexiones a base de datos.
   • Negocio: registros por hora, transacciones completadas, tasa de conversión, usuarios activos.

   Las métricas de negocio son las que más interesan al equipo de producto; las técnicas son las que interesan a operaciones.

4. Configurar alertas. Las alertas deben ser accionables, no ruidosas:

   • Crítica: el servicio está caído o perdiendo datos. Requiere acción inmediata (pagina al ingeniero de guardia).
   • Alta: tasa de error elevada o degradación significativa. Requiere atención en la próxima hora.
   • Media: tendencia preocupante que no requiere acción inmediata. Revisar en el próximo día laborable.

   Evitar alertas que nadie mira. Si una alerta se ignora sistemáticamente, o se elimina o se ajusta su umbral.

5. Implementar health endpoints. La aplicación debe exponer su estado de salud:

   • GET /health: responde 200 si la aplicación está corriendo (liveness).
   • GET /ready: responde 200 si la aplicación puede procesar requests (readiness). Incluye verificación de dependencias críticas (base de datos, caché).

6. Documentar la configuración. Dejar claro dónde se visualizan los logs, cómo se accede al error tracking y qué dashboards están disponibles.

Criterios de éxito

• Los logs son estructurados (JSON) con timestamp, nivel, mensaje y contexto.
• No hay datos sensibles en los logs.
• El error tracking está integrado y agrupa errores correctamente.
• Las métricas cubren al menos latencia, tasa de error y una métrica de negocio.
• Las alertas son accionables y están clasificadas por severidad.
• Los health endpoints están implementados y responden correctamente.

Que NO hacer

• No loguear datos personales (PII). Nombres, emails, direcciones IP, tokens de sesión y cualquier dato identificable deben ser redactados o excluidos de los logs para cumplir con GDPR y buenas prácticas de seguridad.
• No configurar alertas sin definir umbrales concretos. Una alerta sin umbral genera ruido y se acaba ignorando. Cada alerta debe tener un criterio numérico que determine cuándo se dispara y cuándo se resuelve.