From c535bfd9fb248ac9768f2fcfb029aaa384d8b6f3 Mon Sep 17 00:00:00 2001 From: Jared Vititoe Date: Sun, 15 Nov 2026 14:56:13 -0500 Subject: [PATCH] Dashboard: one Needs attention list from every page; say what GANDALF stands for attention.build gathers alerts, power faults, cutsheet mismatches, UniFi port names, undocumented links, labels to print and rack overlaps into Broken now and Tidy up, each linking to where it is fixed. /api/attention serves it; the dashboard renders it and refreshes it with everything else. The header, help dialog, footer and page description spell out Global Advanced Network Detection And Link Facilitator. Co-Authored-By: Claude Opus 5.5 --- app.py | 27 +++++++++ attention.py | 122 ++++++++++++++++++++++++++++++++++++++++ static/app.js | 35 ++++++++++++ static/cutsheet.js | 2 + static/style.css | 67 ++++++++++++++++++++++ templates/base.html | 8 ++- templates/index.html | 9 +++ tests/test_app.py | 30 ++++++++++ tests/test_attention.py | 86 ++++++++++++++++++++++++++++ 9 files changed, 383 insertions(+), 3 deletions(-) create mode 100644 attention.py create mode 100644 tests/test_attention.py diff --git a/app.py b/app.py index 27ff38a..3421f8a 100644 --- a/app.py +++ b/app.py @@ -22,6 +22,7 @@ from urllib.parse import quote, urlparse from flask import Flask, jsonify, make_response, redirect, render_template, request, send_file, url_for +import attention import cutsheet import db import devices @@ -1335,6 +1336,32 @@ def api_topology(): return jsonify(_topology_graph(events, sheet, feeds)) +@app.route('/api/attention') +@require_auth +def api_attention(): + """Everything that needs looking at, from every page, for the dashboard (see attention.build).""" + return jsonify(_attention()) + + +def _attention() -> dict: + events = db.get_active_events(limit=_PAGE_LIMIT) + _annotate_suppressions(events, db.get_active_suppressions()) + view, racks, feeds = None, {}, [] + try: + view = _cutsheet_view() + feeds = db.get_power_feeds() + all_racks = _racks(view['items']) + for rack in all_racks: + here = [i for i in view['items'] if not i.get('shelf') + and (i.get('rack') or all_racks[0]['name']) == rack['name']] + racks[rack['name']] = cutsheet.rack_layout(here, rack['units']) + except Exception as e: + logger.error(f'Cutsheet unavailable for the attention list: {e}') + sheet = {'items': (view or {}).get('items') or [], 'cables': (view or {}).get('cables') or []} + power = _topology_graph(events, sheet, feeds).get('power') or [] + return attention.build(events, power, view, racks) + + def _topology_graph(events: list, sheet: dict, feeds: list) -> dict: return topology.build_graph( _state_json('network_snapshot'), _state_json('link_stats'), _state_json('modem_stats'), diff --git a/attention.py b/attention.py new file mode 100644 index 0000000..fc00f65 --- /dev/null +++ b/attention.py @@ -0,0 +1,122 @@ +"""What needs looking at, gathered from every page into one list for the dashboard. + +Two groups: 'broken' is something not working right now; 'tidy' is housekeeping, where +the network works but the records or names don't match it. Each entry links to the page +where it is fixed. Pure functions, so the rules are easy to test. +""" +from typing import Dict, List, Optional + +GROUPS = ('broken', 'tidy') + + +def _plural(n: int, one: str, many: Optional[str] = None) -> str: + return f'{n} {one if n == 1 else (many or one + "s")}' + + +def _entry(group: str, severity: str, text: str, href: str, detail: str = '') -> dict: + return {'group': group, 'severity': severity, 'text': text, 'href': href, 'detail': detail} + + +def _alerts(events: List[dict]) -> List[dict]: + live = [e for e in events if not e.get('is_suppressed') and e.get('severity') != 'info'] + if not live: + return [] + critical = sum(1 for e in live if e.get('severity') == 'critical') + targets = sorted({str(e.get('target_name') or '') for e in live if e.get('target_name')}, key=str.lower) + text = _plural(len(live), 'active alert') + if critical: + text += f' ({critical} critical)' + shown = ', '.join(targets[:4]) + (f' and {len(targets) - 4} more' if len(targets) > 4 else '') + return [_entry('broken', 'bad' if critical else 'warn', text, '#events-table-wrap', shown)] + + +def _power(power: List[dict]) -> List[dict]: + out = [] + for src in power or []: + name = src.get('node') or '' + if src.get('stale_since'): + out.append(_entry('broken', 'warn', f'{name}: outlet watts are frozen', '/topology', + 'UniFi keeps sending the same per-outlet readings; the total is still live. ' + 'Restarting the unit usually clears it.')) + for o in src.get('outlets') or []: + if not o.get('on') and o.get('target'): + out.append(_entry('broken', 'bad', f'{name} outlet {o.get("index")} is off, and it feeds {o["target"]}', + '/topology')) + idle = [] + for src in power or []: + for o in src.get('outlets') or []: + # Drawing real power, but nothing in Gandalf says what is plugged in + if o.get('on') and not o.get('target') and o.get('match') != 'cleared' and (o.get('power_w') or 0) >= 5: + idle.append(f'{src.get("node")} {o.get("index")}') + if idle: + out.append(_entry('tidy', 'info', f'{_plural(len(idle), "powered outlet")} with no device assigned', + '/topology', ', '.join(idle[:6]) + (' ...' if len(idle) > 6 else ''))) + return out + + +def _cutsheet(view: dict) -> List[dict]: + out = [] + cables = [c for c in view.get('cables') or [] if c.get('status') != 'retired'] + bad = [c for c in cables if c.get('problem')] + if bad: + names = ', '.join(c.get('label') or f'#{c["id"]}' for c in bad[:5]) + out.append(_entry('broken', 'bad', f'{_plural(len(bad), "cable")} not where the cutsheet says', + '/cutsheet?problems=1#cs-cables-section', names)) + + names = view.get('port_names') or [] + wrong = [r for r in names if r.get('kind') in ('wrong', 'moved')] + if wrong: + out.append(_entry('tidy', 'warn', f'{_plural(len(wrong), "UniFi port name")} pointing at the wrong device', + '/cutsheet#cs-portnames-section', + ', '.join(f'{r["switch"]} port {r["port_idx"]} "{r["port_name"]}"' for r in wrong[:3]))) + empty = [r for r in names if r.get('kind') == 'empty'] + if empty: + out.append(_entry('tidy', 'info', f'{_plural(len(empty), "named port")} with nothing plugged in', + '/cutsheet#cs-portnames-section', + ', '.join(f'"{r["port_name"]}"' for r in empty[:4]))) + + missing = view.get('suggestions') or [] + if missing: + out.append(_entry('tidy', 'info', f'{_plural(len(missing), "live link")} not on the cutsheet', + '/cutsheet#cs-suggest-section')) + + labels = view.get('labels') or {} + todo = len(labels.get('cables') or []) + len(labels.get('ports') or []) + if todo: + out.append(_entry('tidy', 'info', f'{_plural(todo, "label")} to print and stick on', + '/cutsheet#cs-labels-section')) + return out + + +def _rack(issues: Dict[str, dict]) -> List[dict]: + out = [] + for rack, r in (issues or {}).items(): + for o in r.get('overlaps') or []: + out.append(_entry('tidy', 'warn', f'{o["name"]} overlaps {", ".join(o["with"])} at {o["units"]}', + '/cutsheet#cs-items-section', rack)) + for o in r.get('outside') or []: + out.append(_entry('tidy', 'warn', f'{o["name"]} at {o["units"]} is outside {rack}', + '/cutsheet#cs-items-section')) + return out + + +def build(events: List[dict], power: List[dict], cutsheet_view: Optional[dict], + rack_issues: Optional[Dict[str, dict]] = None) -> dict: + """{'broken': [entry], 'tidy': [entry]}, worst first within each group. + + events: active alerts, annotated with 'is_suppressed'. power: topology.build_power output. + cutsheet_view: the cutsheet API view (cables with 'problem', suggestions, port_names, + labels), or None when the cutsheet couldn't be loaded. rack_issues: {rack: rack_layout()}. + Entry: {group, severity: bad|warn|info, text, href, detail}. + """ + entries = _alerts(events) + _power(power) + if cutsheet_view is not None: + entries += _cutsheet(cutsheet_view) + entries += _rack(rack_issues or {}) + rank = {'bad': 0, 'warn': 1, 'info': 2} + out = {g: [] for g in GROUPS} + for e in entries: + out[e['group']].append(e) + for g in GROUPS: + out[g].sort(key=lambda e: rank[e['severity']]) + return out diff --git a/static/app.js b/static/app.js index 4c50b1b..34c606e 100644 --- a/static/app.js +++ b/static/app.js @@ -43,6 +43,7 @@ async function refreshAll() { lt.api.get('/api/network'), lt.api.get('/api/status'), refreshModem(), + refreshAttention(), ]); if (netResult.status === 'fulfilled') { const net = netResult.value; @@ -68,6 +69,40 @@ async function refreshAll() { } } +// ── Needs attention ─────────────────────────────────────────────────── +const ATTENTION_GROUPS = [ + { key: 'broken', title: 'Broken now', clear: 'Nothing broken' }, + { key: 'tidy', title: 'Tidy up', clear: 'Records match the network' }, +]; + +async function refreshAttention() { + const body = document.getElementById('attention-body'); + if (!body) return; + try { + renderAttention(body, await lt.api.get('/api/attention')); + } catch (e) { + body.innerHTML = `

Couldn't gather the list: ${lt.escHtml(e.message || e)}

`; + } +} + +function renderAttention(body, data) { + const esc = lt.escHtml; + body.innerHTML = ATTENTION_GROUPS.map(g => { + const rows = data[g.key] || []; + const list = rows.length + ? `` + : `

✓ ${g.clear}

`; + return `
+

${g.title}${rows.length ? ` ${rows.length}` : ''}

+ ${list} +
`; + }).join(''); +} + // Active alerts flagged stale or with a closed ticket, plus tickets left open after clearing function followUpCount(events, staleTickets) { const flagged = events.filter(e => e.severity !== 'info' && diff --git a/static/cutsheet.js b/static/cutsheet.js index 95f51b3..63511da 100644 --- a/static/cutsheet.js +++ b/static/cutsheet.js @@ -757,6 +757,8 @@ function openFromQuery() { document.getElementById('cs-filter').addEventListener('input', () => _cs && renderCables()); document.getElementById('cs-status-filter').addEventListener('change', () => _cs && renderCables()); document.getElementById('cs-problems-only').addEventListener('change', () => _cs && renderCables()); +// The dashboard's "Needs attention" list links here with ?problems=1 +if (new URLSearchParams(window.location.search).get('problems')) document.getElementById('cs-problems-only').checked = true; if (CS_CAN_EDIT) { document.getElementById('cs-cable-form').addEventListener('submit', saveCable); document.getElementById('cs-item-form').addEventListener('submit', saveItem); diff --git a/static/style.css b/static/style.css index 99d9895..6ce3fe0 100644 --- a/static/style.css +++ b/static/style.css @@ -1680,3 +1680,70 @@ body.fp-marks-off .fp-svg .fp-mark { display: none; } .tp-pop select { width: 100%; } .tp-pop-hint { color: var(--text-muted); font-size: .9em; margin: 6px 0 8px; } .tp-pop-actions { display: flex; justify-content: flex-end; gap: 6px; } + +/* ── Needs attention (dashboard) ─────────────────────────────────── */ +.attention-groups { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; } +.attention-group { + background: var(--bg-card); + border: 1px solid var(--border-color); + padding: 10px 14px 12px; + min-width: 0; +} +.attention-group-title { + font-size: .78em; + font-weight: bold; + letter-spacing: .08em; + text-transform: uppercase; + color: var(--text-secondary); + margin: 0 0 8px; +} +.attention-group-broken .attention-group-title { color: var(--accent-red); } +.attention-count { + display: inline-block; + min-width: 1.6em; + padding: 0 5px; + margin-left: 4px; + border: 1px solid currentColor; + text-align: center; + font-size: .9em; +} +.attention-list { list-style: none; margin: 0; padding: 0; } +.attention-item { + position: relative; + padding: 5px 0 5px 16px; + border-top: 1px solid var(--border-color); + font-size: .86em; +} +.attention-item:first-child { border-top: 0; } +.attention-item::before { + content: ''; + position: absolute; + left: 2px; + top: .85em; + width: 7px; + height: 7px; + border-radius: 50%; + background: var(--text-muted); +} +.attention-bad::before { background: var(--accent-red); } +.attention-warn::before { background: var(--accent-amber); } +.attention-info::before { background: var(--accent-cyan); } +.attention-link { color: var(--text-primary); text-decoration: none; } +.attention-link:hover, .attention-link:focus-visible { color: var(--accent-cyan); text-decoration: underline; } +.attention-detail { + display: block; + color: var(--text-muted); + font-size: .9em; + overflow-wrap: anywhere; +} +.attention-clear { color: var(--accent-green); font-size: .86em; margin: 0; } +.attention-empty { color: var(--text-muted); font-size: .86em; margin: 0; } +@media (max-width: 768px) { + .attention-groups { grid-template-columns: 1fr; } +} + +/* ── Brand: what GANDALF stands for ──────────────────────────────── */ +.g-brand-expansion { letter-spacing: .08em; line-height: 1.35; } +.g-brand-expansion b { color: var(--accent-cyan); font-weight: 700; } +.g-help-about { font-size: .86em; color: var(--text-secondary); margin: 0 0 12px; line-height: 1.5; } +.g-help-about b { color: var(--accent-cyan); } diff --git a/templates/base.html b/templates/base.html index a4617d2..5d9c8a4 100644 --- a/templates/base.html +++ b/templates/base.html @@ -5,6 +5,7 @@ + {% block title %}Network Monitor{% endblock %} | GANDALF @@ -30,7 +31,7 @@ @@ -229,7 +230,7 @@ | - GANDALF | TDS v1.2 + GANDALF: Global Advanced Network Detection And Link Facilitator | TDS v1.2 {% if user.groups and 'admin' in user.groups and not maintenance %} @@ -331,6 +332,7 @@
+

GANDALF: Global Advanced Network Detection And Link Facilitator. It watches the UniFi switches and the hosts' links, works out what is plugged in where, and raises a ticket when something breaks.

diff --git a/templates/index.html b/templates/index.html index 3eeaf72..1b0d63d 100644 --- a/templates/index.html +++ b/templates/index.html @@ -30,6 +30,14 @@ + +
+

Needs attention

+
+

Checking every page…

+
+
+
// Load once even when auto-refresh is set to Off refreshModem(); + refreshAttention(); // Start auto-refresh using saved settings interval (default 30 s) const _savedInterval = window.gandalfSettings?.refreshInterval ?? 30; diff --git a/tests/test_app.py b/tests/test_app.py index e87b70e..f40c508 100644 --- a/tests/test_app.py +++ b/tests/test_app.py @@ -792,3 +792,33 @@ class TestPowerFeedApi: resp = client.put('/api/topology/power/RPDU/7', data='target=large1', headers=AUTH, content_type='application/x-www-form-urlencoded') assert resp.status_code == 400 + + +class TestAttention: + def test_needs_auth(self, client): + assert client.get('/api/attention').status_code == 401 + + def test_gathers_every_page(self, client): + gandalf._cutsheet_schema_ready = True + ev = {'id': 1, 'event_type': 'host_down', 'severity': 'critical', 'target_name': 'large1', + 'target_detail': '', 'description': ''} + with patch.object(gandalf.db, 'cutsheet_load', return_value={'items': [], 'cables': [], 'port_labels': []}), \ + patch.object(gandalf.db, 'get_active_events', return_value=[ev]), \ + patch.object(gandalf.db, 'get_power_feeds', return_value=[]), \ + patch.object(gandalf.db, 'cutsheet_racks', return_value=[]), \ + patch.object(gandalf.db, 'check_suppressed', return_value=False): + data = client.get('/api/attention', headers=AUTH).get_json() + assert set(data) == {'broken', 'tidy'} + assert data['broken'][0]['text'] == '1 active alert (1 critical)' + + def test_survives_a_cutsheet_failure(self, client): + gandalf._cutsheet_schema_ready = True + with patch.object(gandalf.db, 'cutsheet_load', side_effect=RuntimeError('db down')): + resp = client.get('/api/attention', headers=AUTH) + assert resp.status_code == 200 + assert set(resp.get_json()) == {'broken', 'tidy'} + + def test_dashboard_has_the_list_and_says_what_gandalf_stands_for(self, client): + html = client.get('/', headers=AUTH).get_data(as_text=True) + assert 'id="attention-body"' in html + assert 'Global Advanced Network Detection And Link Facilitator' in html diff --git a/tests/test_attention.py b/tests/test_attention.py new file mode 100644 index 0000000..5703e06 --- /dev/null +++ b/tests/test_attention.py @@ -0,0 +1,86 @@ +"""The dashboard's "Needs attention" list (attention.py).""" +import attention + + +def _alert(target, severity='critical', **kw): + return dict({'target_name': target, 'severity': severity, 'is_suppressed': False}, **kw) + + +def _outlet(index, on=True, target=None, power_w=10.0, match=None): + return {'index': index, 'on': on, 'target': target, 'power_w': power_w, + 'match': match or ('name' if target else 'none')} + + +class TestAlerts: + def test_one_line_for_all_alerts_with_the_targets(self): + out = attention.build([_alert('pbs'), _alert('24RJ45-POE', 'warning')], [], None) + [line] = out['broken'] + assert line['text'] == '2 active alerts (1 critical)' + assert line['severity'] == 'bad' + assert line['detail'] == '24RJ45-POE, pbs' + assert line['href'] == '#events-table-wrap' + + def test_suppressed_and_info_alerts_are_left_out(self): + events = [_alert('pbs', is_suppressed=True), _alert('large1', 'info')] + assert attention.build(events, [], None)['broken'] == [] + + def test_warnings_only_is_amber(self): + [line] = attention.build([_alert('x', 'warning')], [], None)['broken'] + assert line['severity'] == 'warn' and line['text'] == '1 active alert' + + +class TestPower: + def test_frozen_readings_and_an_off_outlet_feeding_a_device(self): + power = [{'node': 'RPDU', 'stale_since': '2026-11-15 05:26:54 UTC', + 'outlets': [_outlet(19, on=False, target='pbs'), _outlet(3, on=False)]}] + broken = attention.build([], power, None)['broken'] + assert [b['text'] for b in broken] == ['RPDU outlet 19 is off, and it feeds pbs', + 'RPDU: outlet watts are frozen'] + + def test_powered_outlets_with_nothing_assigned(self): + power = [{'node': 'RPDU', 'outlets': [ + _outlet(1, target='large1'), _outlet(2, power_w=40), _outlet(3, power_w=1), + _outlet(4, power_w=40, match='cleared'), _outlet(5, on=False, power_w=0)]}] + [line] = attention.build([], power, None)['tidy'] + assert line['text'] == '1 powered outlet with no device assigned' + assert line['detail'] == 'RPDU 2' + + +class TestCutsheet: + VIEW = { + 'cables': [{'id': 1, 'label': 'C01', 'status': 'installed', 'problem': True}, + {'id': 2, 'label': 'C02', 'status': 'retired', 'problem': True}, + {'id': 3, 'label': 'C03', 'status': 'installed', 'problem': False}], + 'suggestions': [{}, {}, {}], + 'port_names': [{'kind': 'wrong', 'switch': 'POE', 'port_idx': 11, 'port_name': 'Large1 Management'}, + {'kind': 'empty', 'switch': 'POE', 'port_idx': 20, 'port_name': 'WAP'}, + {'kind': 'unnamed', 'switch': 'POE', 'port_idx': 4, 'port_name': 'Port 4'}], + 'labels': {'cables': [{}, {}], 'ports': [{}]}, + } + + def test_every_cutsheet_todo(self): + out = attention.build([], [], self.VIEW) + assert [b['text'] for b in out['broken']] == ['1 cable not where the cutsheet says'] + assert out['broken'][0]['detail'] == 'C01' + assert out['broken'][0]['href'].startswith('/cutsheet?problems=1') + tidy = {t['text']: t for t in out['tidy']} + assert set(tidy) == {'1 UniFi port name pointing at the wrong device', '1 named port with nothing plugged in', + '3 live links not on the cutsheet', '3 labels to print and stick on'} + assert tidy['1 UniFi port name pointing at the wrong device']['detail'] == 'POE port 11 "Large1 Management"' + # Worst first + assert out['tidy'][0]['severity'] == 'warn' + + def test_unnamed_ports_alone_are_not_worth_a_line(self): + view = {'port_names': [{'kind': 'unnamed', 'switch': 'POE', 'port_idx': 4, 'port_name': 'Port 4'}]} + assert attention.build([], [], view) == {'broken': [], 'tidy': []} + + +class TestRack: + def test_overlaps_and_items_outside_the_rack(self): + racks = {'Rack 1': {'overlaps': [{'name': 'NAS', 'units': 'U5-6', 'with': ['storage-01']}], + 'outside': [{'name': 'Shelf', 'units': 'U43'}]}} + texts = [t['text'] for t in attention.build([], [], None, racks)['tidy']] + assert texts == ['NAS overlaps storage-01 at U5-6', 'Shelf at U43 is outside Rack 1'] + + def test_nothing_to_report(self): + assert attention.build([], [], {}, {}) == {'broken': [], 'tidy': []}
ShortcutAction