prole/monitoring/cnpg-dashboard-transforms.yaml

# Transform spec for the upstream cloudnative-pg Grafana dashboard.
#
# Re-applied on every run of `etc/sync_cnpg_grafana_dashboard.py`. The script
# fetches the upstream JSON, walks `transformations` in order, writes the
# result to `knoe-db/grafana-dashboard.json` (which is what
# `etc/init_monitoring.sh` packages into the
# `knoe-db-grafana-dashboard` ConfigMap on the app cluster).
#
# When upstream releases a new version of the dashboard, the workflow is:
#
#   1. Re-run the sync tool (any branch — runs in CI or as a background
#      agent on its own schedule).
#   2. The tool fetches the new upstream, applies these transforms, and
#      either writes the result + opens a diff/PR (default), OR applies
#      to the live cluster directly (--apply).
#   3. If a transformation no longer matches (e.g. upstream renamed a key
#      or removed a panel that we were patching), the tool emits a warning
#      with the affected transformation's `name`. Update or remove that
#      transformation entry here, re-run.
#
# Adding a new transformation: append to `transformations`. Each entry has
# a `name`, `description`, `type`, and per-type parameters. Currently
# supported types:
#
#   - `regex_replace`: sed-style on the raw JSON string.
#       pattern: <python regex>      # use named groups for capture refs
#       replacement: <python regex repl, supports \g<name>>
#       expected_min: <int>         # tool warns if fewer matches than this
#       expected_max: <int>         # tool warns if more matches than this
#
# Future types we may add:
#
#   - `jsonpatch`: RFC 6902 operations against the parsed JSON tree
#   - `panel_query_rewrite`: navigate `panels[*].targets[*].expr` specifically
#
# The current set is deliberately tiny — most of the cross-cluster CNPG
# observability stack is fixed via cluster-side config (Cluster.spec.monitoring
# podMonitorRelabelings, kps grafana.ini settings) rather than dashboard
# edits. Only edits that MUST live in the dashboard JSON go here.

source:
  # Pinned to `main` because the upstream repo's dashboard versioning is loose.
  # If reproducibility against a specific revision is needed, swap `main` for
  # a commit SHA or release tag.
  url: https://raw.githubusercontent.com/cloudnative-pg/grafana-dashboards/main/charts/cluster/grafana-dashboard.json

  # The expected dashboard `uid` field. The tool will refuse to proceed if the
  # upstream has changed UID (would silently break dashboard URLs).
  expected_uid: cloudnative-pg

transformations:

  - name: rate_interval_swap
    description: |
      Swap `[$__interval]` for `[$__rate_interval]` inside `rate()` and
      `irate()` calls. Grafana's $__interval auto-shrinks below the scrape
      interval at small dashboard time ranges (e.g. a 5-min view yields
      ~1-2s rate windows; our 15s scrape interval means 0 samples in any 2s
      window, so rate() returns nothing). $__rate_interval is the rate-safe
      equivalent that Grafana auto-computes from min step + scrape interval.
      As of upstream commit at sync time, this affects 2 panels.      
    type: regex_replace
    pattern: '(?P<fn>rate|irate)\((?P<inner>[^()]*)\[\$__interval\]\)'
    replacement: '\g<fn>(\g<inner>[$__rate_interval])'
    expected_min: 1     # at least one match — if zero, upstream may have switched away from $__interval
    expected_max: 50    # if more than this, something's odd; flag for review

  - name: ds_prometheus_default_to_cnpg
    description: |
      Pin the dashboard's DS_PROMETHEUS template variable to our
      `cnpg-prometheus` datasource so panels render correctly on first load
      without users needing to override via URL params or the variable picker.

      Why: upstream ships the dashboard with `current.value: "prometheus"`
      (the upstream-default Prometheus UID). On a kps install, the standard
      Prometheus datasource has uid=prometheus (default), and our DB-cluster
      Prometheus is at uid=cnpg-prometheus (a stable name we set in
      monitoring/kps-values-gke.yaml's `additionalDataSources`). Without
      this transform, the dashboard initially queries the LOCAL prometheus
      (which has no CNPG metrics — they're only on the DB cluster), and
      Grafana's panel-cache + datasource-variable-rerun quirks make it
      hard to recover even after the user changes the picker.      
    type: set_template_variable_default
    variable: DS_PROMETHEUS
    # CAVEAT: this UID is the auto-generated one from the FIRST helm install
    # of kps. We pinned `uid: cnpg-prometheus` in monitoring/kps-values-gke.yaml
    # so a fresh helm install would get the stable name, but Grafana refuses
    # to update the UID of an already-provisioned datasource (read-only via
    # API; even rollout-restart doesn't pick it up). On the next clean kps
    # re-install (or after deleting the auto-uid datasource via direct DB
    # manipulation), update both this `value` and `text` to `cnpg-prometheus`.
    # Tracked in docs/TODO.md as a follow-up.
    value: P5531627C358300FE
    text: cnpg-prometheus
    selected: true

# (No further transformations needed at time of writing. Dashboard
# correctness for our cross-cluster setup comes mostly from server-side
# config: see `monitoring/kps-cnpg-values.yaml`,
# `monitoring/kps-values-gke.yaml`, and the
# `spec.monitoring.podMonitorRelabelings` in `deploy/gcp/gke/knoe-db.yaml`.)