taskbot/docs/metrics-plan.md

Plan de métricas del bot

Este documento recoge:

1. Inventario de las métricas ya existentes en el código.
2. Clasificación de cada métrica:
   • core: queremos cuidarla y mantenerla estable.
   • nice-to-have: útil, pero no crítica; se puede ajustar.
   • debug: orientada a depuración / exploración.
   • dudosa: probablemente haya que redefinirla o eliminarla.
3. Propuesta de set “core v1” (existentes + nuevas).
4. Notas sobre persistencia y derivación desde BD.
5. Próximos pasos para implementación.

---

1. Inventario actual de métricas

Nota: solo se listan métricas usadas en código de producción (no tests ni docs).

1.1. HTTP / Webhook / Tráfico

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
webhook_events_total_*	counter	Webhook	evtNorm embebido en el nombre (*_xxx)	Contar eventos de webhook por tipo (messages.upsert, etc.).	core
webhook_errors_total	counter	Webhook	–	Errores procesando webhooks.	core
unknown_groups_discovered_total	counter	Webhook/grupos	–	Mensajes recibidos de grupos no conocidos en BD.	nice-to-have
messages_blocked_group_total	counter	Webhook/grupos	–	Mensajes bloqueados por venir de grupos no permitidos.	nice-to-have

1.2. Onboarding (grupos, DMs, asignaciones)

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
onboarding_prompts_sent_total	counter	Onboarding-grupos	group_id, source, reason	Prompts de onboarding enviados al grupo.	core (producto)
onboarding_prompts_skipped_total	counter	Onboarding-grupos	group_id, source?, reason	Casos donde se decide no enviar prompt al grupo.	core (producto)
onboarding_assign_failures_total	counter	Onboarding-asignac.	group_id, source, reason	Fallos al autoasignar tarea en onboarding.	nice-to-have
onboarding_dm_skipped_total	counter	Onboarding-DM	reason, group_id	Razones por las que NO se envía DM de onboarding.	core (producto)
onboarding_dm_sent_total	counter	Onboarding-DM	variant, part, group_id	DMs de onboarding efectivamente enviados.	core (producto)
onboarding_recipients_capped_total	counter	Onboarding-DM	group_id	Número de destinatarios que se quedaron fuera por cap.	nice-to-have
onboarding_bundle_sent_total	counter	Onboarding-DM	variant, group_id	“Bundles” de onboarding enviados.	nice-to-have
onboarding_dm_sent_abs	gauge	Onboarding-analytics	–	Valor absoluto de DMs enviados (derivado).	debug
onboarding_recipients_abs	gauge	Onboarding-analytics	–	Destinatarios totales (derivado).	debug
onboarding_converted_users_abs	gauge	Onboarding-analytics	–	Usuarios convertidos (derivado).	debug
onboarding_conversion_rate	gauge	Onboarding-analytics	–	Ratio de conversión calculado.	debug / dudosa

1.3. Reacciones / Cola de respuestas

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
reactions_enqueued_total	counter	Reacciones/cola	emoji	Reacciones encoladas para enviar.	nice-to-have
reactions_sent_total	counter	Reacciones/cola	emoji	Reacciones enviadas con éxito.	nice-to-have
reactions_failed_total	counter	Reacciones/cola	emoji	Reacciones que fallaron al enviar.	nice-to-have
responses_skipped_unresolvable_recipient_total	counter	Cola respuestas	reason (non_numeric, too_long, bad_domain…)	Respuestas descartadas por no poder resolver el JID.	debug (útil)

1.4. Recordatorios

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
reminders_skipped_outside_window_total	counter	Recordatorios	–	Recordatorios omitidos por estar fuera de ventana horaria.	dudosa (parcial)

1.5. Group sync / grupos / miembros

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
sync_runs_total	counter	Group sync	–	Número de ejecuciones de sync.	core (ops)
sync_errors_total	counter	Group sync	–	Errores en ejecuciones de sync.	core (ops)
sync_skipped_group_total	counter	Group sync	–	Grupos ignorados en la reconciliación (varios motivos).	nice-to-have
allowed_groups_labels_filled_total	counter	Group sync	–	Conteo de grupos donde se rellenaron labels de allowed_groups.	debug
active_groups	gauge	Group sync	–	Número de grupos activos cacheados.	core
active_members	gauge	Group sync	–	Conteo de miembros activos (BD).	core
last_sync_timestamp_seconds	gauge	Group sync	–	Marca de tiempo del último sync correcto.	core
last_sync_ok	gauge	Group sync	–	1 si último sync OK, 0 si falló.	core
last_sync_duration_ms	gauge	Group sync	–	Duración del último sync.	core
alias_coverage_ratio	gauge	Group sync	group_id	Cobertura de alias de identidad en el grupo.	debug/nice
allowed_groups_total_pending	gauge	Allowed groups	–	Grupos en estado pending.	core
allowed_groups_total_allowed	gauge	Allowed groups	–	Grupos en estado allowed.	core
allowed_groups_total_blocked	gauge	Allowed groups	–	Grupos en estado blocked.	core
group_sync_seconds_until_next	gauge	Group sync	–	Segundos hasta el próximo sync, o -1 si inactivo.	core

1.6. Identidad / alias

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
identity_alias_upsert_errors_total	counter	Identidad	–	Errores al hacer upsert de alias.	debug
identity_alias_upserts_total	counter	Identidad	–	Número de upserts de alias realizados.	debug
identity_alias_resolved_total	counter	Identidad	–	Alias resueltos correctamente.	debug
identity_alias_unresolved_total	counter	Identidad	–	Casos en los que no se pudo resolver alias.	debug

1.7. Administración (allow/block/list)

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
admin_actions_total_allow	counter	Admin	–	Acciones de “allow” hechas por admins.	nice-to-have
admin_actions_total_block	counter	Admin	–	Acciones de “block” hechas por admins.	nice-to-have
admin_actions_total_list	counter	Admin	–	Invocaciones a listados de allowed_groups.	nice-to-have

1.8. Comandos

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
commands_alias_used_total	counter	Comandos	`action=info	mias	...`
commands_unknown_total	counter	Comandos	–	Mensajes que no se mapean a ningún comando.	core (debug/ux)
commands_blocked_total	counter	Comandos	–	Comandos bloqueados (p.ej. grupo no permitido).	core (producto/ops)
ver_dm_transition_total	counter	Comandos	–	Veces que se hace transición a “ver por DM”.	nice-to-have
web_tokens_issued_total	counter	Web tokens	–	Número de tokens web emitidos.	nice-to-have

1.9. Mantenimiento / “evolution” (instancia WA)

Métrica	Tipo	Ámbito	Labels principales	Uso actual / intención	Categoría
evolution_instance_state_changes_total	counter	Evolution	instance	Número de cambios de estado de la instancia.	core (ops)
evolution_health_check_errors_total	counter	Evolution	instance	Errores en health checks.	core (ops)
evolution_instance_restart_attempts_total	counter	Evolution	instance	Intentos de reinicio de la instancia.	core (ops)
evolution_instance_restart_success_total	counter	Evolution	instance	Reinicios exitosos de la instancia.	core (ops)
evolution_instance_state	gauge	Evolution	instance, state	Estados actuales de la instancia (por valor de state).	core (ops)
evolution_instance_last_state_change_ts	gauge	Evolution	instance	Timestamp del último cambio de estado.	nice-to-have
evolution_instance_state_age_seconds	gauge	Evolution	instance	Tiempo en segundos en el estado actual.	nice-to-have

---

2. Propuesta de set “core v1” (existentes)

2.1. Operación / salud

Mantener como core:

• Webhook / HTTP:
  • webhook_events_total_*
  • webhook_errors_total
• Group sync:
  • sync_runs_total
  • sync_errors_total
  • active_groups
  • active_members
  • last_sync_timestamp_seconds
  • last_sync_ok
  • last_sync_duration_ms
  • group_sync_seconds_until_next
  • allowed_groups_total_pending
  • allowed_groups_total_allowed
  • allowed_groups_total_blocked
• Evolution / instancia WA:
  • evolution_instance_state_changes_total
  • evolution_health_check_errors_total
  • evolution_instance_restart_attempts_total
  • evolution_instance_restart_success_total
  • evolution_instance_state

2.2. Experiencia de usuario / producto

Mantener como core:

• Onboarding:
  • onboarding_prompts_sent_total
  • onboarding_prompts_skipped_total
  • onboarding_dm_sent_total
  • onboarding_dm_skipped_total
• Comandos:
  • commands_unknown_total
  • commands_blocked_total

---

3. Métricas existentes marcadas como “nice-to-have” o “debug”

3.1. Nice-to-have (mantener pero sin contrato fuerte)

• Webhook / grupos:
  • unknown_groups_discovered_total
  • messages_blocked_group_total
• Onboarding:
  • onboarding_assign_failures_total
  • onboarding_recipients_capped_total
  • onboarding_bundle_sent_total
• Reacciones:
  • reactions_enqueued_total / reactions_sent_total / reactions_failed_total
• Group sync:
  • sync_skipped_group_total
  • alias_coverage_ratio (si se usa en dashboards)
• Administración:
  • admin_actions_total_allow
  • admin_actions_total_block
  • admin_actions_total_list
• Comandos:
  • commands_alias_used_total
  • ver_dm_transition_total
  • web_tokens_issued_total
• Evolution:
  • evolution_instance_last_state_change_ts
  • evolution_instance_state_age_seconds

3.2. Debug / dudosas (candidatas a simplificar o eliminar)

• Onboarding analytics:
  • onboarding_dm_sent_abs
  • onboarding_recipients_abs
  • onboarding_converted_users_abs
  • onboarding_conversion_rate
• Identidad / alias:
  • identity_alias_upsert_errors_total
  • identity_alias_upserts_total
  • identity_alias_resolved_total
  • identity_alias_unresolved_total
• Cola de respuestas:
  • responses_skipped_unresolvable_recipient_total (debug útil → mantener como tal).
• Recordatorios:
  • reminders_skipped_outside_window_total (parcial: solo una razón de skip, sin contexto de enviados totales).

---

4. Métricas nuevas propuestas (faltantes importantes)

Nota: nombres sujetos a ajuste, pero la idea es que sean lo más “Prometheus-friendly” posible.

4.1. Tareas

• Counters (idealmente derivables de BD, o directamente desde DB en /metrics):

  • tasks_created_total
    • Definición: COUNT(*) FROM tasks.
  • tasks_completed_total
    • Definición: COUNT(*) FROM tasks WHERE completed = 1.

• Gauges (derivables de BD):

  • tasks_active
    • Definición: tareas no completadas (criterio exacto según modelo).
  • tasks_overdue
    • Definición: tareas no completadas con due_date < hoy.
  • (Opcional) tasks_active_by_group con label group_id solo si el número de grupos es manejable y se considera útil.

4.2. Mensajes y cola de respuestas

• Tráfico recibido (webhook):

  • bot_messages_received_total (counter, en memoria)
    • Labels: kind=text|reaction|system|other.

• Tráfico enviado por el bot (muy importante, idealmente persistente):

  • bot_messages_sent_total (counter, persistente o derivado de BD si posible)
    • Labels: kind=reply|reminder|onboarding|error|other.

• Cola de respuestas:

  • Counters:
    • response_queue_enqueued_total (por tipo de mensaje/reacción).
    • response_queue_sent_total.
    • response_queue_failed_total.
    • response_queue_retried_total.
    • response_queue_exhausted_total (cuando se dan por fallidos tras reintentos).
  • Gauges (desde BD):
    • response_queue_pending
      • COUNT(*) FROM response_queue WHERE status='pending'.
    • response_queue_oldest_age_seconds
      • now - MIN(created_at) de los pendientes.

4.3. Recordatorios (visión completa)

• Counters:

  • reminders_scheduled_total
    • Cuando se programa un recordatorio.
  • reminders_sent_total
    • Recordatorios enviados efectivamente.
  • reminders_failed_total
    • Intentos de envío de recordatorio fallidos.
  • reminders_skipped_total
    • Con labels reason=outside_window|user_opt_out|group_not_allowed|gating|invalid_time|other.

• Opcionalmente ratios calculables en dashboards:

  • reminders_skipped_total / (reminders_sent_total + reminders_skipped_total).

4.4. Uso de ICS / Web

• ICS:

  • ics_requests_total (counter)
    • Labels: type=personal|group|aggregate, status_class=2xx|4xx|5xx.

• HTTP genérico (si se desea):

  • http_requests_total
    • Labels: handler=webhook|metrics|ics|web_ui|..., status_class=2xx|4xx|5xx.

4.5. Otras métricas posibles (según prioridad)

• Usuarios / grupos (como gauges desde BD):
  • groups_total, groups_active_total.
  • group_members_total (activos).
  • users_total.
  • users_active_30d (si hay last_seen_at).

---

5. Persistencia vs. métricas derivadas

5.1. Derivadas desde BD (sin cambiar Metrics)

Buenas candidatas:

• tasks_* (created, completed, active, overdue).
• groups_* (total, active).
• group_members_total.
• allowed_groups_total_* (ya se hace).
• response_queue_pending, response_queue_oldest_age_seconds.

Ventaja: son persistentes por diseño, no dependen de reinicios del proceso.

5.2. Contadores en memoria (se reinician)

Buenas candidatas:

• Tráfico “reciente”:
  • bot_messages_received_total.
  • http_requests_total.
• Eventos de corto plazo:
  • sync_runs_total, sync_errors_total.
  • evolution_* (si además se pueden inferir de logs/BD, no es grave que se reinicien).

Estos están bien para tendencias recientes, SLIs y alertas basadas en tasas.

5.3. Contadores que probablemente queremos persistir

Lista corta para no complicar demasiado:

• bot_messages_sent_total
• reminders_sent_total
• (Opcional) webhook_events_received_total (si se agrega unificado, en lugar de solo por tipo).

Opciones:

1. Crear una tabla persistent_metrics(name TEXT PRIMARY KEY, value INTEGER NOT NULL).
2. Implementar funciones de “incremento persistente” que actualicen BD y, opcionalmente, el estado de Metrics.
3. Al renderizar /metrics, leer estos valores persistentes y exponerlos.

---

6. Próximos pasos sugeridos

1. Validar este set “core v1”:

   • Confirmar que las métricas “core existentes” listadas arriba son realmente las que quieres cuidar.
   • Elegir cuáles de las nuevas propuestas son imprescindibles en la primera iteración (p.ej. tareas + mensajes + cola + recordatorios).

2. Definir contrato de nombres:

   • Cerrar nombres finales de:
     • tasks_*
     • bot_messages_*
     • response_queue_*
     • reminders_*
     • ics_requests_total / http_requests_total.

3. Implementar por fases:

   • Fase 1: gauges derivadas de BD en /metrics (tareas, cola, grupos, etc.).
   • Fase 2: counters en memoria (mensajes recibidos/enviados, recordatorios, cola).
   • Fase 3: mecanismo de métricas persistentes y migrar los 2–3 contadores elegidos.

4. Limpiar / reclasificar métricas “debug/dudosas”:

   • Mantener responses_skipped_unresolvable_recipient_total como debug útil.
   • Simplificar o eliminar gauges de onboarding *_abs / conversion_rate si no se usan.
   • Revisar reminders_skipped_outside_window_total cuando exista el set completo de reminders_*.

Este documento sirve como referencia para saber qué métricas existen, cuáles son “de contrato” y cuáles se pueden tocar con menos miedo, además de qué huecos importantes hay que cubrir en próximas iteraciones.