/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.