message_bus/reports/0016-2026-06-07-unibus-nats-metrics-clean.md

Report 0016 — unibus: métricas profundas de NATS/JetStream (limpio, sin debug-log)

• Fecha: 07/06/2026
• Autor: Claude (agente NATS metrics)
• Ámbito: projects/message_bus/apps/unibus (flag), functions/infra (parser del registry), projects/fleet_monitoring/apps/unibus_exporter (scraper), projects/fleet_monitoring/hub (dashboard + deploy)
• Estado: done (código + dashboard listos y probados; rollout al cluster pendiente, por diseño)

Resumen

Se añadieron las métricas server-level de NATS/JetStream (msgs/s, conexiones, slow consumers, memoria, KV bucket msgs, RAFT leader por stream, reinicios) a la monitorización del cluster unibus, de forma limpia: desacoplando el endpoint de monitoring del nats-server (puerto 8222) del debug-log verboso al que estaba acoplado.

El problema original: el monitoring 8222 solo se abría con UNIBUS_NATS_DEBUG=1, que enciende el log verboso del nats-server (rutas/RAFT/subjects de rooms a journald en claro), incompatible con el endurecimiento del issue 0007. La causa era únicamente cómo estaba escrito el toggle: monitoring y debug-log estaban acoplados sin necesidad.

La solución es un flag dedicado UNIBUS_NATS_MONITOR=1 que abre el monitoring loopback sin tocar el nivel de log, un scraper local por nodo (modo nuevo del unibus_exporter) que lee /varz, /connz, /jsz por loopback y empuja a VictoriaMetrics reusando las funciones del grupo fleet-metrics, y un dashboard Grafana unibus-nats. No se reinició el cluster (eso es el rollout consolidado del binario 0.11.0).

Cambios

Parte 1 — flag desacoplado en unibus (rama quick/nats-monitor-flag, pusheada)

Repo: dataforge/unibus. Commit 1c93251.

Archivo	Cambio
pkg/embeddednats/embeddednats.go	Función pura nueva natsLogOpts(debugEnv, monitorEnv) (noLog, debug, trace, monitor); StartServer la usa. El monitoring se abre con monitor (no con debug).
pkg/embeddednats/monitor_test.go	Tests del desacoplamiento (tabla pura) + server real con MONITOR=1 (8222 loopback) + server sin flag (cerrado).
deploy/cluster/membershipd-cluster.service.d/nats-monitor.conf	Drop-in systemd aditivo (Environment=UNIBUS_NATS_MONITOR=1).
deploy/cluster/README.md	Sección "NATS server metrics" con runbook de activación rolling + gate R3.
app.md	Bump 0.10.0 → 0.11.0 + growth log.

Diff esencial (lógica):

// natsLogOpts: pura, testeable. MONITOR=1 abre el endpoint dejando el log en silencio.
func natsLogOpts(debugEnv, monitorEnv string) (noLog, debug, trace, monitor bool) {
	debug = debugEnv == "1" || debugEnv == "2"
	trace = debugEnv == "2"
	monitor = monitorEnv == "1" || debug   // debug sigue implicando monitor (compat)
	noLog = !debug
	return noLog, debug, trace, monitor
}
// ...
opts.NoLog, opts.Debug, opts.Trace = noLog, debugNATS, traceNATS
if monitorNATS {
	opts.HTTPHost = "127.0.0.1"   // loopback hardcoded — el monitoring NUNCA es público
	opts.HTTPPort = 8222
}

El bind 127.0.0.1 se mantiene hardcoded: el endpoint no tiene auth y nunca debe ser alcanzable por red. El || debugNATS preserva el comportamiento viejo (DEBUG sigue abriendo el monitoring).

Función nueva del registry — parse_nats_monitor_go_infra

Creada vía fn-constructor en el repo padre (functions/infra/). Análoga a parse_unibus_health, mismo paquete infra, reusa el tipo PromSample.

func ParseNatsMonitor(node string, varz, connz, jsz []byte) ([]PromSample, error)

Convierte /varz + /connz + /jsz?streams=1 en []PromSample con labels node/instance. Robusta: /varz es el core (error si no parsea); /connz y /jsz best-effort. Series: ver tabla del dashboard abajo. Tag de grupo fleet-metrics (+ nats, jetstream, monitoring).

Parte 2a — modo NATS-local en unibus_exporter (rama quick/nats-deep-metrics, commit local)

Repo: dataforge/unibus_exporter (sub-repo sin remote aún). Commit dcdae92.

Segundo modo de scrape, componible con el modo healthz existente:

Archivo	Cambio
config.go	Bloque nats_monitor {enabled, node, base_url} + overrides UNIBUS_NODE/UNIBUS_NATS_URL; validación relajada (healthz, NATS o ambos).
main.go	scrapeNATS() lee loopback 8222 (/varz,/connz,/jsz?streams=1), llama ParseNatsMonitor, reusa FormatPromExposition + PushPromRemote. getJSON genérico.
nats_mode_test.go	scrapeNATS contra fixtures reales + varz caído + validación de config.
testdata/nats_{varz,connz,jsz}.json	Fixtures reales capturados de un nats-server 2.11.15.
systemd/unibus-exporter-nats.service	Unit del modo NATS-local (por nodo).
unibus.nats.example.json	Config de ejemplo nats-only.
app.md	Bump 0.1.0 → 0.2.0 + tabla de métricas NATS + growth log.

El modo healthz no se tocó. Como el monitoring de NATS es loopback-only y sin auth, este modo corre en cada nodo (un exporter local por nodo), distinto del exporter healthz central de magnus.

Parte 2b — dashboard + deploy (rama quick/nats-deep-metrics, pusheada)

Repo: dataforge/fleet_monitoring. Commit dfd55dc.

Archivo	Cambio
hub/dashboards/unibus-nats.json	Dashboard unibus-nats (uid), datasource victoriametrics, 12 paneles. Lo recoge el provider fleet existente (escanea el path de dashboards).
hub/deploy_unibus_nats_exporter.sh	Deploy del exporter en modo NATS-local por nodo. magnus → VM local sin auth; homer/datardos → ingesta pública con basic auth (pass fleet/ingest-pass, nunca en argv). Instala unibus-exporter-nats.service y sondea 8222 para avisar si el monitoring no está abierto. NO reinicia membershipd.

Verificación (evidencia ejecutable)

P1 — flag (unibus, CGO_ENABLED=0)

$ go build ./...                       → BUILD_EXIT=0
$ go test ./pkg/embeddednats/ -run 'TestNatsLogOpts|TestMonitor' -v
--- PASS: TestNatsLogOptsDecoupled (7 subcases: default off, monitor-only ⇒ log quiet,
          debug⇒monitor, trace⇒debug+monitor, both, garbage ignorado ×2)
--- PASS: TestMonitorEndpointLoopback   (server real MONITOR=1: /varz 200 en 127.0.0.1:8222)
--- PASS: TestMonitorDisabledByDefault  (sin flag: MonitorAddr nil, endpoint cerrado)
$ go test ./pkg/embeddednats/          → ok  5.953s  (suite completa, cluster_test incluido)

Función del registry (CGO_ENABLED=1 -tags fts5)

$ go test ./functions/infra/ -run 'ParseNatsMonitor|Battery'   → ok  0.004s
  Golden verifica: nats_msgs_in_total=17, nats_msgs_out_total=17, nats_mem_bytes=18288640,
  nats_jetstream_streams=3, kv_bucket_msgs{UNIBUS_users|rooms|members}=2,
  nats_jetstream_raft_leader{KV_UNIBUS_users}=1.
$ ./fn index    → Indexed 1451 functions (sin error en la función)
$ ./fn show parse_nats_monitor_go_infra → indexada OK

P2a — exporter (CGO_ENABLED=0)

$ go build ./...   → BUILD_OK
$ go vet ./...     → VET_OK
$ go test ./...    → ok  0.005s
  TestScrapeNATSFromFixtures, TestScrapeNATSVarzDown, TestConfigNatsModeValidation

E2E real — scraper contra un nats-server embebido vivo

Se levantó un nats-server embebido con el binario 0.11.0 real (UNIBUS_NATS_MONITOR=1, 8222 abierto, 3 KV buckets creados), se corrió el exporter en modo NATS-local apuntando a 127.0.0.1:8222 y empujando a un VictoriaMetrics simulado (receptor HTTP local). El exporter empujó 29 series reales, recibidas y verificadas:

unibus_exporter starting: nodes=0 nats="http://127.0.0.1:8222 (node=probe)" ...
pushed 29 samples (nodes=0 nats=true)

# series recibidas en el VM simulado (extracto):
nats_msgs_in_total{instance="probe",node="probe"} 17
nats_msgs_out_total{instance="probe",node="probe"} 17
nats_connections{instance="probe",node="probe"} 1
nats_mem_bytes{instance="probe",node="probe"} 1.855488e+07
nats_slow_consumers{...} 0
kv_bucket_msgs{bucket="UNIBUS_users",...} 2
kv_bucket_msgs{bucket="UNIBUS_rooms",...} 2
kv_bucket_msgs{bucket="UNIBUS_members",...} 2
nats_jetstream_raft_leader{stream="KV_UNIBUS_users",...} 1
nats_jetstream_streams{...} 3
nats_server_start_seconds{...} 1.78085962e+09
nats_up{...} 1   nats_scrape_error{...} 0

Esto valida toda la cadena: nats real → scrape loopback 8222 → ParseNatsMonitor → formato Prometheus → push a VictoriaMetrics. El harness y los temporales se limpiaron tras la prueba.

Dashboard

$ python3 -c "json.load(...)" → OK uid=unibus-nats title='unibus — NATS server' panels=12

Paneles: NATS up · conexiones · msgs/s in · slow consumers · JetStream msgs · reinicios (1h); msgs/s por nodo (in/out) · conexiones por nodo · KV bucket msgs por bucket · memoria por nodo; tabla "Leader RAFT por stream" · tabla "JetStream por nodo".

Runbook de activación (consolidada, HUMANO/orquestador — tras el rollout 0.11.0)

El monitoring requiere reiniciar membershipd (reinicia el miembro RAFT del nodo). Se hace dentro del rollout consolidado del binario 0.11.0, nunca dos nodos abajo a la vez.

1. Dependencia previa (registry): commitear la función nueva al registry y push directo a master (es aditivo, exento de TBD): functions/infra/parse_nats_monitor.{go,md,_test.go} + functions/infra/testdata/nats_*.json. Sin esto el exporter no compila en otro entorno.
2. Rollout del binario 0.11.0 a los 3 nodos en orden magnus → homer → datardos, instalando en cada uno el drop-in nats-monitor.conf + daemon-reload + restart membershipd-cluster. Entre cada nodo, esperar reconvergencia R3 (followers_current=2/2 en los 6 KV buckets) y healthz verde en el nodo reiniciado antes de pasar al siguiente (comandos en deploy/cluster/README.md § "NATS server metrics").
3. Desplegar el scraper por nodo (una vez que su 8222 está abierto): ./hub/deploy_unibus_nats_exporter.sh magnus om (y homer homer, datardos dd).
4. Provisionar el dashboard: copiar hub/dashboards/unibus-nats.json a /var/lib/grafana/dashboards en magnus (mismo mecanismo que unibus-cluster.json; el provider fleet lo recoge).
5. Verificar: series nats_*/kv_bucket_msgs en VictoriaMetrics y el dashboard unibus-nats en Grafana.

Gaps / pendientes

• Función del registry sin commitear (dependencia de integración): parse_nats_monitor está creada, indexada y testeada en el working tree del padre fn_registry, pero NO se commiteó (aislamiento: el prompt prohíbe tocar el padre; el orquestador la integra). Es el paso 1 del runbook. El exporter la importa, así que debe ir al registry antes de integrar el exporter.
• unibus_exporter sin remote Gitea: el sub-repo aún no está sincronizado a dataforge/. El commit dcdae92 quedó local en la rama quick/nats-deep-metrics; el push se hará vía /full-git-push (que crea el repo) o configurando el remote. Las otras dos ramas (quick/nats-monitor-flag en unibus, quick/nats-deep-metrics en fleet) sí están pusheadas.
• Validación contra el cluster vivo no realizada (por diseño): el scraper se validó e2e contra un nats-server embebido local con el binario 0.11.0 real, no contra magnus/homer/datardos. Activar UNIBUS_NATS_MONITOR en datardos habría exigido reiniciar un nodo RAFT de producción con otros agentes trabajando contra el cluster vivo — riesgo no justificado. Queda para el rollout.
• NRestarts por proceso/stream no lo expone NATS 8222: se emite nats_server_start_seconds como proxy (un cambio de su valor = el nats-server reinició; el panel "Reinicios (1h)" usa changes()). El contador de reinicios del proceso systemd (NRestarts) vendría de otra fuente.
• Nit de linter (cosmético): parse_nats_monitor.go usa HasPrefix+TrimPrefix donde el linter sugiere CutPrefix. No afecta corrección; opcional de pulir.
• Cluster NO reiniciado: magnus/homer/datardos intactos (8222 cerrado, healthz OK). Correcto según el encargo.

Ramas

Repo	Rama	Estado
dataforge/unibus	quick/nats-monitor-flag	commit 1c93251, pusheada (NO merge)
dataforge/fleet_monitoring	quick/nats-deep-metrics	commit dfd55dc, pusheada (NO merge)
dataforge/unibus_exporter	quick/nats-deep-metrics	commit dcdae92, local (sub-repo sin remote)
fn_registry (padre)	working tree	función parse_nats_monitor sin commitear (paso 1 del runbook)