Instance Sidecar Metrics#

Overview#

The instance sidecar in plugin-barman-cloud exposes a Metrics gRPC service as part of its CNPG-I interface. The service is implemented in internal/cnpgi/instance/metrics.go and registered alongside the WAL, Backup, and health-check services when the sidecar starts 1.

The handler is entirely read-only: it never writes to Kubernetes, never acquires any lock, and has no synchronization with the CatalogMaintenanceRunnable retention cycle that runs concurrently in the same process.

Exposed Metrics#

Three Prometheus gauges are declared in Define and collected in Collect. All names are derived from the plugin name (sanitized to a valid Prometheus namespace) via buildFqName:

All three are TYPE_GAUGE 2. Zero is returned for any metric whose source field is nil or when the server name is not yet present in the ObjectStore status 3.

How Collect Works#

On every scrape the handler 4:

1. Parses the cluster definition from the gRPC request payload via config.NewFromClusterJSON to determine the ObjectStore key and server name.
2. Fetches the ObjectStore CR from the Kubernetes API using a controller-runtime cached client — a single client.Get call, no barman CLI invocation.
3. Reads ObjectStore.Status.ServerRecoveryWindow[serverName] — a map populated by the backup and retention paths.
4. Returns the three timestamps as float64 Unix values, or zeros if the window entry is absent.

The cached client means the call reads from the in-memory informer cache rather than going to the API server on every scrape.

No Shared State with the Retention Cycle#

The metrics service has no mutex, channel, or other synchronization with CatalogMaintenanceRunnable 5. Both run concurrently as separate controller-runtime runnables registered in manager.go 6.

This is safe by design: the metrics handler is read-only and the retention cycle writes ObjectStore.Status via a Kubernetes API call with retry-on-conflict. Kubernetes optimistic concurrency is the only coordination mechanism. The worst-case outcome is that a scrape observes a slightly stale value from the informer cache between a retention cycle write and the cache refresh — not a crash or data race.

Registration#

metricsImpl is registered in CNPGI.Start:

metrics.RegisterMetricsServer(server, &metricsImpl{
    Client: c.Client,
})

It receives only the controller-runtime client.Client; it holds no other state 7.

The GetCapabilities RPC advertises a single RPC_TYPE_METRICS capability 8, which tells the CNPG-I framework that this plugin provides custom metrics.

Key Source Files#