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