Feature Request: Expose additional backup storage metrics from PBS API

[gowtham418p-rgb]

Hello,

We are currently using the pbs-exporter to monitor our Proxmox Backup Server environment and integrate the metrics into Grafana dashboards.

The exporter already exposes several useful metrics such as:

• pbs_size
• pbs_used
• pbs_available
• pbs_snapshot_count
• pbs_snapshot_vm_count
• pbs_snapshot_vm_last_timestamp

However, for deeper monitoring and capacity planning we require additional metrics that appear to be available via the Proxmox Backup Server API but are not currently exported.

Required metrics

1. Snapshot size

To analyze backup storage usage and backup growth trends, we need the size of each snapshot.

Proposed metric:

pbs_snapshot_size_bytes{datastore, namespace, vm_id, vm_name, backup_time}

API source:
/api2/json/admin/datastore//snapshots

2. First backup timestamp per VM

Currently the exporter exposes only the last backup timestamp:

pbs_snapshot_vm_last_timestamp

To display the full backup history of a VM, we would also need the first backup timestamp.

Proposed metric:

pbs_snapshot_vm_first_timestamp{datastore, namespace, vm_id, vm_name}

API source:
/api2/json/admin/datastore//snapshots

3. Total backup storage used per VM

To identify which VMs consume the most backup storage, we propose the following aggregated metric:

pbs_vm_backup_total_size_bytes{datastore, namespace, vm_id, vm_name}

API source:
/api2/json/admin/datastore//snapshots

4. Detect backup growth trend per VM

pbs_vm_backup_growth_bytes

API source:
/api2/json/admin/datastore/{store}/snapshots

5. Needed for alerting: disk full in X days

pbs_datastore_estimated_days_until_full

API source:
/api2/json/admin/datastore/{store}/status

6. Used for capacity monitoring dashboards

pbs_datastore_usage_percent

API source:
/api2/json/admin/datastore/{store}/status

Use case

These metrics would allow us to:

• visualize storage usage per backup
• track backup storage trends
• identify VMs consuming the most backup storage
• enrich Grafana dashboards with VM backup statistics
• improve capacity planning for Proxmox Backup Server storage

API documentation

https://pbs.proxmox.com/docs/api-viewer/index.html

Contribution

We are currently evaluating the possibility of extending the exporter ourselves to expose these metrics.

Since the required information appears to be available through the PBS API (for example via /api2/json/admin/datastore//snapshots), we are exploring adding these metrics directly in the exporter code.

Before proceeding with implementation, we wanted to check with the maintainers if exposing these metrics would be aligned with the project's scope and design.

If this enhancement is acceptable, we would be happy to work on a pull request.

Thank you for maintaining this exporter.

[torbenaa]

Would love to see this too :)

[nicololuescher]

Hi @gowtham418p-rgb,
thanks for the detailed write-up, really appreciate you taking the time to lay it out like this, and yes, we'd be happy to have you work on it. Before you start coding, a few things worth sorting out so the PR lands cleanly.

On the metrics themselves:

For the per-snapshot size, could we avoid putting backup_time in the labels? Every new backup would spawn a new time series that never goes away, and Prometheus gets grumpy about that pretty quickly. What would work better is
pbs_snapshot_vm_last_size_bytes (latest snapshot size per VM). You still get the history you need because Prometheus stores the gauge over time, and you can compute growth with delta(...) in PromQL.

On the "first backup timestamp", naming-wise "first" is a bit of a trap because prune jobs delete old snapshots over time, so it's really the oldest retained one. Could we call it pbs_snapshot_vm_oldest_timestamp? Mirrors the existing _last_timestamp
too.

Total size per VM is fine, happy to take that as pbs_snapshot_vm_total_size_bytes (to match the existing naming). One thing to call out in the help text though: PBS deduplicates at the chunk level, so summing snapshot sizes will overstate actual disk
usage, sometimes by a lot. Worth making that explicit so dashboards don't mislead people.

Three I'd rather leave out:

• Growth bytes → delta(pbs_snapshot_vm_total_size_bytes[7d])
• Days until full → predict_linear(pbs_used[7d], 30*86400) >= pbs_size (works great as an alert rule btw)
• Usage percent → pbs_used / pbs_size

Nothing against the ideas, it's just that Prometheus gives you these basically for free, and doing the math in the exporter means you can't tune the time window per dashboard or alert, which is usually what you actually want. Happy to help with the
PromQL if it's useful.

One bit of good news on the implementation: the snapshots endpoint already returns a size field, so no extra API calls needed. You'll mostly be extending the SnapshotResponse struct and adding some aggregation in getNamespaceMetric.

Two small things for the PR when you get there: please update the metrics table in the README, and if you're up for it, a test or two around the new parsing would be great. The exporter doesn't have any yet and this is a nice spot to start.

Looking forward to seeing it!