peardata/docs/DASHBOARD.md

Master metrics dashboard (Charts tab)

Product plan for turning the Charts tab into a full host/fleet metrics wall: sectioned TOC, every collected chart, synchronized time, and investigation controls.

Related: ROADMAP.md Phase 6 · DESKTOP.md · DATA-MODEL.md · User guide (operator walkthroughs)

---

Current state

Surface	Today
Overview	Compact 6-panel live grid + KPIs (auto-scaled RAM/net units); sparks + KPIs sync from history seed
Charts	Sectioned metrics wall (TOC + cards), shared time bar, multi-dim series
Processes	Live /proc table, KPIs, tree, detail drawer, CSV (user-guide/processes.md)
Containers	Docker/cgroup cards use human names (e.g. dozzle · CPU); ids stay docker.cpu.<shortId>
Time	Charts presets (1m–6h) + play/pause; UI thin-history advisory; agent retention via Settings → Data
Dimensions	Legend chips show/hide; chart type cycle (line/area/stacked/bar/pie)
Alerts → chart	Charts wall scroll-to-card + pause near event

Backend listCharts / queryData / live subscribe power the wall over HyperDHT RPC.

---

Guiding UX principles

1. Algorithmic coverage — every chart the agent emits appears automatically.
2. Taxonomy over dump — sections → families → charts ordered by priority/context.
3. One shared time window — play/pause + presets apply to the whole wall.
4. Visible-first — lazy query / paint only cards in (or near) the viewport.
5. Multi-dimension first — legends show/hide series; stacked when chart type says so.
6. P2P desktop — data via RPC (listCharts / queryData / subscribe), not REST.

Do not name third-party products in code, commits, or user-facing copy.

---

Phase 6 checklist

P0 — Foundation

• Roadmap + this doc
• Long-scroll metrics wall (not one-chart-at-a-time)
• Section TOC (rail) with jump-to-section + search
• Charts ordered by taxonomy section + catalog priority/context
• Global time bar: play/pause, presets (1m / 5m / 15m / 1h / 6h)
• Per-card: title, units, loading/error/empty, multi-dim legend
• Lazy-load history for visible cards; live push into watched set
• Query uses after / points from the shared window
• Synced hover crosshair across visible cards (basic)
• Alert click → Charts wall + scroll-to-card

P1 — Interaction parity

• Pan / zoom / reset on a card (updates shared window)
• Synced crosshair / shared hover time across visible cards
• Dimension show/hide + sort by name / latest value
• Chart type switch (line / area / stacked / bar / multibar / pie) — catalog default + sensible cycle
• Resize card height; persist prefs
• Section overview KPI strip (latest values) above detail charts

P2 — Filters & fleet scope

• Search by id or title / context / family / plugin
• Host/agent chip reseed on active peer switch
• Optional group aggregation UI (average / min / max / sum)
• Tier / resolution hint when HyperDB warm is used (card status)

P3 — Investigation

• Expand card: stats table (min/avg/max), dim table (click title)
• Alert click → Charts wall, scroll to chart, pause near event time
• Related metrics panel (context/family + Pearson — separate from MC)
• Metric Correlations (highlight brush → volume/ks2/anomaly-rate/value → filtered wall)
• Anomaly tint / threshold line on wall cards
• Alert → Correlate around event timestamp

P4 — Shell & persistence

• Persist collapsed sections, card heights, dim sort, chart types
• Persist pinned charts
• Board mode (pinned-only wall reusing the same cards)
• Wallboard / force-play mode
• Stale-while-revalidate paint (no refetch flicker)
• Retention-aware time presets (advisory thin-history hint; presets stay selectable)
• Live / Paused / Force indicator on Charts toolbar
• Dedicated Fleet tab (multi-host cards, set active / reconnect)

P5 — Authoring model

• Versioned shared/taxonomy.js (contexts → sections)
• EXTENDING.md documents taxonomy placement for new charts
• Taxonomy coverage test (test/taxonomy-coverage.test.js)

Also shipped

• Weights / MC engine via getWeights RPC + /api/v1|v2|v3/weights (server/services/weights.js)
• Related ranking boosted by alert weights when no MC window
• Drag-reorder pinned charts
• Keyboard shortcuts on Charts (Space play, 1–5 presets, / search, f force, b board, c correlate, r reset, Esc clear)
• Fullscreen chart focus (Charts wall + Overview) — double-click / ⛶, Esc / ← →

---

Taxonomy sections (v1)

Section	Match (chart id / context / plugin prefixes)
System	system.*, cpu.*, mem.*, disk_*, net.*, ip.*, ipv*, system.*pressure*
Containers	docker.*, cgroup.*, peardock.* — titles/families from Docker socket names (user-guide/containers.md)
Storage	zfs.*, bcache.*, dmcache.*, md.*, smart.*, fs.*
Hardware	sensors.*, gpu.*, ipmi.*, power*
Applications	nginx.*, apache.*, redis.*, mysql.*, postgres.*, memcached.*, mongodb.*, rabbitmq.*, kafka.*, nats.*, unbound.*
Network services	sockets.*, conntrack / softnet deep charts
Observability	ebpf.*, statsd.*, prometheus.*, peardata.*, self-monitor
Fleet	fleet.*, parent aggregates
Other	unmatched

---

File map (implementation)

Path	Role
shared/taxonomy.js	Section defs + groupCatalog()
shared/related-metrics.js	Related-chart ranking (taxonomy + Pearson)
server/services/weights.js	Metric Correlations scoring (ks2 / volume / AR / value)
ui/dashboard.js	Metrics wall controller + Correlate mode
ui/chart-focus.js	Fullscreen chart overlay (shared)
ui/charts.js	Canvas paint + hover helpers
ui/data-manager.js	Settings → Data (retention / prune / usage)
ui/logs.js	System Log tab (journal default)
shared/container-names.js	Docker/cgroup display names + card subtitles
shared/format.js	KPI unit scaling (MiB, kb/s, …)
index.html	Charts / Logs / Settings shells
ui/styles.css	Metrics shell layout
app.js	Wire catalog / samples / view switch

---

Exit criteria (P0) — met

1. Charts tab shows all catalog charts in collapsible sections.
2. TOC jumps scroll the wall; search filters TOC + wall.
3. Play/pause + time preset change refetch visible cards.
4. Multi-dimension charts draw every series (not a single scalar).
5. Overview remains the compact home grid.

Desktop polish (post Phase 6)

• Full-width metrics grid (auto-fit), single wall scrollbar, capped related panel
• Series fill plot width (X domain on series length); light X time ticks
• Legacy single-chart detail panel removed; dblclick expands stats + related
• Hover pad shared with Y-axis; hero-aware resize; hover paint batched via rAF
• Fleet cards show CPU/RAM chips when available; empty → Connect CTA
• Charts Filters menu (TOC / search / group / sort collapsed by default)
• Logs tab: journal (default) / anomaly / audit stream, Follow, search highlight
• Settings → Data: agent Data Manager (3m warm + 1 GiB budget default, auto-prune + GC, usage)
• Container cards: human names via Docker socket; subtitle hides bare hashes

Metric Correlations vs Related

	Correlate	Related (⇢)
Goal	Find metrics that changed vs a baseline around a highlight	Find charts related to a seed chart
Engine	Server weights.js (volume / ks2 / …)	Client taxonomy + Pearson
UX	Toolbar Correlate → brush ≥15s → Find Correlations → filtered wall	Per-card ⇢ / dblclick → related panel

Full operator docs: metric-correlations.md · related-metrics.md · weights-api.md · logs.md · charts.md (Filters menu).