# 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) · **[User guide](../user-guide/README.md)** (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](../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

- [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

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

### P2 — Filters & fleet scope

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

### P3 — Investigation

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

### P4 — Shell & persistence

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

### P5 — Authoring model

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

### Also shipped

- [x] Weights / MC engine via `getWeights` RPC + `/api/v1|v2|v3/weights` (`server/services/weights.js`)
- [x] Related ranking boosted by alert weights when no MC window
- [x] Drag-reorder pinned charts
- [x] Keyboard shortcuts on Charts (`Space` play, `1–5` presets, `/` search, `f` force, `b` board, `c` correlate, `r` reset, `Esc` clear)
- [x] 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](../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](../user-guide/metric-correlations.md) · [related-metrics.md](../user-guide/related-metrics.md) · [weights-api.md](../user-guide/weights-api.md) · [logs.md](../user-guide/logs.md) · [charts.md](../user-guide/charts.md) (Filters menu).