Updates

2026-07-18 20:17:34 -04:00
parent 52a1823469
commit 41f5476a60
10 changed files with 1470 additions and 90 deletions
@@ -0,0 +1,124 @@
+# 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](./ROADMAP.md) Phase 6 · [DESKTOP.md](./DESKTOP.md) · [DATA-MODEL.md](./DATA-MODEL.md)
+
+---
+
+## Current state (baseline)
+
+| Surface | Today |
+|---------|--------|
+| Overview | Fixed 6-panel live grid + KPIs |
+| Charts | Flat searchable id list + single scalar detail canvas |
+| Time | Settings “points per chart” only |
+| Dimensions | Text dump; live path collapses to one number |
+| Alerts → chart | Jumps to Overview spotlight, not Charts wall |
+
+Backend already has `listCharts`, `queryData` (multi-dim labels), live `subscribeMetrics`, contexts REST — the desktop Charts UI under-uses them.
+
+---
+
+## 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 (in progress)
+
+- [x] Roadmap + this doc
+- [x] Long-scroll **metrics wall** (not one-chart-at-a-time)
+- [x] **Section TOC** (rail) with jump-to-section + search
+- [x] Charts ordered by **taxonomy section** + catalog priority/context
+- [x] **Global time bar**: play/pause, presets (1m / 5m / 15m / 1h / 6h)
+- [x] Per-card: title, units, loading/error/empty, multi-dim legend
+- [x] Lazy-load history for **visible** cards; live push into watched set
+- [x] Query uses `after` / `points` from the shared window
+- [x] Synced hover crosshair across visible cards (basic)
+- [x] 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) where units allow
+- [ ] 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
+
+### P3 — Investigation
+
+- [ ] Expand card: stats table (min/avg/max), dim table
+- [ ] Alert click → Charts wall, scroll to chart, pause at event time
+- [ ] Highlight window for “related metrics” (uses `/weights` when ready)
+- [ ] Anomaly tint / threshold line on wall cards
+
+### P4 — Shell & persistence
+
+- [ ] Persist pinned charts, collapsed sections, card heights
+- [ ] Custom board view reusing the same card component (later)
+- [ ] Wallboard / force-play mode (later)
+
+### P5 — Authoring model
+
+- [ ] Versioned `shared/taxonomy.js` (contexts → sections)
+- [ ] New collectors register context + priority used by TOC
+- [ ] Optional CI check: new contexts appear in taxonomy or “Other”
+
+---
+
+## Taxonomy sections (v1)
+
+| Section | Match (chart id / context / plugin prefixes) |
+|---------|-----------------------------------------------|
+| System | `system.*`, `cpu.*`, `mem.*`, `disk_*`, `net.*`, `ip.*`, `ipv*`, `system.*pressure*` |
+| Containers | `docker.*`, `cgroup.*`, `peardock.*` |
+| 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()` |
+| `ui/dashboard.js` | Metrics wall controller |
+| `ui/charts.js` | Canvas paint + hover helpers |
+| `index.html` | Charts view shell (TOC + wall + time bar) |
+| `ui/styles.css` | Metrics shell layout |
+| `app.js` | Wire catalog / samples / view switch |
+
+---
+
+## Exit criteria (P0)
+
+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 unchanged as the compact home grid.
@@ -9,8 +9,11 @@ The client shell is a **Pear desktop application** built with `pear-electron` +
 | `index.js` | Pear process entry — starts `pear-electron` Runtime + `pear-bridge` |
 | `index.html` | GUI main (`pear.gui.main`) — titlebar + panels |
 | `app.js` | UI logic (connect, fleet, live charts, invites) |
+| `ui/dashboard.js` | Charts tab master metrics wall |
+| `shared/taxonomy.js` | Section grouping for the metrics wall |
 | `ui/styles.css` | Layout, theme, **titlebar drag regions** |
 | `client/*` | HyperDHT connection stack used by the UI |
+| `docs/DASHBOARD.md` | Master Charts / metrics wall plan |

 ```bash
 npm start          # pear run -d .
@@ -109,6 +109,29 @@ Template rebrand, protocol, collector, memory store, anomalies, REST, desktop MV

 ---

+## Phase 6 — Master metrics dashboard (Charts tab)  ← **active**
+
+Turn Charts from a single-chart catalog into a full metrics wall (taxonomy TOC,
+shared time, multi-dim cards, investigation). Detail checklist:
+[DASHBOARD.md](./DASHBOARD.md).
+
+| Item | Status |
+|------|--------|
+| Taxonomy sections + group catalog by context/family | Done (`shared/taxonomy.js`) |
+| Long-scroll metrics wall + TOC jump links | Done (`ui/dashboard.js`) |
+| Global time bar (play/pause, presets) | Done |
+| Multi-dimension live + history cards | Done |
+| Lazy visible-card query / paint | Done |
+| Dim show/hide chips + basic synced hover | Done (P0) |
+| Pan/zoom / shared window from gestures | Planned (P1) |
+| Alert → scroll-to-chart | Done (pause-at-event TBD P3) |
+| Persist layout prefs / pinned charts | Planned (P4) |
+
+**Phase 6 exit (P0)** — Charts tab lists every agent chart in sections; shared
+time + play/pause; multi-dim series; Overview stays the compact home grid.
+
+---
+
 ## Suggested near-term sequence

 1. ~~HyperDB soak~~ ✅  
@@ -126,9 +149,11 @@ Template rebrand, protocol, collector, memory store, anomalies, REST, desktop MV
 13. ~~Webhook HMAC signing~~ ✅ (`X-PearData-Signature`)  
 14. ~~z-score / retrain job~~ ✅  
 15. ~~REST HyperDHT tunnel~~ ✅ (`PEARDATA_REST_TUNNEL=1`)  
-16. **Autobase multi-writer parents** — HA fleet history  
-17. **Windows collector depth** — close `/proc`-only gaps  
-18. **Plugin SDK polish** — public collector registration API 
+16. **Master metrics dashboard (Charts)** — Phase 6 P0 ← **now**  
+17. Dashboard P1 — sync crosshair / pan-zoom / dim picker  
+18. Autobase multi-writer parents — HA fleet history  
+19. Windows collector depth — close `/proc`-only gaps  
+20. Plugin SDK polish — public collector registration API

 ---

@@ -152,6 +177,7 @@ Template rebrand, protocol, collector, memory store, anomalies, REST, desktop MV
 | M4 | Historical scrub across restart (HyperDB warm) | ✅ |
 | M5 | Container charts from Docker hosts | ✅ opt-in spike |
 | M6 | Parent peer rolling up a fleet | ✅ opt-in spike |
+| M7 | Charts tab = sectioned master metrics wall | 🔄 Phase 6 |

 ---

@@ -159,6 +185,7 @@ Template rebrand, protocol, collector, memory store, anomalies, REST, desktop MV

 | Doc | Role |
 |-----|------|
+| [DASHBOARD.md](./DASHBOARD.md) | Master Charts / metrics wall plan |
 | [STORAGE-HYPERDB.md](./STORAGE-HYPERDB.md) | Warm store + swarm + Autobase |
 | [CI.md](./CI.md) / [RELEASE.md](./RELEASE.md) | Binary matrix + installer |
 | [TECH-CHOICES.md](./TECH-CHOICES.md) | Bare maps, collectors |