Topology: a live page drawn from the real gear
Lint / JS (eslint) (push) Successful in 21s
Lint / Python (flake8) (push) Successful in 1m20s
Lint / Notify on failure (push) Skipped
Lint / Deploy (push) Skipped
Security / Python Security (bandit) (push) Successful in 1m0s
Test / Python Tests (pytest) (push) Successful in 1m48s
Lint / Python (flake8) (pull_request) Successful in 1m44s
Lint / JS (eslint) (pull_request) Successful in 30s
Lint / Notify on failure (pull_request) Skipped
Lint / Deploy (pull_request) Skipped
Security / Python Security (bandit) (pull_request) Successful in 1m42s
Test / Python Tests (pytest) (pull_request) Successful in 1m16s

The dashboard's hand-drawn diagram was out of date. /topology replaces it
with the network as the switches report it, every device drawn to scale
from its faceplate or cutsheet front, and one cable per physical link
leaving the port it is plugged into.

- topology.py builds the graph: switch-to-switch cables seen from both ends
  are merged, servers get one cable per NIC, the gateway's internet port
  goes to the modem and on to the internet, unknown neighbours are stubs,
  and gear with no live cable is drawn where it was last seen.
- Ports named after a different device than the one plugged in are flagged.
- Cables show medium, speed, state and traffic; click one for its details,
  hover a device to trace its path to the internet; pan, zoom and filters.
- The monitor now keeps host_macs (MAC to host NIC) in link_stats.
- The old dashboard diagram and its JS and CSS are removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-14 19:30:59 -05:00
co-authored by Claude Opus 5.5
parent 390748173c
commit aa7341af06
16 changed files with 1982 additions and 519 deletions
+37 -4
View File
@@ -19,11 +19,13 @@ A Proxmox/Ceph cluster lives or dies by its network, and network problems are sn
## Gallery
**Dashboard**: alert queue with linked tickets, a live topology, per-host interface status and the UniFi device inventory.
**Dashboard**: alert queue with linked tickets, per-host interface status and the UniFi device inventory.
![Dashboard](docs/img/dashboard.png)
![Topology diagram](docs/img/topology.png)
**Topology**: every device drawn from its real faceplate or chassis, with each cable leaving the port it is plugged into, styled by medium and speed, with live traffic.
![Topology](docs/img/topology.png)
![Host cards](docs/img/host-cards.png)
@@ -105,9 +107,8 @@ Ping-only (no node_exporter): **pbs** (10.10.10.3)
### Dashboard (`/`)
- Device search (see Device pages below)
- Active alerts first, then the WAN / Fiber panel, hosts, UniFi devices, topology, and recently resolved alerts
- Active alerts first, then the WAN / Fiber panel, hosts, UniFi devices, and recently resolved alerts
- Real-time host status grid with per-NIC link state (UP / DOWN / degraded)
- Network topology diagram (Internet → Modem → Gateway → Switches → Hosts)
- WAN / Fiber panel: WAN and PON state, Rx/Tx power, optics temperature, throughput, errors, gateway uptime and last restart, 7-day Rx trend, recent WAN outages
- UniFi device table (switches, APs, gateway)
- Active alerts table with severity, target, consecutive failures, ticket link
@@ -180,6 +181,34 @@ The rack front, drawn from the rack units set on cutsheet items, top first.
claim the same top unit, the one recorded first is drawn. Items without a rack unit are listed below.
- The rack keeps its own dark "hardware" palette in both themes.
### Topology (`/topology`)
The whole network as the switches see it now, top down: the internet, the modem, the gateway, then
each switch by how many hops it is from the gateway, the gear and unknown devices below them, and the
servers along the bottom. Power gear (PDU, UPS, power strip) sits in a rail on the right.
- **Drawn to scale from the real gear**: UniFi devices use their faceplates (the same drawings as the
port inspector and rack page), and servers use the **Front drawing** of their cutsheet item. Servers
without one are a plain box. Above each server is a strip of its physical NICs, so every cable lands
on the NIC it is plugged into; NICs marked unused are dimmed.
- **One line per physical cable**, leaving the exact port: a switch-to-switch cable is reported by both
switches and drawn once. A server with two links (10G and 1G) has two cables. Colour is the cable
type (DAC, multimode fibre, the provider's fibre, an SFP+ module that doesn't say which, copper) and
thickness is the speed. A cable that is down is dashed red.
- **Last seen**: a device with no live cable is drawn on the port it was last seen on, dotted red.
- **Unknown devices**: something plugged into a switch port that Gandalf can't name is a grey stub,
labelled with the port name (or its address), linking to that port.
- **Port names**: a ⚠ marks a port named after one device with a different one plugged in (a port
called "Large1 Management" with the AP on it). Generic names ("Port 4", "SFP+ 2", "Uplink") and
"Downlink to X" with X on the other end never flag.
- **Alerts**: a device with active alerts (not suppressed) gets a ring and a count in its worst
severity colour, and the NIC it is about is marked.
- Click a device for its page, or a port on a faceplate for that port. Click a cable for its details:
both ends, speed, cable type and module, traffic each way and how busy it is, errors and drops, and
its cutsheet record. Hovering a device traces its path to the internet.
- Drag to pan, scroll or pinch to zoom, **Fit** (or `0`) to see everything, `+` and `-` to zoom. Show
or hide unknown devices, power gear, traffic, cables slower than 10G, and everything without an
alert. The filters are remembered per browser. Refreshes every 30 seconds without moving the view.
- API: `GET /api/topology` returns `{nodes, links, warnings, updated}` (see `topology.py`).
### Health check (`/health`)
No login needed. Returns 200 when the database answers and the monitor has completed a check recently,
otherwise 503 with the failing check: `{"status": "degraded", "checks": {"db": "ok", "monitor": "stale",
@@ -738,6 +767,7 @@ gandalf/
├── monitor.py # Background daemon (Prometheus, UniFi, Pulse, alert logic)
├── modem.py # Read-only AT&T gateway status page client and parser
├── devices.py # Device inventory for search and device pages
├── topology.py # The topology graph: devices, cables, depth, last-seen links
├── cutsheet.py # Cutsheet validation, path tracing, plan-vs-actual checks, CSV
├── ticket_text.py # Markdown for tickets and recovery notes
├── db.py # Database operations (MariaDB via pymysql, thread-local conn reuse)
@@ -751,6 +781,8 @@ gandalf/
│ ├── cutsheet.js # Cutsheet page
│ ├── events.js # Alert history page
│ ├── rack.js # Rack drawing
│ ├── topology.js # Topology page: layout, cables, pan and zoom
│ ├── faceplates.js # UniFi faceplates drawn from each model's real layout
│ ├── fronts.js # Drawn fronts for gear without a live faceplate (NVR, server cases)
│ └── port-inspector.js # Switch front panel, port panel, path check, diagnostics
└── templates/
@@ -760,6 +792,7 @@ gandalf/
├── cutsheet.html # Cutsheet page and its editors
├── events.html # Alert history page
├── rack.html # Rack drawing
├── topology.html # Topology page
├── _modem_panel.html # WAN / Fiber panel, shared by the dashboard and modem page
└── suppressions.html # Suppression management page
```