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 <[email protected]>

Author: gbartolini

.wordlist.txt

@@ -33,6 +33,7 @@ ObjectMeta
 ObjectStore
 ObjectStoreSpec
 ObjectStoreStatus
+Observability
 PITR
 PoR
 PostgreSQL

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`      |

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.