Wireless Monitor — Architecture & Technical Reference

Wireless Monitor — Architecture & Technical Reference

Versión: v1.0.27 (05-03-2026) Ruta: /monitoring/wireless/ Estado: v3 — Configurable chart grid, multi-radio, reports, real-time WS

Objetivo

Página dedicada para monitoreo de Access Points WiFi, separada de Observatory. Observatory está optimizado para dispositivos de red genéricos (switches, routers, firewalls) con ping/SNMP/HTTP. Wireless Monitor agrega datos específicos de WiFi: radios, SSIDs, clientes conectados, señal, y métricas vendor-specific.

Arquitectura

Principio: Reutilización máxima

No se creó ningún modelo ni app nueva. La página reutiliza 100% de la infraestructura existente:

Layout

Sigue el patrón Observatory: sidebar izquierdo + workspace con sistema de pestañas.

+-------------------+--------------------------------------------------+
|     SIDEBAR       |              WORKSPACE                           |
|                   |  [Dashboard] [AP-1] [AP-2] [×]  ← Tabs          |
| CreaRack-Pro      |                                                  |
| Wireless monitor  |  +---+ +---+ +---+ +---+                        |
|                   |  |119| |107| |2.2k| |Top|  ← Summary Cards      |
| Access Points 119 |  +---+ +---+ +---+ +---+                        |
| [Search...]       |                                                  |
| [Status ▼]        |  ┌─AP Table (sortable)─────────────────────────┐ |
| [Group ▼][Rack ▼] |  │ ● │ Name  │ IP   │ Vendor │ R │ Cl │FW    │ |
|                   |  │ ● │ AP-1  │ .42  │ Xirrus │ 8 │ 49 │8.5   │ |
|  ● AP-1 (49 cl)  |  │ ○ │ AP-2  │ .55  │ Cambium│ 3 │  0 │6.6   │ |
|  ○ AP-2 (0 cl)   |  └─────────────────────────────────────────────┘ |
|  ● AP-3 (15 cl)  |                                                  |
|                   |  == AP DETAIL TAB ==============================  |
|                   |  [Hardware: model, FW, serial, uptime, MAC]      |
|  [Report]         |  Charts  [1h][4h][12h][24h]        [Add Chart]  |
|  [Fleet Report]   |  ┌──────────────┐ ┌──────────────┐              |
|  [Refresh All]    |  │Station Count?│ │AP Bandwidth ?│              |
|                   |  │ ~~~~~~~~~~~~ │ │ ~~~~~~~~~~~~ │              |
|                   |  └──────────────┘ └──────────────┘              |
|                   |  ┌──────────────┐ ┌──────────────┐              |
|                   |  │Ch Util     ? │ │Noise Floor ? │              |
|                   |  │ ≈≈≈≈≈≈≈≈≈≈≈ │ │ ≈≈≈≈≈≈≈≈≈≈≈ │              |
|                   |  └──────────────┘ └──────────────┘              |
|                   |  [Radio Table] [SSID Table] [Client Table]      |
+-------------------+--------------------------------------------------+

Evolución

Configurable Chart Grid (v3)

Módulos

Métricas disponibles (9)

Chart Types

• area: Single line with gradient fill (Station Count, TX Power, Clients/Radio)
• dual-area: Two lines with legend — Inbound (green) + Outbound (blue) for bandwidth
• multi-area: Up to 8 lines, one per radio — 8-color palette (red, orange, yellow, green, cyan, blue, violet, pink)
• step: Step function for discrete values (Channel)

Features

• Add/Remove panels: Max 8 per AP, “Add Chart” button picks next unused metric
• Metric selector: Dropdown per panel to switch metric on the fly
• Time range pills: 1h | 4h | 12h | 24h — click reloads all panels with selected range
• Info tooltips: ? button per panel with descriptive text from CHART_REGISTRY[key].info
• Layout persistence: localStorage key wireless_chart_layout_v3_{profileId} — saved on add/remove/switch
• Default layout: ['station_count', 'throughput', 'channel_utilization', 'noise_floor']
• Loading overlay: “Loading…” → “Waiting for data…” if no data returned
• Available metrics filtering: Only metrics with matching OIDs in vendor’s monitoring_oids are shown
• Accent border: border-top: 2px solid var(--accent) on each panel

Multi-Radio Detection

Per-radio metrics (Channel Util, Noise Floor, etc.) use OID keys suffixed _1 through _8 (e.g., channel_utilization_1, channel_utilization_2). The available-metrics logic in WirelessDetail.js collapses these per-radio keys to their base key (e.g., channel_utilization) so the metric appears once in the selector, not 8 times.

VendorProfile.monitoring_oids:
  channel_utilization_1: ".1.3.6..."
  channel_utilization_2: ".1.3.6..."
  ...
  channel_utilization_8: ".1.3.6..."

→ Available metrics: ["channel_utilization"]  (collapsed)
→ Registry lookup: CHART_REGISTRY.channel_utilization.metricKeys = ["channel_utilization_1", ..., "channel_utilization_8"]
→ Chart: 1 line per radio that has data

WebSocket Real-Time (v2)

Data flow

Agent (Sentinel fast_snmp_loop, 15s)
  → WebSocket push to SaaS (MonitoringConsumer)
    → Forward to browser WS subscribers
      → WirelessChartGrid.handleRealtimeMetric()
        → Each panel checks if WS key matches its metricKeys
          → Appends data point to ECharts series

Metric key matching

• WS key arrives as snmp_fast_channel_utilization_1 or snmp_extras_noise_floor_3
• Panel strips prefix: snmp_fast_ or snmp_extras_ → channel_utilization_1
• Matches against config.metricKeys array to find series index

Green dot indicator

When a chart grid receives real-time WS data, the .chart-grid-label shows a pulsing green dot (CSS ::after pseudo-element via .ws-realtime-active class).

Auto Deep Discovery

• On tab open: Deep discovery triggers immediately when opening an AP detail tab
• Periodic refresh: Every 5 minutes for open AP tabs
• Status polling: Polls /profiles/{id}/deep-discover-status instead of fixed timeout
• Data table refresh: Radio/SSID/Client tables refresh from latest deep_snmp_data
• REST fallback: When Agent WS disconnected, browser sends tasks directly to Agent via POST localhost:5050/network/deep-discover

Reports (v3)

AP Report

Generated via GET /api/monitoring/wireless/report/{profileId}?hours=24:

1. Header: AP name, IP, vendor, model, firmware
2. Time range pills: 1h, 4h, 12h, 24h, 7d — re-generates report
3. Stats cards: Avg/Min/Max/P95 for Station Count, Bandwidth In/Out, Noise Floor, TX Power, Channel, Clients/Radio
4. Charts: Up to 7 static ECharts (no animation) for available metrics
5. Deep data tables: Hardware, Radios (pivot), SSIDs (pivot), Clients (pivot, max 50)
6. Export CSV: Client-side generation with timestamped filename
7. Print: Light theme for ECharts axes + CSS @media print for dark text/white background

Fleet Report

Generated via GET /api/monitoring/wireless/fleet-report?hours=24:

1. Summary cards: Total APs, Online, Offline, Total Clients
2. AP table: Name, IP, Status, Clients, Vendor, Model, Firmware
3. Export CSV + Print

Print Light Theme

_print() switches ECharts axis colors before window.print():

• xAxis label: rgba(255,255,255,0.5) → #666
• xAxis line: rgba(255,255,255,0.15) → #ccc
• yAxis label: rgba(255,255,255,0.5) → #666
• yAxis splitLine: rgba(255,255,255,0.06) → #e5e5e5

CSS @media print handles text colors, table styling, break-inside: avoid.

Fuentes de datos

1. DeviceProfile.deep_snmp_data (JSONField)

Estructura con categorías separadas por tipo de dato:

{
  "hardware": [
    {"name": "hostname", "index": "0", "value": "AP-01", "oid": "..."},
    {"name": "model", "index": "0", "value": "XR4836", "oid": "..."},
    {"name": "firmwareVersion", "index": "0", "value": "8.5.11", "oid": "..."}
  ],
  "wireless": [
    {"name": "radioName", "index": "1", "value": "iap1", "oid": "..."},
    {"name": "radioBand", "index": "0", "value": "2.4GHz", "oid": "..."},
    {"name": "associatedClients", "index": "1", "value": "12", "oid": "..."}
  ],
  "ssids": [
    {"name": "ssidName", "index": "0", "value": "Corporate", "oid": "..."},
    {"name": "ssidVlan", "index": "0", "value": "100", "oid": "..."}
  ],
  "clients": [
    {"name": "clientMac", "index": "0", "value": "AA:BB:CC:...", "oid": "..."},
    {"name": "clientSignal", "index": "0", "value": "-65", "oid": "..."}
  ]
}

2. VictoriaMetrics (time-series)

3. WebSocket (real-time)

4. Campos OID por vendor

5. Status determination

Si tiene MonitoringTarget → usar last_status (up→online, down→offline)
Si NO tiene MT pero last_verified < 2h → online (respondió a SNMP)
Si NO tiene MT pero tiene deep_snmp_data antiguo → offline
Si no tiene nada → unknown (gris)

Actualización v1.85.2 (ciclos 5 y 6 de la auditoría #261, 25-08-2026): se añadió WirelessLive (monitoring/api/wireless.py) como señal adicional — una consulta instantánea a VictoriaMetrics por petición sobre snmp_fast_station_count/snmp_extras_connected_clients (ventana 2×cadencia + margen). Un AP con SNMP fresco cuenta online aunque el ping falle (en el CCIB, donde la red filtra ICMP, esto afectaba a 47 APs), y sus clientes salen del dato vivo en vez de la foto del deep discovery, que pasa a ser solo respaldo. Mismo criterio aplicado también a /wireless/deep-data (antes tenía su propio cálculo sin frescura). Detalle completo en [[feature—wireless—clientes-vivos-ahora]].

Actualización v1.164.5 (28-09-2026, visto en PROD durante FABCON26): la agregación de SSIDs de get_wireless_group_summary (tabla de la ficha de un grupo) suma un segundo filtro además del de arriba — que el AP esté vivo no basta, la FOTO del deep discovery (deep_snmp_updated_at) también tiene que ser reciente (SSID_PHOTO_MAX_AGE, 60 min). Sin este filtro, un AP vivo con una foto de semanas atrás colaba en la tabla redes de eventos ya terminados. Detalle completo, con el contrato de la respuesta y los campos nuevos, en [[feature—wireless—clientes-vivos-ahora]].

Archivos

Backend

Frontend

Integration

Sistema de pestañas

Replica el patrón de Observatory:

1. Dashboard tab (siempre presente, no cerrable): summary cards + tabla AP + heatmap widget
2. AP tabs (dinámicas): click en sidebar/tabla → abre pestaña con detalle
3. Persistencia: localStorage key wireless_tabs_v2 guarda tabs abiertas y tab activa
4. Cleanup: al cerrar tab, se destruye WirelessChartGrid (dispone todos los ECharts)
5. Auto deep discovery: trigger al abrir tab + refresh cada 5 min

Multi-vendor rendering

WirelessDetail.js detecta automáticamente el vendor por los campos presentes:

• Si existe radioBand → estilo Cambium (Band, Channel, TxPower, Noise, Status, Clients)
• Si existe radioName → estilo Xirrus (Name, MAC, Clients, Speed)
• Columnas de tabla se adaptan dinámicamente (no se muestran columnas vacías)
• Client table: si hay 8 campos (Cambium) muestra tabla completa; si solo MAC (Xirrus) muestra lo disponible
• Signal con color-coding: verde >-60dBm, azul >-70, amarillo >-80, rojo <-80
• Security decode: Xirrus usa códigos numéricos (3=WPA2), Cambium usa texto
• Session time formateado: segundos → “2h 15m”

Auto-Provision integration

“Send to Wireless” (Step 3)

• Filtra perfiles seleccionados por device_type === 'access_point'
• Muestra conteo separado: “X Switches/Routers” + “Y Access Points”
• Toast de confirmación + redirección a /monitoring/wireless/
• Los APs enviados ya tienen deep_snmp_data si Deep Discovery estaba activo

API Endpoints

Roadmap (v4)

• Mapa de cobertura WiFi (APs posicionados en plano con círculos de señal)
• Alertas WiFi: AP con 0 clientes, canal solapado, señal degradada
• SNMPv3 polling para entornos de producción

Última actualización: 28-09-2026 Mantenido por: Claude (Anthropic) + Equipo CreaRack

Véase también

• [[crearack-tech—backend—network-observatory]]
• [[crearack-tech—backend—multi-vendor-snmp-guide]]
• [[crearack-tech—backend—network-tools]]
• [[crearack—monitoring—configurar-snmp]]
• [[crearack—redes-infra—monitorizacion]]
• [[feature—wireless—clientes-vivos-ahora]]