Descripción
Modelo Django que representa una instancia del Local Agent conectada a la organización. Registra su identidad, estado de conexión, rol en la flota (primary/secondary) y telemetría operativa.
Campos
Identificación
| Campo | Tipo | Descripción |
|---|
agent_id | UUID, PK | Identificador único del Agent generado en el binario. |
organization | FK(Organization) | Organización propietaria del Agent. |
hostname | str(128) | Nombre del equipo donde corre (ej: OFICINA-PC). |
Estado de conexión
| Campo | Tipo | Descripción |
|---|
status | str(20) | “online” u “offline”. |
last_seen | DateTime | ISO 8601 del último heartbeat recibido. |
connected_at | DateTime | ISO 8601 de la conexión actual. |
disconnected_at | DateTime, nullable | ISO 8601 del último desconexión (NULL si online). |
Flota y redundancia
| Campo | Tipo | Descripción |
|---|
role | str(20) | “primary” o “secondary” — si es una flota de 2+ agentes. |
sentinel_active | bool | ¿Hay un monitor Sentinel conectado a este Agent? |
disconnects_7d | int, default=0 | Contador de desconexiones largas (gap ≥10 min) en los últimos 7 días. |
Versión del Agent
| Campo | Tipo | Descripción |
|---|
agent_version | str(20) | Versión del binario (ej: “2.18.0”). |
IP de la LAN (v2.16.1+)
| Campo | Tipo | Descripción |
|---|
ip_address | str(45), nullable | IP interna (IPv4/IPv6) del Agent. Reportada por /api/agent/agent_status y validada server-side. NULL si no disponible. |
Portabilidad del equipo (v2.15+)
| Campo | Tipo | Descripción |
|---|
has_battery | bool, nullable | ¿El equipo corre en un portátil? Reportado por /api/agent/agent_status. Usado por el Sentinel para avisos de batería baja. NULL si Agent < 2.15. |
Telemetría del proceso (v2.18.0 · v1.65.0 · task #209)
| Campo | Tipo | Descripción |
|---|
health | JSONField, nullable | Nuevo en v1.65.0: snapshot del bloque health del último heartbeat (cada 30s). Contiene métricas del propio proceso del Agent: cpu_percent (float 0–100), mem_mb (int), db_mb (float), pending_rows (int), last_sync_age_s (int). NULL si Agent < 2.18.0 o sin heartbeat reciente. Persistido saneado por el consumer (solo claves conocidas, rechaza payloads arbitrarios). |
Métodos públicos
mark_online()
Marca el Agent como online, actualiza last_seen y connected_at.
mark_offline()
Marca el Agent como offline, actualiza disconnected_at.
note_reconnect_gap(duration_seconds)
Registra una desconexión de larga duración (≥10 min) para el cálculo de disconnects_7d.
disconnects_7d (propiedad)
Retorna el número de desconexiones largas en los últimos 7 días (agregación de note_reconnect_gap).
Casos de uso
Fleet Manager (web)
- Lista todos los agentes con
status, agent_version, role, sentinel_active, last_seen y health.
- Columna “Footprint”: renderiza CPU/RAM si
health existe.
Observatory (web)
- Ficha del agente: muestra CPU, RAM, DB Size, Pending Sync si
health disponible.
API /api/agent/fleet
- Retorna array de
AgentInstanceOut (serialización de este modelo).
Dashboard home (línea marginal)
- Busca primer agente con
health y renderiza telemetría (refresco 30s).
Retrocompatibilidad
- Agents < 2.15: no reportan
ip_address, has_battery → campos NULL.
- Agents < 2.18.0: no reportan
health → campo NULL (modelo aún persiste sin error).
- Clientes sin permiso
fleet:view: no ven estos datos (403 en /api/agent/fleet).
Consideraciones de seguridad
- El campo
health es saneado por el consumer antes de persistir — rechaza dicts arbitrarios de payloads externos.
- Los campos
ip_address y hostname no contienen credenciales (la IP es interna y el hostname es público).
- Solo se expone en endpoints que requieren permiso
fleet:view o acceso a la organización.
Véase también
- [[entity—terminal—endpoint—fleet]] — endpoint que expone instancias de este modelo
- [[feature—terminal—agent-health-heartbeat]] — feature que introduce el campo
health
- [[concept—saas—multi-tenancy]] — aislamiento por organización
- [[entity—terminal—endpoint—agent-status]] — endpoint del Agent local que reporta
ip_address, has_battery, health