Cutsheet trace mode and mismatch alerts
Lint / Python (flake8) (push) Successful in 1m8s
Security / Python Security (bandit) (push) Successful in 56s
Test / Python Tests (pytest) (push) Successful in 43s
Lint / Python (flake8) (pull_request) Successful in 50s
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 55s
Test / Python Tests (pytest) (pull_request) Successful in 50s
Lint / JS (eslint) (push) Successful in 16m17s
Lint / Notify on failure (push) Skipped
Lint / Deploy (push) Skipped

Trace a cord: pick a panel port, press Start, and unplug the cord at the
panel. The page polls a new admin-only endpoint that reads every switch
port's state from UniFi (cached 2 s), shows the one port that dropped
with a button to record the cable, and confirms when it's plugged back
in. Several ports dropping at once, or none within 3 minutes, is
explained rather than guessed at.

Mismatch alerts: the monitor runs the cutsheet check every poll. Each
mismatched installed run (wrong neighbor, no link, missing port, port
conflict) keeps one cable_mismatch event on its switch, resolved when
fixed, and opens a P4 ticket after cutsheet.mismatch_ticket_hours
(default 24, 0 never). Suppressing the switch or port stops the ticket.

Also fixes buttons with the hidden attribute still showing, which left a
Delete button on the new-cable form.

Closes #12

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 16:54:57 -05:00
co-authored by Claude Opus 5.5
parent cd602fdacf
commit 86aa29b378
11 changed files with 446 additions and 1 deletions
+68
View File
@@ -21,6 +21,7 @@ import requests
from urllib3.exceptions import InsecureRequestWarning
import db
import cutsheet
import devices
import modem as modem_api
@@ -943,6 +944,13 @@ class NetworkMonitor:
except Exception as e:
logger.error(f'Could not create modem history table: {e}')
# Cutsheet mismatches open a P4 ticket once they've lasted this long (0 = never ticket)
self.cutsheet_ticket_hours = (self.cfg.get('cutsheet') or {}).get('mismatch_ticket_hours', 24)
try:
db.ensure_cutsheet_schema()
except Exception as e:
logger.error(f'Could not create cutsheet tables: {e}')
# Last good Prometheus result, shown (as unknown) during a Prometheus outage
self._last_iface_states: Dict[str, Dict[str, bool]] = {}
@@ -1165,6 +1173,58 @@ class NetworkMonitor:
if tid:
db.set_ticket_id(event_id, tid)
# ------------------------------------------------------------------
# Cutsheet: documented cabling vs. what discovery sees
# ------------------------------------------------------------------
def _process_cutsheet(self, link_data: dict, suppressions: list) -> None:
"""Keep one event per mismatched cable run, and ticket the ones that last.
Events appear on the dashboard and the switch's page straight away; a
ticket waits for cutsheet.mismatch_ticket_hours, so recabling never pages.
"""
data = db.cutsheet_load()
items = {i['name']: i for i in data['items']}
switches = link_data.get('unifi_switches') or {}
found = cutsheet.problems(data['cables'], items, switches)
hours = self.cutsheet_ticket_hours
threshold = max(1, -(-int(hours * 3600) // max(1, self.poll_interval))) if hours else 0
current = set()
for p in found:
current.add((p['switch'], p['key']))
description = f'{p["label"]}: {p["detail"]} (path: {p["path"]})'
event_id, _, consec, ticket_id = db.upsert_event(
'cable_mismatch', 'warning', 'cutsheet', p['switch'], p['key'], description,
)
sup = (db.check_suppressed(suppressions, 'unifi_device', p['switch']) or
db.check_suppressed(suppressions, 'interface', p['switch'], p['port']))
if threshold and not sup and consec >= threshold and not ticket_id:
self._ticket_cable_mismatch(event_id, p, hours)
for target_name, target_detail in db.get_open_event_targets('cable_mismatch'):
if (target_name, target_detail) not in current:
db.resolve_event('cable_mismatch', target_name, target_detail)
def _ticket_cable_mismatch(self, event_id: int, p: dict, hours: float) -> None:
title = (
f'[{p["switch"]}][auto][production][issue][network][single-node] '
f'Cable {p["label"]} does not match the cutsheet'
)
desc = (
f'Cutsheet Mismatch\n{"=" * 40}\n\n'
f'Cable: {p["label"]}\n'
f'Switch port: {p["switch"]} port {p["port"]}\n'
f'Problem: {p["detail"]}\n'
f'Documented path: {p["path"]}\n'
f'Detected: {_now_utc()}\n\n'
f'This has not matched for at least {hours:g} hours.\n\n'
f'Either the cable was moved (update the cutsheet in Gandalf: /cutsheet#cable-{p["cable_id"]}) '
f'or it is plugged into the wrong place.'
)
tid = self.tickets.create(title, desc, priority='4')
if tid:
db.set_ticket_id(event_id, tid)
# ------------------------------------------------------------------
# Ping-only hosts (no node_exporter)
# ------------------------------------------------------------------
@@ -1579,6 +1639,7 @@ class NetworkMonitor:
db.set_state('last_check', _now_utc())
# 4. Collect link stats (ethtool + traffic metrics)
link_data = None
try:
link_data = self.link_stats.collect(self._instance_map)
db.set_state('link_stats', link_data)
@@ -1596,6 +1657,13 @@ class NetworkMonitor:
self._process_ping_hosts(suppressions, ping_states)
# Cutsheet: compare documented cabling with what was just discovered
if link_data is not None:
try:
self._process_cutsheet(link_data, suppressions)
except Exception as e:
logger.error(f'Cutsheet check failed: {e}', exc_info=True)
# WAN modem: isolated so a failure here can't stop the rest of the cycle
if self.modem:
try: