From ffb4ffb7a62514bb9fac503d7c0d0047f47f77df Mon Sep 17 00:00:00 2001
From: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Date: Mon, 27 Oct 2025 16:39:14 +0100
Subject: [PATCH] docs: clarify observability metrics and migration to
 plugin-based ones (#621)

Improved the "Observability" section to better describe the Prometheus
metrics exposed by the Barman Cloud Plugin via the instance manager.
Added a mapping table in the "Verify your metrics" step to show the
transition from in-core metrics (`cnpg_collector_*`) to the new
plugin-based metrics (`barman_cloud_cloudnative_pg_io_*`).

Closes #473
Closes cloudnative-pg/cloudnative-pg#8902

Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
---
 .wordlist.txt             |  1 +
 web/docs/migration.md     | 15 +++++++++++++++
 web/docs/observability.md | 24 ++++++++++++++++++++++++
 3 files changed, 40 insertions(+)
 create mode 100644 web/docs/observability.md

diff --git a/.wordlist.txt b/.wordlist.txt
index d5fa782..24d9309 100644
--- a/.wordlist.txt
+++ b/.wordlist.txt
@@ -33,6 +33,7 @@ ObjectMeta
 ObjectStore
 ObjectStoreSpec
 ObjectStoreStatus
+Observability
 PITR
 PoR
 PostgreSQL
diff --git a/web/docs/migration.md b/web/docs/migration.md
index 43c4b80..2c99ada 100644
--- a/web/docs/migration.md
+++ b/web/docs/migration.md
@@ -257,3 +257,18 @@ spec:
         barmanObjectName: minio-eu
         serverName: pg-eu
 ```
+
+## Step 5: Verify your metrics
+
+When migrating from the in-core solution to the plugin-based approach, you need
+to monitor a different set of metrics, as described in the
+["Observability"](observability.md) section.
+
+The table below summarizes the name changes between the old in-core metrics and
+the new plugin-based ones:
+
+| Old metric name                                  | New metric name                                                  |
+| ------------------------------------------------ | ---------------------------------------------------------------- |
+| `cnpg_collector_last_failed_backup_timestamp`    | `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp`    |
+| `cnpg_collector_last_available_backup_timestamp` | `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp` |
+| `cnpg_collector_first_recoverability_point`      | `barman_cloud_cloudnative_pg_io_first_recoverability_point`      |
diff --git a/web/docs/observability.md b/web/docs/observability.md
new file mode 100644
index 0000000..274b973
--- /dev/null
+++ b/web/docs/observability.md
@@ -0,0 +1,24 @@
+---
+sidebar_position: 55
+---
+
+# Observability
+
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+The Barman Cloud Plugin exposes the following metrics through the native
+Prometheus exporter of the instance manager:
+
+- `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp`:
+  the UNIX timestamp of the most recent failed backup.
+
+- `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp`:
+  the UNIX timestamp of the most recent successfully available backup.
+
+- `barman_cloud_cloudnative_pg_io_first_recoverability_point`:
+  the UNIX timestamp representing the earliest point in time from which the
+  cluster can be recovered.
+
+These metrics supersede the previously available in-core metrics that used the
+`cnpg_collector` prefix. The new metrics are exposed under the
+`barman_cloud_cloudnative_pg_io` prefix instead.