Volver a la wiki

Network Observatory - Documentación Técnica

Network Observatory - Documentación Técnica

Versión: 4.5.0 Fecha: 10-02-2026 Estado: ✅ Producción - Apache ECharts + VictoriaMetrics + Global Alerts

Resumen

Sistema de monitoreo de red en tiempo real integrado en CreaRack Pro. Incluye:

Cambios v4.4.0 (05-02-2026) - ASYNC METRICS WRITE (PERFORMANCE)

Fire-and-Forget VictoriaMetrics Writes:

Cambios v4.3.0 (05-02-2026) - GLOBAL SHINE

Global Brightness Toggle:

Cambios v4.2.0 (05-02-2026) - MINUTE RANGE + REFRESH PERSISTENCE

Minute-level Range Selector:

Refresh Interval Persistence:

Cambios v4.1.0 (05-02-2026) - UX IMPROVEMENTS

Animation Toggle (Ani button):

Time Range Multiplier:

Fixes:

Cambios v4.0.0 (05-02-2026) - GLOBAL ALERTS SYSTEM

Modelo centralizado de alertas globales:

UI del Alert Manager:

Threshold Lines globales:

Asteroids Red Alert Mode:

Cambios v2.3.0 (31-01-2026) - PING CONSOLE

Ping Console (Consola de Ping en Vivo):

Gráficas uniformes:

DataLabels en picos:

Cambios v2.2.0 (31-01-2026) - SETTINGS MODALS

Modales de configuración:

Reducción de espacio vertical:

Cambios v2.1.0 (31-01-2026) - UX IMPROVEMENTS

Auto-start de monitoreo:

Gráficas estables:

Selector de tiempo (Time Range):

Botones Enable/Disable:

Auto-save de configuración:

Modal para crear alertas:

Nuevo endpoint API:

Bug fixes:

Cambios v2.0.0 (31-01-2026) - REESTRUCTURACIÓN MAYOR

Nueva arquitectura Device-centric:

Código modular:

Nuevos endpoints API:

Backend sync Device → Target:

Cambios v1.2.0 (31-01-2026)

Cambios v1.1.0 (31-01-2026)

Acceso

Arquitectura

Stack Tecnológico

ComponenteTecnología
BackendDjango 6 + Ninja API
WebSocketDjango Channels
GráficosApache ECharts 5.5.0
SNMPpysnmp-lextudio 6.3
HTTP Clienthttpx
Base de datosPostgreSQL

Modelos de Datos

monitoring/models.py
├── MonitoringTarget      # Dispositivo/IP a monitorear
│   ├── ping_enabled      # Bool: Habilitar ping monitoring
│   ├── snmp_enabled      # Bool: Habilitar SNMP bandwidth
│   ├── http_enabled      # Bool: Habilitar HTTP health check
│   └── monitor_types     # Property: Lista de tipos habilitados
├── MetricSample          # Muestras individuales (granular)
├── AggregatedMetric      # Métricas agregadas por hora
├── MonitoringAlert       # Configuración de alertas
└── AlertEvent            # Historial de alertas disparadas

API Endpoints

Targets (CRUD)

MétodoEndpointDescripción
GET/api/monitoring/targetsListar targets
POST/api/monitoring/targetsCrear target
GET/api/monitoring/targets/{id}Obtener target
PUT/api/monitoring/targets/{id}Actualizar target
DELETE/api/monitoring/targets/{id}Eliminar target

Métricas y Ping

MétodoEndpointDescripción
POST/api/monitoring/targets/{id}/pingEjecutar ping y guardar métricas
GET/api/monitoring/targets/{id}/metricsMétricas históricas (params: metric_type, hours)
GET/api/monitoring/targets/{id}/historyHistórico agregado (params: metric_type, days)
GET/api/monitoring/targets/{id}/statsEstadísticas (uptime%, avg, min, max)

SNMP/Bandwidth

MétodoEndpointDescripción
POST/api/monitoring/targets/{id}/snmp/testTest conexión SNMP
GET/api/monitoring/targets/{id}/snmp/interfacesListar interfaces SNMP
POST/api/monitoring/targets/{id}/snmp/pollPoll métricas SNMP
GET/api/monitoring/targets/{id}/bandwidthHistórico bandwidth (Mbps)

HTTP Health Check

MétodoEndpointDescripción
POST/api/monitoring/targets/{id}/http/checkEjecutar HTTP check
GET/api/monitoring/targets/{id}/http/historyHistórico response times

Respuesta de HTTP check:

{
    "status": "up",
    "status_code": 200,
    "response_time_ms": 45.2,
    "content_length": 12456,
    "ssl_valid": true,
    "ssl_expires_days": 89,
    "redirect_url": null,
    "url_checked": "https://example.com/",
    "timestamp": "2026-01-31T17:00:00Z",
    "alerts_triggered": 0,
    "error": null
}

Alertas

MétodoEndpointDescripción
GET/api/monitoring/alertsListar alertas configuradas
POST/api/monitoring/targets/{id}/alertsCrear alerta
DELETE/api/monitoring/alerts/{id}Eliminar alerta
GET/api/monitoring/alerts/activeAlertas activas (sin resolver)
POST/api/monitoring/alerts/{id}/acknowledgeReconocer alerta

Tipos de condición soportados:

Overview

MétodoEndpointDescripción
GET/api/monitoring/overviewResumen general (up, down, avg latency)

WebSocket

Conexión

const ws = new WebSocket('ws://localhost:8000/ws/monitoring/');

Mensajes Client → Server

// Suscribirse a targets
{"type": "subscribe", "target_ids": [1, 2, 3]}

// Desuscribirse
{"type": "unsubscribe", "target_ids": [2]}

// Heartbeat
{"type": "ping"}

Mensajes Server → Client

// Actualización de métricas
{
    "type": "metric_update",
    "target_id": 1,
    "metrics": {"status": "up", "latency_ms": 15.2, "packet_loss": 0},
    "timestamp": "2026-01-30T22:00:00Z"
}

// Alerta disparada
{
    "type": "alert_triggered",
    "alert_id": 5,
    "alert_name": "High Latency",
    "target_id": 1,
    "target_name": "Google DNS",
    "value": 150.5,
    "timestamp": "2026-01-30T22:00:00Z"
}

Management Commands

Ping automático a todos los targets

# Una ejecución
python manage.py ping_targets

# Modo continuo (cada 10 segundos)
python manage.py ping_targets --continuous --interval 10

Limpieza de datos antiguos

# Eliminar métricas > 30 días y alertas resueltas > 90 días
python manage.py cleanup_metrics

# Personalizar retención
python manage.py cleanup_metrics --days 7 --alert-days 30

# Dry run (ver qué se eliminaría)
python manage.py cleanup_metrics --dry-run

Agregación de métricas

# Agregar últimas 24 horas en buckets de 1 hora
python manage.py aggregate_metrics

# Agregar más horas
python manage.py aggregate_metrics --hours 168

Crontab recomendado (producción)

# Ping cada 10 segundos (usar supervisor/systemd para modo continuo)
*/1 * * * * cd /app && python manage.py ping_targets

# Agregación cada hora
0 * * * * cd /app && python manage.py aggregate_metrics

# Limpieza diaria a las 3 AM
0 3 * * * cd /app && python manage.py cleanup_metrics

Frontend

Sistema de Pestañas

Menú Contextual

Click en un target del sidebar o en Overview muestra un menú con opciones:

Pestañas HTTP

Cada pestaña HTTP muestra:

Multi-View

Persistencia

Las pestañas abiertas se guardan en localStorage con key observatory_tabs y se restauran al recargar.

Apache ECharts - Configuración Centralizada

Todas las gráficas usan EChartsService (static/js/services/EChartsService.js) como factory centralizada. Esto significa que modificando un solo método o valor en EChartsService se ajustan las tres gráficas de cada dispositivo.

Configuración compartida (un cambio afecta a las 3 gráficas)

Qué se comparteMétodo / FuenteEfecto
Grid layoutgetBaseOptions()Márgenes idénticos (left:65, right:65, top:40, bottom:65)
TooltipgetBaseOptions()Formato hora es-ES, crosshair, estilo oscuro
DataZoom (scroll + slider)getDataZoom()Slider inferior y zoom con rueda del ratón
ToolboxgetToolbox()Zoom rect, reset, export PNG, data view
xAxis type: 'time'getBaseOptions()Auto-rango basado en datos, formato HH:mm
Threshold linesgetThresholdMarkLines()Estilo de líneas de alerta (colores por severidad)
Threshold areasgetThresholdMarkAreas()Zonas sombreadas de alerta

Sincronización entre gráficas (echarts.connect)

Las 3 gráficas de un dispositivo se conectan mediante echarts.connect() en ObservatoryCharts.js:connectDeviceCharts():

// Se ejecuta automáticamente al crear cada gráfica
echarts.connect([heartbeatChart, bandwidthChart, httpChart]);

Lo que sincroniza connect:

Lo que NO sincroniza (es independiente por gráfica):

Controles globales por dispositivo (Observatory Alpine.js)

Estos controles aplican a las 3 gráficas simultáneamente desde observatory.js:

ControlMétodoEfecto en las 3 gráficas
Range (01m, 1h, 6h, 24h)setGlobalTimeRange()Re-fetches datos con las mismas hours
Chart Style dropdownEChartsService.setChartStyle()Aplica estilo (line, area, bar, scatter…)
Animation (Ani)EChartsService.toggleAnimation()On/Off pulso visual en refresh
Show ValuesEChartsService.toggleDataLabels()Top 4 picos durante 3 segundos
Alert Lines (AL)EChartsService.toggleMarkLines()Muestra/oculta líneas de umbral
Pause/ResumeEChartsService.pauseDeviceCharts()Brush-zoom pausa las 3, resume las despausa
Reset ZoomresetDeviceZoom()Reset dataZoom 0-100% en las 3
Export PNGexportDeviceCharts()Exporta las 3 como PNG

Patrón de actualización (identico en las 3)

Las tres funciones de update siguen el mismo patrón — solo actualizan series data, dejando que ECharts auto-escale los ejes:

// Heartbeat
chart.setOption({ series: [{ data: latencyData }, { data: lossData }] });

// Bandwidth
chart.setOption({ series: [{ data: inData }, { data: outData }, { data: aggregateData }] });

// HTTP
chart.setOption({ series: [{ data: responseData }, { data: mirrorData }] });

Importante: Ningún updateX() modifica xAxis ni yAxis — esto garantiza que ECharts mantenga sincronía perfecta entre las 3 gráficas cuando están conectadas.

Colores por defecto

// Heartbeat
latency:    '#3b82f6'  // Azul
packetLoss: '#ff9800'  // Naranja

// Bandwidth
inbound:    '#4caf50'  // Verde
outbound:   '#2196f3'  // Azul
aggregate:  '#ff9800'  // Naranja (dashed, hidden by default)

// HTTP
response:   '#10b981'  // Esmeralda (con visualMap: verde → amarillo → rojo)

Estilos de gráfica disponibles

13 estilos configurables desde el dropdown, aplicables a cualquier gráfica:

EstiloDescripción
line-smoothLínea suave (default)
line-sharpLínea recta
line-thickLínea gruesa sin área
line-dotsLínea con puntos
area-solidÁrea sólida (estilo PRTG)
area-stackedÁrea apilada
area-gradientGradiente dual-color (estilo ECharts demo)
step / step-areaEscalón con/sin área
bar / bar-thinBarras normales/finas
scatter / scatter-largePuntos dispersos

Auto-Refresh

El sistema ejecuta automáticamente cada 10 segundos:

  1. Ping a todos los targets con ping_enabled
  2. SNMP poll a todos los targets con snmp_enabled
  3. HTTP check solo para targets con pestaña HTTP abierta (evita timeouts)
  4. Actualización de gráficas y métricas en pestañas abiertas
  5. Refresh de Multi-View tabs

Configuración SNMP

Para monitorear bandwidth de un dispositivo:

  1. Crear target con snmp_enabled: true
  2. En la pestaña Bandwidth, configurar:
    • Community: public (o la community string del dispositivo)
    • Port: 161 (puerto SNMP estándar)
    • Interface: índice de la interfaz a monitorear (1, 2, etc.)
  3. Click “Save Config”
  4. Click “Test SNMP” para verificar conectividad
  5. Click “Poll Now” para recolectar datos

SNMPv3 (v1.0.37)

Las credenciales v3 se almacenan en MonitoringTarget.config (JSONField):

{
  "snmp_version": "v3",
  "snmp_v3_username": "snmpuser",
  "snmp_v3_auth_protocol": "SHA256",
  "snmp_v3_auth_key": "authPassphrase",
  "snmp_v3_priv_protocol": "AES128",
  "snmp_v3_priv_key": "privPassphrase"
}

SNMPService.from_config() detecta v3 automáticamente y construye UsmUserData via build_snmp_auth(). Los dispositivos descubiertos con v3 en Auto-Provision propagan sus credenciales al crear el MonitoringTarget.

OIDs Soportados

Configuración HTTP

Para monitorear un endpoint HTTP/HTTPS:

  1. Crear target con http_enabled: true
  2. Abrir pestaña HTTP desde el menú contextual
  3. Configurar:
    • URL: Endpoint a monitorear (ej: https://example.com/health)
    • Method: GET o HEAD
    • Verify SSL: Activar para validar certificados
  4. Click “Save Config”
  5. Click “Check Now” para ejecutar check manual

Métricas recolectadas

Archivos Principales

monitoring/
├── __init__.py
├── models.py              # MonitoringTarget, MetricSample, etc.
├── api.py                 # Endpoints Django Ninja
├── views.py               # Vista observatory_view
├── urls.py                # URL /monitoring/
├── routing.py             # WebSocket routing
├── consumers.py           # MonitoringConsumer (WebSocket)
├── admin.py               # Admin interfaces
├── services/
│   ├── __init__.py
│   ├── ping_service.py    # PingService (icmplib)
│   ├── snmp_service.py    # SNMPService para bandwidth
│   ├── http_service.py    # HttpService para health checks
│   └── alert_service.py   # Evaluación de alertas
└── management/
    └── commands/
        ├── ping_targets.py      # Ping automático
        ├── cleanup_metrics.py   # Limpieza de datos
        └── aggregate_metrics.py # Agregación horaria

templates/monitoring/
└── observatory.html       # Página principal con todo el JS

static/js/vendor/
└── echarts.min.js         # Apache ECharts local (evita CSP)

Dependencias

# requirements.txt
pysnmp-lextudio>=6.3.0    # SNMP polling
icmplib>=3.0              # Ping nativo (sin subprocess)
httpx>=0.27.0             # HTTP client async
# Dockerfile
iputils-ping              # Comando ping en contenedor (fallback)

Notas de Desarrollo

Para continuar el desarrollo

  1. Leer este documento
  2. Revisar Documentation/archive/plans/NETWORK_OBSERVATORY_PLAN.md para el plan original
  3. Ejecutar la batería de pruebas en tests/monitoring/TEST_CHECKLIST.md

Completado en v2.1.0

Completado en v1.2.0

Pendiente de pulir

Última actualización: 10-02-2026 (v4.5.0 - Documentación sincronización centralizada de gráficas)

Véase también

Subir