108 lines
4.0 KiB
Markdown
108 lines
4.0 KiB
Markdown
---
|
|
name: matrix-telemetry-bot
|
|
id: 0007
|
|
status: pending
|
|
created: 2026-05-16
|
|
updated: 2026-05-16
|
|
priority: high
|
|
risk: low
|
|
related_issues: [0085]
|
|
apps:
|
|
- data_factory
|
|
- dag_engine
|
|
- call_monitor
|
|
- agents_and_robots
|
|
trigger: webhook
|
|
schedule: ""
|
|
expected_runtime_s: 1
|
|
tags: [observability, alerts, matrix, sink]
|
|
---
|
|
|
|
## Goal
|
|
|
|
Probar agents_and_robots como sink universal de telemetria. Cada falla critica en cualquier app dispara un mensaje a sala Matrix `#fn-registry-ops`. Cierra el bucle observability del stack.
|
|
|
|
## Pre-requisitos
|
|
|
|
- Bot Matrix activo, joineado a `#fn-registry-ops`.
|
|
- `agents_and_robots` con accion `matrix_send_message` operativa.
|
|
- Variables expuestas como funcion del registry: `matrix_send_message_py_infra` o equivalente.
|
|
|
|
## Flow
|
|
|
|
Tres triggers distintos, mismo sink.
|
|
|
|
### Trigger 1: data_factory run failed
|
|
|
|
1. En `data_factory_record_run_py_pipelines`, si `status == 'failed'` -> tambien llama `matrix_send_message`.
|
|
2. Formato:
|
|
```
|
|
:rotating_light: <node_id> FAILED in <duration_ms>ms
|
|
error: <error[:200]>
|
|
```
|
|
|
|
### Trigger 2: dag_engine DAG final status
|
|
|
|
1. En executor de dag_engine, handler `on_failure` invoca `matrix_send_message`.
|
|
2. Formato:
|
|
```
|
|
:x: DAG <dag_name> run <run_id> FAILED
|
|
step <step_name> exit <code>
|
|
```
|
|
|
|
### Trigger 3: call_monitor anomaly
|
|
|
|
1. Cron 1h analiza `call_monitor.violations_24h`. Si > threshold (default 50):
|
|
```
|
|
:warning: violations_24h = <N> (threshold <T>) — top rules: <rule_ids>
|
|
```
|
|
2. Si `error_rate_7d > 0.1` para alguna funcion top -> alert.
|
|
|
|
## Acceptance
|
|
|
|
- [ ] `matrix_send_message_py_infra` existe en el registry (crear si no — usa agents_and_robots backend).
|
|
- [ ] Trigger 1 dispara mensaje cuando un node de data_factory falla deliberadamente.
|
|
- [ ] Trigger 2 dispara mensaje cuando un DAG falla (test con DAG que falla a proposito).
|
|
- [ ] Trigger 3 dispara mensaje cuando se inyectan violations sinteticas.
|
|
- [ ] Mensajes llegan en <3 segundos del evento.
|
|
|
|
## Telemetria esperada
|
|
|
|
- `function_stats.matrix_send_message_*`: calls dependientes de eventos reales.
|
|
- Sala Matrix recibe mensajes de los 3 origenes.
|
|
|
|
## Definition of Done
|
|
|
|
Ver `README.md` seccion DoD + user-facing.
|
|
|
|
### Generico
|
|
|
|
- [ ] **Repetibilidad**: 3 triggers (node fail / DAG fail / violations) disparan mensaje cada uno, 100x sin perdida.
|
|
- [ ] **Observabilidad**: cada envio en `call_monitor.calls`; cola persistente registra envios pendientes si Matrix down.
|
|
- [ ] **Error-path**: Matrix down → cola en operations.db; al reconectar drena en orden.
|
|
- [ ] **Idempotencia**: dedup: misma alerta 10x en 1min → 1 mensaje agregado, no flood.
|
|
- [ ] **Secrets**: bot token en `pass matrix/bot-token`.
|
|
- [ ] **Docs**: `## Notas` con onboarding + comandos para provocar trigger de prueba.
|
|
- [ ] **Registry-first**: `matrix_send_message_py_infra` registrado + reusado.
|
|
- [ ] **INDEX + status**: `status: done` + INDEX + movido.
|
|
|
|
### User-facing
|
|
|
|
- [ ] **User-facing**: usuario lee alerta en sala Matrix `#fn-registry-ops` con prefix emoji severidad + nombre app + link al dashboard de la app fallida.
|
|
- [ ] **User-facing repeat**: cada fallo real dispara mensaje en la sala; sala es el feed de salud diario del stack.
|
|
- [ ] **User-facing onboarding**: parrafo en `## Notas`: "Para enterarse de fallos: unirse a `#fn-registry-ops` (creds Matrix en `pass matrix/user`). Heartbeat 09:00 confirma bot vivo. Probar trigger: `./fn run inject_synthetic_violation`."
|
|
- [ ] **User-facing latencia**: evento → mensaje en <3s p95 (medido sobre 100 envios).
|
|
|
|
### Custom
|
|
|
|
- [ ] Severity routing: `critical` → `#fn-registry-ops`; `warning` → `#fn-registry-dev`.
|
|
- [ ] Self-test diario 09:00: bot envia heartbeat si vivo; ausencia heartbeat = alerta meta.
|
|
- [ ] Mensaje formateado con link al dashboard (no solo texto plano).
|
|
|
|
## Notas
|
|
|
|
- Throttling: max 1 mensaje/minuto por origen para evitar spam.
|
|
- Severidad: prefix emoji indica nivel.
|
|
- Mejora futura: comandos en sala (`!status`, `!ack <run_id>`) para responder desde Matrix.
|
|
- Pre-condicion: `agents_and_robots` necesita estar deployado + bot autenticado.
|