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 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 14:56:13 -05:00
co-authored by Claude Opus 5.5
parent a90ce44c80
commit c535bfd9fb
9 changed files with 383 additions and 3 deletions
+27
View File
@@ -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'),
+122
View File
@@ -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
+35
View File
@@ -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 = `<p class="attention-empty">Couldn't gather the list: ${lt.escHtml(e.message || e)}</p>`;
}
}
function renderAttention(body, data) {
const esc = lt.escHtml;
body.innerHTML = ATTENTION_GROUPS.map(g => {
const rows = data[g.key] || [];
const list = rows.length
? `<ul class="attention-list">${rows.map(r => `
<li class="attention-item attention-${esc(r.severity)}">
<a class="attention-link" href="${esc(r.href)}">${esc(r.text)}</a>
${r.detail ? `<span class="attention-detail">${esc(r.detail)}</span>` : ''}
</li>`).join('')}</ul>`
: `<p class="attention-clear">✓ ${g.clear}</p>`;
return `<div class="attention-group attention-group-${g.key}">
<h3 class="attention-group-title">${g.title}${rows.length ? ` <span class="attention-count">${rows.length}</span>` : ''}</h3>
${list}
</div>`;
}).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' &&
+2
View File
@@ -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);
+67
View File
@@ -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); }
+5 -3
View File
@@ -5,6 +5,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
<meta name="theme-color" content="#030508">
<meta name="robots" content="noindex, nofollow">
<meta name="description" content="GANDALF: Global Advanced Network Detection And Link Facilitator">
<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='%23030508'/%3E%3Cpath d='M8 2l5 3v6l-5 3-5-3V5z' fill='none' stroke='%2300e5ff' stroke-width='1.5'/%3E%3C/svg%3E">
<title>{% block title %}Network Monitor{% endblock %} | GANDALF</title>
@@ -30,7 +31,7 @@
<!-- MOBILE NAV DRAWER -->
<div id="lt-nav-drawer" class="lt-nav-drawer" aria-hidden="true" role="dialog" aria-modal="true" aria-label="Navigation menu">
<div class="lt-nav-drawer-header">
<span class="lt-brand-title">GANDALF</span>
<span class="lt-brand-title" title="Global Advanced Network Detection And Link Facilitator">GANDALF</span>
<button type="button" class="lt-nav-drawer-close" id="lt-nav-drawer-close" aria-label="Close navigation">&#x2715;</button>
</div>
<nav class="lt-nav-drawer-links" aria-label="Mobile navigation">
@@ -81,7 +82,7 @@
class="lt-brand-title lt-glitch"
data-text="GANDALF"
aria-label="GANDALF home">GANDALF</a>
<span class="lt-brand-subtitle">Network Monitor // LotusGuild</span>
<span class="lt-brand-subtitle g-brand-expansion" title="GANDALF: Global Advanced Network Detection And Link Facilitator"><b>G</b>lobal <b>A</b>dvanced <b>N</b>etwork<br><b>D</b>etection <b>A</b>nd <b>L</b>ink <b>F</b>acilitator</span>
</div>
<!-- Desktop nav -->
@@ -229,7 +230,7 @@
<span class="lt-footer-sep">|</span>
<button type="button" class="lt-footer-hint" data-action="show-keyboard-help"><span class="lt-footer-key">[ ? ]</span> HELP</button>
</nav>
<span>GANDALF | TDS v1.2</span>
<span>GANDALF: Global Advanced Network Detection And Link Facilitator | TDS v1.2</span>
</footer>
{% if user.groups and 'admin' in user.groups and not maintenance %}
@@ -331,6 +332,7 @@
<button type="button" class="lt-modal-close" data-modal-close aria-label="Close">&#x2715;</button>
</div>
<div class="lt-modal-body">
<p class="g-help-about"><strong>GANDALF</strong>: <b>G</b>lobal <b>A</b>dvanced <b>N</b>etwork <b>D</b>etection <b>A</b>nd <b>L</b>ink <b>F</b>acilitator. It watches the UniFi switches and the hosts' links, works out what is plugged in where, and raises a ticket when something breaks.</p>
<table class="lt-table">
<thead><tr><th>Shortcut</th><th>Action</th></tr></thead>
<tbody>
+9
View File
@@ -30,6 +30,14 @@
</div>
</div>
<!-- ── Needs attention: every page's problems in one place ──────────── -->
<section class="g-section attention" id="attention" aria-labelledby="attention-title">
<div class="g-section-header"><h2 class="g-section-title" id="attention-title">Needs attention</h2></div>
<div class="attention-groups" id="attention-body" aria-live="polite">
<p class="attention-empty">Checking every page…</p>
</div>
</section>
<!-- ── Stats summary cards ──────────────────────────────────────────── -->
<div class="lt-stats-grid">
<div class="lt-stat-card{% if summary.critical %} lt-stat-card--alert{% endif %}"
@@ -370,6 +378,7 @@
<script>
// 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;
+30
View File
@@ -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
+86
View File
@@ -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': []}