Merge branch 'grafana/dashboard-labels-and-uid-collision' into 'main'

Sarumyan · Sarumyan · commit 780d221b6fcc · 2026-05-25T14:05:22.000Z
ops(grafana): standardize dashboard tags, fix UID-collision after upgrade

Closes #202

See merge request postgres-ai/postgresai!269
diff --git a/config/grafana/dashboards/Dashboard_10_Index health.json b/config/grafana/dashboards/Dashboard_10_Index health.json
@@ -1115,7 +1115,8 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "indexes"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_11_Single_index_analysis.json b/config/grafana/dashboards/Dashboard_11_Single_index_analysis.json
@@ -741,7 +741,8 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "indexes"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_12_SLRU.json b/config/grafana/dashboards/Dashboard_12_SLRU.json
@@ -763,7 +763,8 @@
     "refresh": "30s",
     "schemaVersion": 41,
     "tags": [
-      "postgres-ai"
+      "postgres-ai",
+      "slru"
     ],
     "templating": {
       "list": [
diff --git a/config/grafana/dashboards/Dashboard_13_Lock_waits.json b/config/grafana/dashboards/Dashboard_13_Lock_waits.json
@@ -1021,7 +1021,8 @@
   "refresh": "30s",
   "schemaVersion": 39,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "locks"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_14_IO_Statistics.json b/config/grafana/dashboards/Dashboard_14_IO_Statistics.json
@@ -1092,10 +1092,8 @@
   "refresh": "30s",
   "schemaVersion": 41,
   "tags": [
-    "postgresql",
-    "io",
-    "performance",
-    "postgres-ai"
+    "postgres-ai",
+    "io"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_1_Node_performance_overview.json b/config/grafana/dashboards/Dashboard_1_Node_performance_overview.json
@@ -3421,7 +3421,9 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "overview",
+    "node"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_2_Aggregated_query_analysis.json b/config/grafana/dashboards/Dashboard_2_Aggregated_query_analysis.json
@@ -3383,7 +3383,8 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "queries"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_3_Single_query_analysis.json b/config/grafana/dashboards/Dashboard_3_Single_query_analysis.json
@@ -2141,7 +2141,8 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "queries"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_4_Wait_Sampling_Dashboard.json b/config/grafana/dashboards/Dashboard_4_Wait_Sampling_Dashboard.json
@@ -936,7 +936,9 @@
   "refresh": "5s",
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "waits",
+    "ash"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_5_Backup_stats.json b/config/grafana/dashboards/Dashboard_5_Backup_stats.json
@@ -1156,10 +1156,10 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "backups",
-    "dr",
+    "postgres-ai",
     "wal",
-    "postgres-ai"
+    "backups",
+    "dr"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_6_Replication_and_HA.json b/config/grafana/dashboards/Dashboard_6_Replication_and_HA.json
@@ -64,7 +64,9 @@
     "preload": false,
     "schemaVersion": 41,
     "tags": [
-      "postgres-ai"
+      "postgres-ai",
+      "replication",
+      "ha"
     ],
     "templating": {
       "list": []
diff --git a/config/grafana/dashboards/Dashboard_7_Autovacuum_and_xmin_horizon.json b/config/grafana/dashboards/Dashboard_7_Autovacuum_and_xmin_horizon.json
@@ -1615,7 +1615,9 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "autovacuum",
+    "xmin"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_8_Table_Stats.json b/config/grafana/dashboards/Dashboard_8_Table_Stats.json
@@ -3257,7 +3257,8 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "tables"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/Dashboard_9_Single_table_analysis.json b/config/grafana/dashboards/Dashboard_9_Single_table_analysis.json
@@ -1958,7 +1958,8 @@
   "preload": false,
   "schemaVersion": 41,
   "tags": [
-    "postgres-ai"
+    "postgres-ai",
+    "tables"
   ],
   "templating": {
     "list": [
diff --git a/config/grafana/dashboards/README.md b/config/grafana/dashboards/README.md
@@ -2,6 +2,54 @@
 
 This document outlines the naming principles used in PostgresAI Grafana dashboards.
 
+## Tag Vocabulary
+
+Every shipped dashboard JSON MUST include a top-level `"tags"` array whose
+first entry is the project label `postgres-ai`, followed by 1-3 thematic tags
+drawn from the controlled vocabulary below. The leading project label lets
+operators filter the dashboard library to PostgresAI-shipped content even
+when other Grafana provisioning providers are configured on the same
+instance; the thematic tags give topical navigation.
+
+**Project label (mandatory, always first):** `postgres-ai`
+
+**Thematic vocabulary (pick 1-3):**
+
+| Tag | Meaning |
+|-----|---------|
+| `overview` | High-level / landing-page dashboards |
+| `node` | Per-node performance |
+| `queries` | Query analysis (pg_stat_statements, etc.) |
+| `waits` | Wait events |
+| `ash` | Active Session History |
+| `wal` | WAL generation and archiving |
+| `backups` | Backup state and lag |
+| `dr` | Disaster recovery |
+| `replication` | Streaming/logical replication |
+| `ha` | High availability state |
+| `autovacuum` | Autovacuum workload |
+| `xmin` | xmin horizon, bloat causes |
+| `tables` | Table-level stats |
+| `indexes` | Index-level stats |
+| `slru` | SLRU caches |
+| `locks` | Lock contention |
+| `io` | I/O statistics (pg_stat_io) |
+| `self-monitoring` | Monitoring of the monitoring stack itself |
+| `monitoring-stack` | pgwatch/VictoriaMetrics/Grafana plumbing |
+
+The mapping for shipped dashboards lives in the dashboards themselves; the
+file `config/grafana/dashboards/<name>.json` is the source of truth.
+
+When adding a new dashboard:
+
+1. Add `postgres-ai` as the first tag.
+2. Pick 1-3 thematic tags from the table above. Add to the table if a new
+   theme is genuinely needed (and explain why in the PR).
+3. Choose a stable top-level `uid` and never reuse one previously shipped:
+   Grafana provisioning blocks the entire provider when two files share a
+   top-level `uid` (see `config/init-configs.sh` for the upgrade-time
+   cleanup of stale dashboards).
+
 ## Terminology Rules
 
 ### Bloat Metrics
diff --git a/config/grafana/dashboards/Self_Monitoring_Dashboard.json b/config/grafana/dashboards/Self_Monitoring_Dashboard.json
@@ -2848,9 +2848,9 @@
   "refresh": "",
   "schemaVersion": 41,
   "tags": [
+    "postgres-ai",
     "self-monitoring",
-    "monitoring-stack",
-    "postgres-ai"
+    "monitoring-stack"
   ],
   "templating": {
     "list": []
diff --git a/config/init-configs.sh b/config/init-configs.sh
@@ -45,6 +45,21 @@ fi
 
 echo "Initializing configs (target version: $SOURCE_VERSION)..."
 
+# Grafana dashboards are managed by file-based provisioning and must mirror the
+# image exactly: stale files cause "the same UID is used more than once" warnings
+# that block the provisioner from writing ANY dashboard. cp -r only adds/overwrites,
+# so an in-place upgrade where a dashboard was renamed (e.g. 0.14 ->
+# 0.15: Dashboard_7_Autovacuum_and_bloat.json -> Dashboard_7_Autovacuum_and_xmin_horizon.json,
+# both with the same top-level uid) would leave both files in the volume and
+# trigger a collision. Clean the dashboards directory before re-copy. We only
+# clean dashboards/ - other config files (pgwatch metrics.yml, etc.) may have
+# been edited by the operator and must be preserved.
+DASHBOARDS_DIR="${TARGET_DIR}/grafana/dashboards"
+if [ -d "$DASHBOARDS_DIR" ]; then
+  echo "Cleaning stale dashboards from $DASHBOARDS_DIR..."
+  find "$DASHBOARDS_DIR" -mindepth 1 -delete
+fi
+
 # Copy all configs preserving structure
 cp -r "$SOURCE_DIR"/* "$TARGET_DIR/"
 
diff --git a/tests/compliance_vectors/test_init_configs.py b/tests/compliance_vectors/test_init_configs.py
@@ -162,3 +162,54 @@ def test_missing_version_marker_on_nonempty_target_overwrites():
         assert os.path.isfile(marker)
         with open(marker) as f:
             assert f.read().strip() == '2.0.0'
+
+
+def test_stale_grafana_dashboards_removed_on_upgrade():
+    """Renamed dashboards from a prior version must NOT linger in the volume.
+
+    Grafana provisioning treats files in `grafana/dashboards/` as authoritative
+    sources. A stale file from a prior version that shares a top-level `uid`
+    with a renamed file in the new version triggers the
+    "the same UID is used more than once" warning and blocks the provider from
+    writing ANY dashboard. The init-configs script must therefore mirror the
+    dashboards directory to the image contents, not merely overlay it.
+    """
+    with tempfile.TemporaryDirectory() as tmp:
+        source_dir = os.path.join(tmp, 'src')
+        target_dir = os.path.join(tmp, 'tgt')
+        version_file = os.path.join(tmp, 'VERSION')
+        os.makedirs(source_dir)
+        os.makedirs(target_dir)
+        _make_source_tree(source_dir)
+
+        # New image ships a renamed dashboard.
+        os.makedirs(os.path.join(source_dir, 'grafana', 'dashboards'))
+        new_dashboard = os.path.join(
+            source_dir, 'grafana', 'dashboards', 'Dashboard_7_Autovacuum_and_xmin_horizon.json'
+        )
+        with open(new_dashboard, 'w') as f:
+            f.write('{"uid": "caffad19", "title": "new D7"}\n')
+
+        # Pre-existing volume from a prior version still has the OLD filename
+        # with the SAME top-level uid - the case that triggered the
+        # "the same UID is used more than once" warning in 0.14 -> 0.15.
+        os.makedirs(os.path.join(target_dir, 'grafana', 'dashboards'))
+        stale_dashboard = os.path.join(
+            target_dir, 'grafana', 'dashboards', 'Dashboard_7_Autovacuum_and_bloat.json'
+        )
+        with open(stale_dashboard, 'w') as f:
+            f.write('{"uid": "caffad19", "title": "old D7"}\n')
+        # Mismatched version marker so re-init runs.
+        with open(os.path.join(target_dir, VERSION_MARKER), 'w') as f:
+            f.write('1.0.0')
+
+        _run_script(source_dir, target_dir, version_file, version='2.0.0')
+
+        # Stale dashboard removed; new dashboard present.
+        assert not os.path.exists(stale_dashboard), (
+            'stale dashboard from prior version must be removed to avoid '
+            'duplicate-uid provisioning collisions'
+        )
+        assert os.path.isfile(
+            os.path.join(target_dir, 'grafana', 'dashboards', 'Dashboard_7_Autovacuum_and_xmin_horizon.json')
+        )
