message_bus/reports/0001-2026-06-07-unibus-grafana-monitoring.md

Report 0001 — Monitorización de unibus en Grafana/VictoriaMetrics

• Fecha: 07/06/2026
• Autor: agente (Claude Opus 4.8)
• Ámbito: projects/fleet_monitoring/ (exporter + dashboard + deploy) + 1 función nueva en el registry (functions/infra/). Solo lectura de projects/message_bus/apps/unibus/ (endpoint /healthz + CA).
• Estado: done (métricas de /healthz); gap declarado en métricas profundas NATS/JetStream.

Resumen

Se añadió monitorización del cluster de mensajería unibus (NATS+JetStream, 3 nodos: magnus, homer, datardos) a la stack de Grafana/VictoriaMetrics que ya corre en magnus, sin instrumentar el bus. Un nuevo daemon unibus_exporter sondea el endpoint público de salud de cada nodo (GET https://<nodo>:8470/healthz, TLS verificado con la CA del cluster) en un bucle de 15 s, traduce la respuesta a métricas Prometheus y las empuja a la VictoriaMetrics local de magnus. Un dashboard dedicado las visualiza. No se tocó nada del código de unibus ni la stack existente (Caddy/Gitea/VM/Grafana/fleet-agent intactos).

Qué métricas se recolectan y cómo

El /healthz de cada nodo devuelve, verificado en producción:

{"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}

De ahí se derivan estas series (labels node e instance = nombre del nodo, label común job=unibus_exporter):

Serie	Origen	Significado
unibus_up	exporter	1 si el nodo respondió /healthz, 0 si el GET/parseo falló
unibus_status_ok	healthz status	1 si status=="ok"
unibus_posture_enforce	healthz posture.enforce	enforcement de auth (1/0)
unibus_posture_acl	healthz posture.acl	ACL de subjects (1/0)
unibus_posture_tls	healthz posture.tls	TLS del transporte (1/0)
unibus_posture_cluster	healthz posture.cluster	modo cluster activo (1/0)
unibus_store_kv	healthz posture.store	1 si el store es kv (JetStream KV)
unibus_scrape_error	exporter	1 si el scrape de ese nodo falló
unibus_scrape_duration_seconds	exporter	latencia del GET /healthz
unibus_cluster_size	exporter (config)	nº de nodos configurados (los vivos = sum(unibus_up))

unibus_up=0 lo emite el exporter (no el parser) cuando el GET falla, para que un nodo caído sea visible en Grafana, no simplemente ausente.

Componentes entregados

Función del registry — parse_unibus_health_go_infra

• functions/infra/parse_unibus_health.go + .md + _test.go (grupo fleet-metrics, tags unibus).
• func ParseUnibusHealth(node string, body []byte) ([]PromSample, error) — pura de transformación (clasificada impure solo por el error de unmarshal). Tests golden/edge/error.
• Nota de proceso: el prompt pedía delegar esta función a fn-constructor, pero ese subagent_type no existe en este entorno. Tras confirmar con el usuario ("crear en el registry"), se creó a mano siguiendo el flujo (archivos + tests + fn index).

App — unibus_exporter (sub-repo Gitea propio)

• projects/fleet_monitoring/apps/unibus_exporter/: main.go, config.go, unibus.example.json, systemd/unibus-exporter.service, app.md, .gitignore.
• Compone parse_unibus_health + format_prom_exposition + push_prom_remote del registry (no reescribe push ni formato). Config JSON; secretos (CA, basic-auth) fuera de argv. Verifica TLS siempre contra la CA del cluster (sin InsecureSkipVerify).
• git init -b master + commit inicial hecho (apps/* está gitignored en el project; sin sub-repo el código se perdería). Falta crear el repo Gitea remoto: lo hará /full-git-push.

Dashboard — unibus-cluster.json

• projects/fleet_monitoring/hub/dashboards/unibus-cluster.json (formato de los fleet-*.json, datasource victoriametrics, carpeta Fleet, uid unibus-cluster, 9 paneles): nodos up, cluster size, nodos caídos, posture homogénea segura, up/down por nodo, matriz de posture por nodo (state-timeline enforce/acl/tls/cluster/store-kv × 3 nodos), latencia de scrape y tabla de estado por nodo. Panel "Meta-leader" preparado (muestra n/d sin métricas NATS).

Deploy — deploy_unibus_exporter.sh

• projects/fleet_monitoring/hub/deploy_unibus_exporter.sh: compila el binario linux/amd64, sube binario + CA del cluster a magnus (/opt/unibus-exporter, /etc/unibus-exporter/ca.crt chmod 600 la config) e instala el servicio systemd apuntando a http://127.0.0.1:8428/... (VM local, sin auth porque corre en el propio hub).

Verificación (evidencia ejecutable)

1. Acceso y healthz de los 3 nodos (CA del cluster por path):

$ curl -s --cacert .../deploy/tls/ca.crt https://135.125.201.30:8470/healthz
{"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}
   (idéntico en homer 141.94.69.66 y datardos 51.91.100.142)

2. Tests de la función:

$ go test -tags fts5 -run ParseUnibusHealth ./functions/infra/
ok  	fn-registry/functions/infra	0.004s
$ ./fn index   # → "Indexed 1450 functions ..."; ./fn show parse_unibus_health_go_infra → OK

3. Exporter build + scrape/push único de prueba (local → VM):

$ ./unibus_exporter -config <test> -once
unibus_exporter starting: nodes=3 hub="https://metrics-…/api/v1/import/prometheus" interval=15s
pushed 28 samples for 3 nodes        # 1 cluster_size + 3 nodos × 9 series

4. Daemon systemd en magnus:

$ systemctl is-active unibus-exporter   → active
$ systemctl is-enabled unibus-exporter  → enabled
$ journalctl -u unibus-exporter         → "pushed 28 samples for 3 nodes"

5. Series en VictoriaMetrics (magnus, 127.0.0.1:8428):

sum(unibus_up)        = 3
unibus_cluster_size   = 3
count(unibus_up==1)   = 3
unibus_posture_enforce: magnus=1 homer=1 datardos=1  (job=unibus_exporter)
unibus_store_kv:        magnus=1 homer=1 datardos=1
unibus_scrape_duration_seconds: magnus≈4ms homer≈32ms datardos≈19ms

6. Dashboard en Grafana (visto en el navegador):

• https://grafana-…/d/unibus-cluster — carpeta Fleet, 9 paneles renderizando datos reales.
• Nodos up: 3 · Cluster size: 3 · Nodos caídos: 0 · Posture homogénea segura: OK (enforce+acl+tls+cluster+kv) · matriz de posture: 15 celdas en verde · tabla de estado por nodo con ✓ en up/enforce/acl/tls.
• Captura: unibus-grafana-monitoring-dashboard.png (junto a este report).
• API: GET /api/dashboards/uid/unibus-cluster → dashboard CARGADO: unibus — Cluster | folder: Fleet | paneles: 9.

Gaps / pendientes

• Métricas profundas NATS/JetStream (msgs/s, conexiones, KV bucket msgs, RAFT leader por stream, NRestarts) — NO incluidas, gap recomendado. La vía es el monitoring embebido de NATS (puerto 8222), que se confirmó cerrado en los 3 nodos en producción (curl 127.0.0.1:8222/varz → CLOSED en magnus/homer/dd). Activarlo (bindeado a 127.0.0.1 + scrape local, o sacar /jsz por SSH) exige tocar la config/unit de los nodos del cluster, que además están siendo trabajados por otros agentes ahora mismo. Se decidió no forzarlo por riesgo en producción. Para abordarlo después: añadir UNIBUS_NATS_DEBUG/equivalente bindeado a loopback en cada nodo (cambio aditivo, coordinado con unibus/deploy/cluster/), un scrape local del /jsz+/varz y nuevas series unibus_jsz_*. El panel "Meta-leader" del dashboard ya está preparado para cuando exista unibus_meta_leader.
• unibus_cluster_size refleja el nº de nodos configurados en el exporter (3), no un recuento que el bus reporte (healthz no lo expone). Los nodos vivos se ven con sum(unibus_up).
• Commit en el repo padre fn_registry sin pushear (a propósito): la función nueva quedó commiteada en local (82f1f1bd, master ahead 1) pero no se hizo push del padre, para respetar el aislamiento pedido. El humano debería revisarlo y pushearlo (junto con fn index para regenerar registry.db, que está gitignored).
• Repo Gitea del exporter: apps/unibus_exporter tiene su git init + commit local pero aún no tiene remoto en Gitea; /full-git-push lo creará (dataforge/unibus_exporter).
• Vida útil (DoD capa 3): validado funcionalmente hoy; falta la ventana de uso real ≥7 días.