From 81be46c69c468b27ebef2fc9c4b7b312060f81dd Mon Sep 17 00:00:00 2001 From: borja Date: Mon, 8 Sep 2025 14:20:31 +0200 Subject: [PATCH] docs: actualizar README.md y STATUS.md con observabilidad y /metrics y /health Co-authored-by: aider (openrouter/openai/gpt-5) --- README.md | 12 +++++++++--- STATUS.md | 8 ++++++-- docs/plan-sincronizacion-miembros.md | 9 ++++----- 3 files changed, 19 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 8c2a52e..da02e9d 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ Un chatbot de WhatsApp para gestionar tareas en grupos, integrado con Evolution - Nombres amigables vía caché de contactos (sin llamadas de red en tests). - Sincronización de miembros de grupos (snapshot periódica + webhooks incrementales; tolerante a fallos). - Mensajes compactos con emojis y cursiva; fechas dd/MM; vencidas con ⚠️. +- Observabilidad mínima: /metrics (Prometheus por defecto, JSON opcional) y /health detallado. ## Requisitos - Evolution API accesible (recomendado: misma red interna Docker). @@ -61,6 +62,11 @@ Un chatbot de WhatsApp para gestionar tareas en grupos, integrado con Evolution - Opcionales — migraciones - MIGRATOR_CHECKSUM_STRICT: si "false" desactiva validación estricta de checksum de migraciones; por defecto "true". - MIGRATIONS_LOG_PATH: ruta del fichero de log de migraciones; por defecto data/migrations.log. +- Opcionales — métricas y mantenimiento + - METRICS_ENABLED: "true"|"false" para habilitar /metrics; por defecto true (desactivado en test). + - METRICS_FORMAT: "prom"|"json"; por defecto "prom". + - GROUP_MEMBERS_INACTIVE_RETENTION_DAYS: días para purgar miembros inactivos; 180 por defecto; 0 desactiva. + - FORCE_SCHEDULERS: "true" para forzar arranque de jobs en NODE_ENV=test. - Entorno - NODE_ENV: production | development | test. @@ -87,7 +93,7 @@ Consulta .env.example para un listado comentado con valores de ejemplo. ## Limitaciones conocidas - Sin orden garantizado por destinatario en la cola. -- Sin endpoint /metrics por ahora. +- /metrics básico sin histogramas ni etiquetas; mejoras futuras. - Permisos/roles y validación estricta de pertenencia a grupos no implementados. ## Roadmap @@ -115,9 +121,9 @@ Consulta .env.example para un listado comentado con valores de ejemplo. - Objetivo: conocer miembros activos por grupo para features avanzadas. - Implica: endpoints Evolution API para miembros; cache/migraciones. -10) Métricas y observabilidad (deferido del MVP) +10) Métricas y observabilidad - Objetivo: visibilidad con bajo coste. -- Implica: counters/gauges/histograms y endpoint /metrics; logging estructurado. Se pospone al final de esta lista. +- Implementado: /metrics (Prometheus/JSON) con counters/gauges y /health detallado; pendiente: histogramas/latencias y logging estructurado avanzado. ## 🔑 Key Considerations & Caveats * **WhatsApp ID Normalization:** Crucial for consistently identifying users and groups. Needs careful implementation to handle edge cases. (Utility function exists). diff --git a/STATUS.md b/STATUS.md index 39d576d..3654c5f 100644 --- a/STATUS.md +++ b/STATUS.md @@ -26,6 +26,10 @@ Estado general: listo para piloto con la junta directiva; 170 tests pasando. Rie - Caché en memoria, actualización por webhooks, fallback a Evolution API (saltado en tests); nombres amigables en textos. - Testing - ~170 tests unitarios con SQLite en memoria; ResponseQueue (reintentos/cleanup), comandos (alias/fechas/listados/x/tomar/soltar), recordatorios, utilidades. +- Observabilidad y mantenimiento + - Endpoint /metrics (Prometheus por defecto; JSON opcional) con contadores/gauges básicos: sync_runs_total, sync_errors_total, webhook_events_total_*, webhook_errors_total, active_groups, active_members, last_sync_*. + - /health detallado (full=1) con active_groups, active_members, last_sync_at y snapshot_age_ms. + - Job diario de limpieza de miembros inactivos configurable (GROUP_MEMBERS_INACTIVE_RETENTION_DAYS; por defecto 180 días). ## Pendiente (priorizado) - MVP operativo (bloqueantes/casi bloqueantes) @@ -34,7 +38,7 @@ Estado general: listo para piloto con la junta directiva; 170 tests pasando. Rie 3) Seguridad/red: ejecutar en red interna con Evolution API; si no, proteger el webhook (IP allowlist/reverse proxy). 4) Ensayo E2E en staging: registro de webhook, recepción de MESSAGES_UPSERT reales y envío de DMs. - Post-MVP (mejoras) - - Observabilidad: /metrics con contadores de cola, errores y latencias. + - Observabilidad: ampliar métricas (latencias/histogramas, etiquetas), dashboards y alertas. - Orden por destinatario en ResponseQueue; idempotency_key opcional. - Permisos/roles y pertenencia a grupos (si se requiere). - Edición/eliminación de tareas. @@ -44,7 +48,7 @@ Estado general: listo para piloto con la junta directiva; 170 tests pasando. Rie - Iteración A — Operativa lista para piloto - Entregables: pipeline CI (GitHub Actions), build de imagen, despliegue CapRover con volumen /app/data, backup diario configurado, checklist de red interna verificada. - Iteración B — Observabilidad mínima - - Entregables: logs con contexto en puntos clave, plan de /metrics (pospuesto si no es crítico), guía de troubleshooting. + - Entregables: logs con contexto en puntos clave, ruta /metrics (Prometheus/JSON) y /health detallada, guía de troubleshooting. - Iteración C — Calidad de datos/UX - Entregables: mejoras de caché de contactos, afinado de recordatorios (hora por usuario), pruebas adicionales de ResponseQueue y comandos. diff --git a/docs/plan-sincronizacion-miembros.md b/docs/plan-sincronizacion-miembros.md index 4118033..d96c473 100644 --- a/docs/plan-sincronizacion-miembros.md +++ b/docs/plan-sincronizacion-miembros.md @@ -99,14 +99,13 @@ Etapa 3 — Consumidores (comandos y recordatorios) — COMPLETADA - Tests: - Cobertura de ambos caminos (con y sin membership). -Etapa 4 — Observabilidad y mantenimiento +Etapa 4 — Observabilidad y mantenimiento — COMPLETADA - Métricas: - - grupos sincronizados, miembros activos, difs por sync, errores de webhook. + - Contadores y gauges básicos expuestos en /metrics (Prometheus por defecto, JSON opcional): sync_runs_total, sync_errors_total, webhook_events_total_*, webhook_errors_total, active_groups, active_members, last_sync_*. - Estado de salud: - - último sync OK, edad de la snapshot. + - /health (full=1) incluye last_sync_at, snapshot_age_ms, active_groups, active_members. - Mantenimiento: - - Re-sync diario. - - Purgado opcional de inactivos antiguos. + - Job diario de purga de miembros inactivos con retención configurable (GROUP_MEMBERS_INACTIVE_RETENTION_DAYS; por defecto 180). ## Criterios de aceptación - Tras una full sync, group_members refleja fielmente miembros activos por grupo.