docs: add dashboard unification plan for panel titles, units, and groupings

Comprehensive proposal covering:
- Panel title standardization across Table/Index dashboards
- Unit unification (binBps vs Bps, percent vs percentunit)
- Row grouping consistency (Activity stats, Bloat stats positioning)
- Implementation priorities and checklist

Author: claude

PLAN_dashboard_unification.md

@@ -0,0 +1,352 @@
+# Dashboard Unification Plan
+
+This document outlines proposed improvements to unify panel titles, units, and groupings across all PostgresAI Grafana dashboards.
+
+---
+
+## Executive Summary
+
+After reviewing all 14 dashboards (22,700+ lines of JSON configuration), I identified several inconsistencies that impact user experience and maintainability:
+
+1. **Panel titles** use inconsistent naming conventions
+2. **Units** vary for similar metrics across dashboards
+3. **Row groupings** differ between related dashboards (e.g., Table Stats vs Index Health)
+
+---
+
+## 1. Panel Title Unification
+
+### 1.1 Current Issues
+
+#### Inconsistent "Top N" Panel Title Patterns
+
+| Dashboard | Current Title | Issue |
+|-----------|---------------|-------|
+| Dashboard 8 (Table Stats) | `Top $top_n tables by total size` | Uses "total size" |
+| Dashboard 10 (Index Health) | `Top $top_n indexes by size` | Uses just "size" |
+| Dashboard 8 (Table Stats) | `Top $top_n tables by size change rate (absolute)` | "(absolute)" suffix |
+| Dashboard 9 (Single Table) | `Table logical size distribution changes (absolute)` | Different pattern |
+
+#### Inconsistent Bloat Panel Naming
+
+| Dashboard | Current Title |
+|-----------|---------------|
+| Dashboard 9 (Single Table) | `Estimated bloat %` |
+| Dashboard 10 (Index Health) | `Top $top_n indexes by estimated bloat %` |
+| Dashboard 11 (Single Index) | No explicit bloat panel title (uses Boguk ratio) |
+
+#### Inconsistent IO Panel Naming
+
+| Dashboard | Current Title |
+|-----------|---------------|
+| Dashboard 10 (Index Health) | `Top $top_n indexes by reads (bytes)` |
+| Dashboard 10 (Index Health) | `Top $top_n indexes by hits (bytes)` |
+| Dashboard 11 (Single Index) | `Index reads and hits (bytes)` |
+| Dashboard 9 (Single Table) | `Shared block hits` / `Shared block reads` |
+
+### 1.2 Proposed Unified Title Patterns
+
+#### Pattern 1: Aggregated Dashboards (Multiple Objects)
+```
+Top $top_n {objects} by {metric}
+```
+Examples:
+- `Top $top_n tables by total size`
+- `Top $top_n indexes by size`
+- `Top $top_n tables by tuple inserts`
+- `Top $top_n indexes by block reads`
+
+#### Pattern 2: Single Object Dashboards
+```
+{Metric name}
+```
+Examples:
+- `Size distribution`
+- `Tuple operations`
+- `Block reads and hits`
+- `Estimated bloat`
+
+#### Pattern 3: Rate Metrics
+Add `/s` suffix for rates, not "(absolute)":
+- `Size change rate` → `Size growth /s`
+- `Tuple operations` (for rates)
+- Remove "(absolute)" from titles
+
+### 1.3 Specific Title Changes
+
+#### Dashboard 8 (Table Stats) - Aggregated
+| Current | Proposed |
+|---------|----------|
+| `Top $top_n tables by total size` | `Top $top_n tables by total size` (keep) |
+| `Top $top_n tables by size change rate (absolute)` | `Top $top_n tables by size growth /s` |
+| `Top $top_n tables by table (w/o TOAST) size` | `Top $top_n tables by heap size (excl. TOAST)` |
+| `Top $top_n tables by table (w/o TOAST) size change rate (absolute)` | `Top $top_n tables by heap size growth /s` |
+| `Top $top_n tables by TOAST size` | `Top $top_n tables by TOAST size` (keep) |
+| `Top $top_n tables by index size` | `Top $top_n tables by indexes size` |
+| `Top $top_n tables by tuple inserts (including TOAST)` | `Top $top_n tables by tuple inserts` |
+| `Top $top_n tables by tuple updates (HOT + non-HOT) (including TOAST)` | `Top $top_n tables by tuple updates` |
+| `Top $top_n tables by tuple deletes (including TOAST)` | `Top $top_n tables by tuple deletes` |
+| `Top $top_n tables by blk_reads in bytes` | `Top $top_n tables by block reads` |
+| `Top $top_n tables by blk_hits in bytes` | `Top $top_n tables by block hits` |
+
+#### Dashboard 9 (Single Table Analysis)
+| Current | Proposed |
+|---------|----------|
+| `Table logical size distribution` | `Size distribution` |
+| `Table logical size distribution changes (absolute)` | `Size growth /s` |
+| `Estimated bloat %` | `Bloat percentage (estimated)` |
+| `Estimated bloat size` | `Bloat size (estimated)` |
+| `Tuple operations` | `Tuple operations /s` |
+| `Tuple operations (%)` | `Tuple operations distribution (%)` |
+| `Live tuples fetch distribution` | `Tuple fetch methods /s` |
+| `Shared block hits` | `Block cache hits /s` |
+| `Shared block reads` | `Block disk reads /s` |
+| `Shared block hit ratio` | `Block cache hit ratio` |
+
+#### Dashboard 10 (Index Health) - Aggregated
+| Current | Proposed |
+|---------|----------|
+| `Top $top_n indexes by size` | `Top $top_n indexes by size` (keep) |
+| `Top $top_n indexes by tuples read` | `Top $top_n indexes by tuples read /s` |
+| `Top $top_n indexes by tuples fetched` | `Top $top_n indexes by tuples fetched /s` |
+| `Top $top_n indexes by reads (bytes)` | `Top $top_n indexes by block reads` |
+| `Top $top_n indexes by hits (bytes)` | `Top $top_n indexes by block hits` |
+| `Top $top_n indexes by estimated bloat %` | `Top $top_n indexes by bloat %` |
+| `Top $top_n indexes by estimated bloat size` | `Top $top_n indexes by bloat size` |
+
+#### Dashboard 11 (Single Index Analysis)
+| Current | Proposed |
+|---------|----------|
+| `Index size` | `Size` |
+| `Index scans` | `Scans /s` |
+| `Tuples read and fetched` | `Tuples read and fetched /s` |
+| `Index reads and hits (bytes)` | `Block reads and hits` |
+| (Boguk ratio panel has no title) | `Bloat analysis (Boguk ratio)` |
+
+#### Dashboard 1 (Node Performance Overview)
+| Current | Proposed |
+|---------|----------|
+| `TPS` | `Transactions /s` |
+| `QPS (pg_stat_statements)` | `Queries /s` |
+| `Query total time (pg_stat_statements)` | `Query execution time /s` |
+| `Query time per call (latency) (pg_stat_statements)` | `Query latency per call` |
+| `Tuples fetched and tuples returned per second` | `Tuple read operations /s` |
+| `Tuples operations per second` | `Tuple write operations /s` |
+| `blk_reads and blk_hits per second (bytes)` | `Block reads and hits /s` |
+| `blk_read_time and blk_write_time (s/s)` | `Block I/O wait time /s` |
+
+---
+
+## 2. Unit Unification
+
+### 2.1 Current Unit Inconsistencies
+
+| Metric Type | Units Found | Dashboards |
+|-------------|-------------|------------|
+| Byte rates | `binBps`, `Bps` | Mixed across all |
+| Percentages | `percent`, `percentunit` | Mixed across all |
+| Operations | `ops`, `ops/s`, `short` | Mixed |
+| Calls | `calls/s`, `ops/s` | Dashboard 2 |
+| Time | `s`, `ms`, `s/s`, `ms/s` | Mixed |
+
+### 2.2 Proposed Unit Standards
+
+| Metric Type | Standard Unit | Grafana Unit ID |
+|-------------|---------------|-----------------|
+| Byte sizes (absolute) | Bytes (IEC) | `bytes` |
+| Byte rates (throughput) | Bytes/sec (IEC) | `binBps` |
+| Percentages (0-100 scale) | Percent (0-100) | `percent` |
+| Percentages (0-1 scale) | Percent (0.0-1.0) | `percentunit` |
+| Operations per second | ops/sec | `ops` (with /s in title) |
+| Time durations | Seconds | `s` |
+| Time rates | Seconds per second | `s` (with ratio in title) |
+| Latencies | Milliseconds | `ms` |
+| Row counts | Short | `short` |
+
+### 2.3 Specific Unit Changes
+
+#### Index Dashboards (10, 11)
+| Panel | Current Unit | Proposed Unit |
+|-------|--------------|---------------|
+| Top indexes by reads (bytes) | `Bps` | `binBps` |
+| Top indexes by hits (bytes) | `Bps` | `binBps` |
+| Index reads and hits (bytes) | `Bps` | `binBps` |
+
+#### Table Dashboards (8, 9)
+Already mostly consistent with `binBps` for rates and `bytes` for absolute sizes.
+
+#### Query Dashboards (2, 3)
+| Panel | Current Unit | Proposed Unit |
+|-------|--------------|---------------|
+| Calls per second | `calls/s` | `ops` (rename to "ops/s" in title or keep calls/s) |
+
+**Recommendation**: Keep `calls/s` as it's semantically clearer for queries.
+
+---
+
+## 3. Row Grouping and Ordering Unification
+
+### 3.1 Current Row Groupings
+
+#### Dashboard 8 (Table Stats)
+1. Detailed table view (aggregated table statistics)
+2. Size stats
+3. Tuple stats
+4. IO stats
+5. Estimated bloat stats
+
+#### Dashboard 9 (Single Table Analysis)
+1. Size stats
+2. Estimated bloat stats
+3. Tuple stats
+4. IO stats
+
+#### Dashboard 10 (Index Health)
+1. Detailed index view
+2. Size stats
+3. Index usage stats
+4. IO stats
+5. Estimated bloat stats
+
+#### Dashboard 11 (Single Index Analysis)
+1. Size stats
+2. Index usage stats
+3. IO stats
+4. Estimated bloat stats
+
+### 3.2 Identified Inconsistencies
+
+1. **Bloat stats position**: In Dashboard 9 (Single Table), bloat comes right after Size stats. In Dashboard 8, 10, 11, bloat comes at the end.
+
+2. **Missing sections**: Dashboard 9 has "IO stats" section, but Dashboard 11 (Single Index) also has "IO stats" - these are consistent.
+
+3. **Naming inconsistency**: "Index usage stats" vs "Tuple stats" - these cover similar concepts (how objects are being used).
+
+### 3.3 Proposed Unified Row Order
+
+For **Aggregated Dashboards** (8, 10):
+1. `Detailed view` (collapsed table with all metrics)
+2. `Size stats` (size-related time series)
+3. `Activity stats` (operations, scans, tuple activity)
+4. `IO stats` (block reads, hits, cache performance)
+5. `Bloat stats` (estimated bloat metrics)
+
+For **Single Object Dashboards** (9, 11):
+1. `Size stats`
+2. `Activity stats`
+3. `IO stats`
+4. `Bloat stats`
+
+### 3.4 Specific Changes
+
+#### Dashboard 9 (Single Table Analysis)
+Move "Estimated bloat stats" section from position 2 to position 4 (after IO stats):
+
+**Current Order:**
+1. Size stats
+2. Estimated bloat stats  ← Move to end
+3. Tuple stats
+4. IO stats
+
+**Proposed Order:**
+1. Size stats
+2. Tuple stats (rename to "Activity stats")
+3. IO stats
+4. Bloat stats
+
+#### Dashboard 8 (Table Stats)
+Rename "Tuple stats" to "Activity stats" for consistency with proposed naming.
+
+#### Dashboard 10 (Index Health)
+Rename "Index usage stats" to "Activity stats" for consistency.
+
+#### Dashboard 11 (Single Index Analysis)
+Rename "Index usage stats" to "Activity stats" for consistency.
+
+---
+
+## 4. Additional Recommendations
+
+### 4.1 Panel Height Consistency
+
+Current panel heights vary significantly:
+- Most time series panels: h=8 to h=13
+- Recommendation: Standardize on h=10 for regular panels, h=13 for wide/important panels
+
+### 4.2 Legend Configuration
+
+Some dashboards show different legend calculations:
+- Dashboard 9: `["min", "max", "mean"]` - good
+- Dashboard 10: `["min", "max", "mean"]` - good
+- Some panels only show `["last"]`
+
+Recommendation: Use `["min", "max", "mean"]` for all time series panels.
+
+### 4.3 Footer Text Panel
+
+All dashboards end with the PostgresAI branding text panel. This is consistent and should be maintained.
+
+---
+
+## 5. Implementation Priority
+
+### Priority 1: High Impact, Low Risk
+1. Rename "Index usage stats" → "Activity stats" (Dashboards 10, 11)
+2. Rename "Tuple stats" → "Activity stats" (Dashboards 8, 9)
+3. Fix unit inconsistency: `Bps` → `binBps` in Index dashboards
+
+### Priority 2: Medium Impact
+1. Standardize "Top N" panel title patterns
+2. Reorder Dashboard 9 sections (move bloat to end)
+3. Add `/s` suffix to rate panel titles
+
+### Priority 3: Polish
+1. Standardize panel heights
+2. Unify legend configurations
+3. Review and standardize panel descriptions
+
+---
+
+## 6. Implementation Checklist
+
+### Dashboard 8 (Table Stats)
+- [ ] Rename "Tuple stats" row to "Activity stats"
+- [ ] Simplify panel titles (remove "(including TOAST)", "(absolute)")
+- [ ] Add `/s` to rate panel titles
+
+### Dashboard 9 (Single Table Analysis)
+- [ ] Rename "Tuple stats" row to "Activity stats"
+- [ ] Move "Estimated bloat stats" section to end (after IO stats)
+- [ ] Simplify panel titles
+
+### Dashboard 10 (Index Health)
+- [ ] Rename "Index usage stats" row to "Activity stats"
+- [ ] Change units from `Bps` to `binBps` for reads/hits panels
+- [ ] Add `/s` to rate panel titles
+
+### Dashboard 11 (Single Index Analysis)
+- [ ] Rename "Index usage stats" row to "Activity stats"
+- [ ] Change units from `Bps` to `binBps` for reads/hits panel
+- [ ] Add title to Boguk ratio panel: "Bloat analysis (Boguk ratio)"
+
+### Dashboard 1 (Node Performance Overview)
+- [ ] Simplify panel titles (remove "pg_stat_statements" suffixes where redundant)
+- [ ] Consider renaming sections for consistency
+
+---
+
+## 7. Summary of Changes
+
+| Category | Changes Count | Risk Level |
+|----------|---------------|------------|
+| Row renames | 4 | Low |
+| Row reordering | 1 | Low |
+| Panel title updates | ~30 | Low |
+| Unit fixes | 3-4 | Low |
+| Panel config (heights, legends) | ~20 | Very Low |
+
+Total estimated changes: ~60 modifications across 4-5 dashboards.
+
+---
+
+*Document prepared for dashboard unification review.*