fn_registry/dev/flows/0007-matrix-telemetry-bot.md

name, id, status, created, updated, priority, risk, related_issues, apps, trigger, schedule, expected_runtime_s, tags

name	id	status	created	updated	priority	risk	related_issues	apps	trigger	schedule	expected_runtime_s	tags
matrix-telemetry-bot	0007	pending	2026-05-16	2026-05-16	high	low	0085	data_factory dag_engine call_monitor agents_and_robots	webhook		1	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.