Merge branch 'dashboard-unification-issue-73' into 'main'

Dementii Priadko · Dementii Priadko · commit b9e4aeb87cf4 · 2025-12-29T19:49:32.000Z
feat(dashboards): unify panel titles and units across Grafana dashboards

Closes #73

See merge request postgres-ai/postgres_ai!131
diff --git a/config/grafana/dashboards/Dashboard_10_Index health.json b/config/grafana/dashboards/Dashboard_10_Index health.json
@@ -500,39 +500,6 @@
       ],
       "title": "Top $top_n indexes by tuples read",
       "type": "timeseries"
-    },
-      "options": {
-        "legend": {
-          "calcs": [
-            "min",
-            "max",
-            "mean"
-          ],
-          "displayMode": "table",
-          "placement": "bottom",
-          "showLegend": true,
-          "sortBy": "Max",
-          "sortDesc": true
-        },
-        "tooltip": {
-          "hideZeros": false,
-          "mode": "multi",
-          "sort": "desc"
-        }
-      },
-      "pluginVersion": "12.0.2",
-      "targets": [
-        {
-          "editorMode": "code",
-          "expr": "topk($top_n, irate(pgwatch_pg_stat_all_indexes_idx_tup_read{cluster='$cluster_name', node_name='$node_name', datname=\"$db_name\"}[$__rate_interval]))",
-          "interval": "20",
-          "legendFormat": "{{schemaname}}.{{relname}}.{{indexrelname}}",
-          "range": true,
-          "refId": "A"
-        }
-      ],
-      "title": "Top $top_n indexes by tuples read",
-      "type": "timeseries"
     },
     {
       "datasource": {
@@ -705,7 +672,7 @@
               }
             ]
           },
-          "unit": "Bps"
+          "unit": "binBps"
         },
         "overrides": []
       },
@@ -746,7 +713,7 @@
           "refId": "A"
         }
       ],
-      "title": "Top $top_n indexes by reads (bytes)",
+      "title": "Top $top_n indexes by block reads",
       "type": "timeseries"
     },
     {
@@ -806,7 +773,7 @@
               }
             ]
           },
-          "unit": "Bps"
+          "unit": "binBps"
         },
         "overrides": []
       },
@@ -847,7 +814,7 @@
           "refId": "A"
         }
       ],
-      "title": "Top $top_n indexes by hits (bytes)",
+      "title": "Top $top_n indexes by block hits",
       "type": "timeseries"
     },
     {
diff --git a/config/grafana/dashboards/Dashboard_11_Single_index_analysis.json b/config/grafana/dashboards/Dashboard_11_Single_index_analysis.json
@@ -423,7 +423,7 @@
               }
             ]
           },
-          "unit": "Bps"
+          "unit": "binBps"
         },
         "overrides": []
       },
@@ -470,7 +470,7 @@
           "refId": "B"
         }
       ],
-      "title": "Index reads and hits (bytes)",
+      "title": "Shared block reads and hits",
       "type": "timeseries"
     },
     {
@@ -693,7 +693,7 @@
           "refId": "C"
         }
       ],
-      "title": "",
+      "title": "Boguk ratio (index size / reltuples)",
       "transformations": [
         {
           "id": "calculateField",
diff --git a/config/grafana/dashboards/Dashboard_8_Table_Stats.json b/config/grafana/dashboards/Dashboard_8_Table_Stats.json
@@ -659,7 +659,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by size change rate (absolute)",
+      "title": "Top $top_n tables by size growth /s",
       "type": "timeseries"
     },
     {
@@ -761,7 +761,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by table (w/o TOAST) size",
+      "title": "Top $top_n tables by heap size (excl. TOAST)",
       "type": "timeseries"
     },
     {
@@ -863,7 +863,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by table (w/o TOAST) size change rate (absolute)",
+      "title": "Top $top_n tables by heap size growth /s",
       "type": "timeseries"
     },
     {
@@ -1067,7 +1067,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by TOAST size change rate (absolute)",
+      "title": "Top $top_n tables by TOAST size growth /s",
       "type": "timeseries"
     },
     {
@@ -1169,7 +1169,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by index size",
+      "title": "Top $top_n tables by indexes size",
       "type": "timeseries"
     },
     {
@@ -1271,7 +1271,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by index size change rate (absolute)",
+      "title": "Top $top_n tables by indexes size growth /s",
       "type": "timeseries"
     },
     {
@@ -1284,7 +1284,7 @@
       },
       "id": 11,
       "panels": [],
-      "title": "Tuple stats",
+      "title": "Activity stats",
       "type": "row"
     },
     {
@@ -2474,7 +2474,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by table (without TOAST) shared block hits",
+      "title": "Top $top_n tables by heap shared block hits",
       "type": "timeseries"
     },
     {
@@ -2577,7 +2577,7 @@
           "useBackend": false
         }
       ],
-      "title": "Top $top_n tables by table (without TOAST) shared block reads",
+      "title": "Top $top_n tables by heap shared block reads",
       "type": "timeseries"
     },
     {
diff --git a/config/grafana/dashboards/Dashboard_9_Single_table_analysis.json b/config/grafana/dashboards/Dashboard_9_Single_table_analysis.json
@@ -422,7 +422,7 @@
           "useBackend": false
         }
       ],
-      "title": "Table logical size distribution changes (absolute)",
+      "title": "Size growth /s",
       "transformations": [
         {
           "id": "calculateField",
@@ -663,7 +663,7 @@
       },
       "id": 30,
       "panels": [],
-      "title": "Tuple stats",
+      "title": "Activity stats",
       "type": "row"
     },
     {
@@ -884,7 +884,7 @@
           "useBackend": false
         }
       ],
-      "title": "Tuple operations",
+      "title": "Tuple operations /s",
       "transformations": [
         {
           "id": "calculateField",
@@ -1145,7 +1145,7 @@
           "useBackend": false
         }
       ],
-      "title": "Tuple operations (%)",
+      "title": "Tuple operations distribution (%)",
       "transformations": [
         {
           "id": "calculateField",
@@ -1426,7 +1426,7 @@
           "useBackend": false
         }
       ],
-      "title": "Live tuples fetch distribution",
+      "title": "Tuple fetch methods /s",
       "type": "timeseries"
     },
     {
@@ -1610,7 +1610,7 @@
           "refId": "E"
         }
       ],
-      "title": "Shared block hits",
+      "title": "Shared block hits /s",
       "transformations": [
         {
           "id": "calculateField",
@@ -1787,7 +1787,7 @@
           "refId": "E"
         }
       ],
-      "title": "Shared block reads",
+      "title": "Shared block reads /s",
       "transformations": [
         {
           "id": "calculateField",
diff --git a/config/grafana/dashboards/README.md b/config/grafana/dashboards/README.md
@@ -0,0 +1,61 @@
+# Grafana Dashboards Naming Conventions
+
+This document outlines the naming principles used in PostgresAI Grafana dashboards.
+
+## Terminology Rules
+
+### Bloat Metrics
+Always use **"Estimated bloat"** when referring to bloat metrics. The bloat
+values shown in these dashboards are based on estimation queries that use
+pg_stat_user_tables statistics - they are not precise measurements like
+pgstattuple would provide.
+
+**Correct:**
+- "Estimated bloat %"
+- "Estimated bloat size"
+- "Top $top_n tables by estimated bloat %"
+
+**Incorrect:**
+- "Bloat %"
+- "Bloat size"
+
+### Shared Block I/O
+Use **"Shared block reads"** and **"Shared block hits"** - these are the correct
+PostgreSQL terminology.
+
+- **Shared block hits**: Data was found in PostgreSQL's shared buffer pool
+- **Shared block reads**: Data was read into the shared buffer pool from the OS
+  page cache. Note: This does NOT necessarily mean a disk read occurred - the data
+  may have been served from the OS file system cache.
+
+**Correct:**
+- "Shared block reads"
+- "Shared block hits"
+- "Shared block hit ratio"
+
+**Incorrect:**
+- "Block disk reads" (we don't know if actual disk I/O occurred)
+- "Block cache hits" (ambiguous - could mean OS cache or PG buffer pool)
+
+### Rate Metrics
+For rate-based panels (showing per-second values), append `/s` to the title:
+
+**Examples:**
+- "Tuple operations /s"
+- "Size growth /s"
+- "Shared block hits /s"
+
+### Section (Row) Naming
+- **"Activity stats"**: For table dashboards showing tuple operations
+- **"Index usage stats"**: For index dashboards showing scan/fetch metrics
+- **"Estimated bloat stats"**: For bloat-related metrics (always include "Estimated")
+- **"IO stats"**: For shared buffer pool I/O metrics
+- **"Size stats"**: For size-related metrics
+
+## Units
+
+- **binBps**: Use binary bytes per second (KiB/s, MiB/s, GiB/s) for PostgreSQL
+  block I/O rates, as PostgreSQL uses binary block sizes (typically 8 KiB)
+- **bytes**: Use for absolute size measurements
+- **percent**: Use for percentage values (0-100 scale)
+- **ops**: Use for operations per second

Original file line number	Diff line number	Diff line change
`@@ -423,7 +423,7 @@`
`423`	`423`	`}`
`424`	`424`	`]`
`425`	`425`	`},`
`426`		`- "unit": "Bps"`
	`426`	`+ "unit": "binBps"`
`427`	`427`	`},`
`428`	`428`	`"overrides": []`
`429`	`429`	`},`
`@@ -470,7 +470,7 @@`
`470`	`470`	`"refId": "B"`
`471`	`471`	`}`
`472`	`472`	`],`
`473`		`- "title": "Index reads and hits (bytes)",`
	`473`	`+ "title": "Shared block reads and hits",`
`474`	`474`	`"type": "timeseries"`
`475`	`475`	`},`
`476`	`476`	`{`
`@@ -693,7 +693,7 @@`
`693`	`693`	`"refId": "C"`
`694`	`694`	`}`
`695`	`695`	`],`
`696`		`- "title": "",`
	`696`	`+ "title": "Boguk ratio (index size / reltuples)",`
`697`	`697`	`"transformations": [`
`698`	`698`	`{`
`699`	`699`	`"id": "calculateField",`
Original file line number	Diff line number	Diff line change
`@@ -659,7 +659,7 @@`
`659`	`659`	`"useBackend": false`
`660`	`660`	`}`
`661`	`661`	`],`
`662`		`- "title": "Top $top_n tables by size change rate (absolute)",`
	`662`	`+ "title": "Top $top_n tables by size growth /s",`
`663`	`663`	`"type": "timeseries"`
`664`	`664`	`},`
`665`	`665`	`{`
`@@ -761,7 +761,7 @@`
`761`	`761`	`"useBackend": false`
`762`	`762`	`}`
`763`	`763`	`],`
`764`		`- "title": "Top $top_n tables by table (w/o TOAST) size",`
	`764`	`+ "title": "Top $top_n tables by heap size (excl. TOAST)",`
`765`	`765`	`"type": "timeseries"`
`766`	`766`	`},`
`767`	`767`	`{`
`@@ -863,7 +863,7 @@`
`863`	`863`	`"useBackend": false`
`864`	`864`	`}`
`865`	`865`	`],`
`866`		`- "title": "Top $top_n tables by table (w/o TOAST) size change rate (absolute)",`
	`866`	`+ "title": "Top $top_n tables by heap size growth /s",`
`867`	`867`	`"type": "timeseries"`
`868`	`868`	`},`
`869`	`869`	`{`
`@@ -1067,7 +1067,7 @@`
`1067`	`1067`	`"useBackend": false`
`1068`	`1068`	`}`
`1069`	`1069`	`],`
`1070`		`- "title": "Top $top_n tables by TOAST size change rate (absolute)",`
	`1070`	`+ "title": "Top $top_n tables by TOAST size growth /s",`
`1071`	`1071`	`"type": "timeseries"`
`1072`	`1072`	`},`
`1073`	`1073`	`{`
`@@ -1169,7 +1169,7 @@`
`1169`	`1169`	`"useBackend": false`
`1170`	`1170`	`}`
`1171`	`1171`	`],`
`1172`		`- "title": "Top $top_n tables by index size",`
	`1172`	`+ "title": "Top $top_n tables by indexes size",`
`1173`	`1173`	`"type": "timeseries"`
`1174`	`1174`	`},`
`1175`	`1175`	`{`
`@@ -1271,7 +1271,7 @@`
`1271`	`1271`	`"useBackend": false`
`1272`	`1272`	`}`
`1273`	`1273`	`],`
`1274`		`- "title": "Top $top_n tables by index size change rate (absolute)",`
	`1274`	`+ "title": "Top $top_n tables by indexes size growth /s",`
`1275`	`1275`	`"type": "timeseries"`
`1276`	`1276`	`},`
`1277`	`1277`	`{`
`@@ -1284,7 +1284,7 @@`
`1284`	`1284`	`},`
`1285`	`1285`	`"id": 11,`
`1286`	`1286`	`"panels": [],`
`1287`		`- "title": "Tuple stats",`
	`1287`	`+ "title": "Activity stats",`
`1288`	`1288`	`"type": "row"`
`1289`	`1289`	`},`
`1290`	`1290`	`{`
`@@ -2474,7 +2474,7 @@`
`2474`	`2474`	`"useBackend": false`
`2475`	`2475`	`}`
`2476`	`2476`	`],`
`2477`		`- "title": "Top $top_n tables by table (without TOAST) shared block hits",`
	`2477`	`+ "title": "Top $top_n tables by heap shared block hits",`
`2478`	`2478`	`"type": "timeseries"`
`2479`	`2479`	`},`
`2480`	`2480`	`{`
`@@ -2577,7 +2577,7 @@`
`2577`	`2577`	`"useBackend": false`
`2578`	`2578`	`}`
`2579`	`2579`	`],`
`2580`		`- "title": "Top $top_n tables by table (without TOAST) shared block reads",`
	`2580`	`+ "title": "Top $top_n tables by heap shared block reads",`
`2581`	`2581`	`"type": "timeseries"`
`2582`	`2582`	`},`
`2583`	`2583`	`{`
Original file line number	Diff line number	Diff line change
`@@ -422,7 +422,7 @@`
`422`	`422`	`"useBackend": false`
`423`	`423`	`}`
`424`	`424`	`],`
`425`		`- "title": "Table logical size distribution changes (absolute)",`
	`425`	`+ "title": "Size growth /s",`
`426`	`426`	`"transformations": [`
`427`	`427`	`{`
`428`	`428`	`"id": "calculateField",`
`@@ -663,7 +663,7 @@`
`663`	`663`	`},`
`664`	`664`	`"id": 30,`
`665`	`665`	`"panels": [],`
`666`		`- "title": "Tuple stats",`
	`666`	`+ "title": "Activity stats",`
`667`	`667`	`"type": "row"`
`668`	`668`	`},`
`669`	`669`	`{`
`@@ -884,7 +884,7 @@`
`884`	`884`	`"useBackend": false`
`885`	`885`	`}`
`886`	`886`	`],`
`887`		`- "title": "Tuple operations",`
	`887`	`+ "title": "Tuple operations /s",`
`888`	`888`	`"transformations": [`
`889`	`889`	`{`
`890`	`890`	`"id": "calculateField",`
`@@ -1145,7 +1145,7 @@`
`1145`	`1145`	`"useBackend": false`
`1146`	`1146`	`}`
`1147`	`1147`	`],`
`1148`		`- "title": "Tuple operations (%)",`
	`1148`	`+ "title": "Tuple operations distribution (%)",`
`1149`	`1149`	`"transformations": [`
`1150`	`1150`	`{`
`1151`	`1151`	`"id": "calculateField",`
`@@ -1426,7 +1426,7 @@`
`1426`	`1426`	`"useBackend": false`
`1427`	`1427`	`}`
`1428`	`1428`	`],`
`1429`		`- "title": "Live tuples fetch distribution",`
	`1429`	`+ "title": "Tuple fetch methods /s",`
`1430`	`1430`	`"type": "timeseries"`
`1431`	`1431`	`},`
`1432`	`1432`	`{`
`@@ -1610,7 +1610,7 @@`
`1610`	`1610`	`"refId": "E"`
`1611`	`1611`	`}`
`1612`	`1612`	`],`
`1613`		`- "title": "Shared block hits",`
	`1613`	`+ "title": "Shared block hits /s",`
`1614`	`1614`	`"transformations": [`
`1615`	`1615`	`{`
`1616`	`1616`	`"id": "calculateField",`
`@@ -1787,7 +1787,7 @@`
`1787`	`1787`	`"refId": "E"`
`1788`	`1788`	`}`
`1789`	`1789`	`],`
`1790`		`- "title": "Shared block reads",`
	`1790`	`+ "title": "Shared block reads /s",`
`1791`	`1791`	`"transformations": [`
`1792`	`1792`	`{`
`1793`	`1793`	`"id": "calculateField",`