Telemetría del Agente en el heartbeat — la ligereza, visible

Descripción

Task #209 — El Local Agent 2.18.0 ahora mide y reporta la telemetría de su propio proceso en el latido de cada 30 segundos. La promesa central del Agent — “máxima ligereza, mínimo impacto” — dejó de ser una declaración de marketing y pasó a ser un dato verificable en pantalla.

Lo que cambia

Agent-side (core/connector.py)

El heartbeat que el Agent envía al SaaS cada 30s ahora incluye un bloque health con cinco métricas del propio proceso:

• cpu_percent (0–100): normalizado al total de la máquina (multiplicado por el número de cores si reporta por core).
• mem_mb (entero): memoria residente (RSS) en MB.
• db_mb (entero): tamaño de metrics.db, la base de datos SQLite local que acumula métricas antes de subirlas.
• pending_rows (entero): métricas sin sincronizar hacia el SaaS (indicador temprano de buffers llenos).
• last_sync_age_s (entero): segundos desde el último sync exitoso a SaaS.

Se calcula en un thread (asyncio.to_thread) y es best-effort: si psutil falla o el acceso al store se bloquea, el heartbeat viaja sin el bloque health — la telemetría jamás puede tumbar el latido. El código es puro (sin I/O sincrónico bloqueante) y viaja como parte del paquete app-2.18.0.zip del auto-update (sin necesidad de recompilar el onedir).

SaaS-side (Django + Consumidor WebSocket)

Modelo: AgentInstance.health (JSONField, nullable)

• Migración terminal 0006 (v1.65.0).
• Snapshot del último heartbeat recibido.
• NULL = Agent < 2.18.0 (aún no envía el bloque).

Consumer (terminal/consumers.py):

• Persiste el bloque saneado — solo claves conocidas (cpu_percent, mem_mb, db_mb, pending_rows, last_sync_age_s) y valores numéricos.
• Rechaza dicts arbitrarios o payloads malformados (defensa contra Agent spoofed o roto).

Endpoint (GET /api/agent/fleet):

• Expone health en cada AgentInstanceOut si está presente.
• Permite que el frontend construya vistas sin retrasos extra.

Frontend

Fleet Manager (static/js/base.js):

• Nueva columna “Footprint” en la tabla de agentes.
• Muestra 0.3% CPU · 48 MB para agentes online con telemetría (2.18.0+).
• Fallback a ”—” si no hay dato (Agent viejo o sin heartbeat reciente).

Observatory (static/js/pages/observatory/ObservatoryAgent.js):

• Variante SaaS-side (HTTPS, sin acceso al Agent local):
  • Gana CPU, RAM, DB Size, Pending Sync en la ficha del agente.
  • Paridad de visibilidad que antes solo tenía la variante localhost.

Línea marginal del home (static/js/dashboard.js + static/css/pages/dashboard.css):

• Discreta y en tiempo real (refresco cada 30s).
• Formato: Local Agent · <hostname>: 0.3% CPU · 48 MB RAM · synced
  • O ... · <N> métricas en búfer si hay sync pendiente.
• Silenciosa por diseño:
  • No visible si no hay agentes en la flota.
  • No visible si el usuario no tiene permiso fleet:view (403 en la petición).
  • No visible si todos los agentes conectados son < 2.18.0 (sin health).
• Petición explícita de Edu en la sesión de diseño.

Internacionalización

Cuatro strings nuevos en locale/es/LC_MESSAGES/djangojs.po:

• synced → sincronizado
• %s metrics buffered → %s métricas en búfer
• CPU → CPU (no traducir, es etiqueta técnica)
• RAM → RAM (no traducir, es etiqueta técnica)

Nota: "Local Agent" es nombre de producto (glosario) — no se traduce.

Valor entregado

Para el MSP / vendedor

• Argumento de venta verificable: en el Fleet Manager, el cliente ve en vivo lo que consume la sonda en cada sede.
• Credibilidad: “máxima ligereza” deja de ser eslogan y se convierte en un número en pantalla.

Para operaciones

• Alerta temprana: una .db engordando o un buffer acumulándose se ven en el SaaS antes de que el cliente reporte un problema.
• Diagnóstico remoto: observar CPU/RAM/DB Size de múltiples agentes de golpe identifica rápidamente si uno está anomaloso.

Descartado en la misma charla

Polling adaptativo (“respiración”): la latencia de reacción al pedir un Observatory y el hecho de que casi siempre hay un dispositivo vigilado hacen que el ahorro energético no compense la complejidad; se reabiría solo con datos de flotas grandes (que esta misma feature aportará en el futuro).

Versiones

• Agent: 2.18.0
• SaaS: 1.65.0
• Fecha: 2026-07-31

Véase también

• [[entity—terminal—model—agentinstance]]
• [[entity—terminal—endpoint—fleet]]
• [[concept—terminal—agent-architecture]]
• [[feature—terminal—auto-update]]
• [[concept—saas—observability]]