NAME
gyptazy - it's all about FreeBSD, Proxmox, BGP and Coding!

OPTIONS

CONTENT

Proxmox Backup Server Monitoring with Prometheus and Grafana

():

Proxmox Backup Server is an essential component for anyone running Proxmox Virtual Environment (PVE) or managing backups in a modern virtualized infrastructure. It delivers a high-performance, deduplication-enabled backup solution that ensures reliable data protection while keeping storage usage efficient. Like any critical infrastructure service, continuous monitoring of its performance and health is crucial to guarantee stable operations and fast troubleshooting.

This is where centralized monitoring with Prometheus and Grafana becomes invaluable. Instead of manually inspecting logs or relying on sporadic status checks, a properly integrated monitoring stack provides real-time visibility into the backup server. Prometheus collects metrics, while Grafana visualizes them in clear and intuitive dashboards. This gives administrators immediate insight into backup job status, storage utilization, performance bottlenecks, and potential failures. A proactive monitoring approach helps detect issues early and ensures backups run reliably at all times.

In this HowTo guide, we set up Prometheus monitoring for Proxmox Backup Server by running the prometheus-pbs-exporter (from Natrontech) directly on the Proxmox Backup Server host. The exporter exposes relevant metrics for Prometheus, making it easy to monitor backup processes, disk usage, and system performance from a centralized monitoring environment. For container-based infrastructures, the exporter can also be deployed using Docker, offering additional flexibility.

Frequently Asked Questions (FAQ)

Why should I monitor Proxmox Backup Server?

Monitoring Proxmox Backup Server helps detect failed backup jobs, storage capacity issues, and performance bottlenecks early. With proper monitoring, administrators can proactively resolve issues before backups fail or storage runs out.

Which metrics does the Proxmox Backup Server exporter provide?

The PBS exporter exposes metrics such as backup job status, task duration, datastore usage, disk I/O performance, and system health. These metrics allow detailed analysis using Prometheus and visualization through Grafana dashboards.

Do I need Docker to run the PBS exporter?

No. While the upstream project assumes a container-based deployment, the exporter can also be run directly on Proxmox Backup Server using systemd. This is ideal for environments without Docker or container runtimes.

Is it safe to use an API token for monitoring?

Yes. Proxmox Backup Server API tokens are designed for automation and monitoring. For production environments, it is recommended to use a dedicated user with limited permissions and a dedicated API token.

Can I use self-signed certificates with the PBS exporter?

Yes. The exporter supports disabling SSL certificate verification for environments using self-signed certificates. However, valid TLS certificates are strongly recommended for production setups.

Is there an official Grafana dashboard for Proxmox Backup Server?

Yes. The PBS exporter project provides a ready-to-use Grafana dashboard that can be imported directly into Grafana to visualize Proxmox Backup Server metrics without manual dashboard creation.

Installation

General

By default, the upstream project assumes the exporter runs inside a dedicated Docker container. However, this approach does not always fit environments where no container infrastructure is available or desired. For this reason, I created the pull request feat: Add systemd unit file and support to run on PBS #99, which adds instructions and a systemd unit file to run the exporter directly on a Proxmox Backup Server host.

At the time of writing, this pull request is still open and not yet merged. Therefore, this guide uses the upstream project together with my fork to install and configure the exporter on Proxmox Backup Server.

Downloading the Packages

All required components are downloaded and installed directly on the Proxmox Backup Server. This includes the exporter binary for Linux amd64, a systemd unit file, and a dedicated system user for running the exporter service. Execute the following commands on your PBS host: 


# Download prometheus-pbs-exporter
mkdir /opt/pbs-exporter
cd /opt/pbs-exporter
wget https://github.com/natrontech/pbs-exporter/releases/download/v0.6.4/pbs-exporter_v0.6.4_linux_amd64.tar.gz
tar xfvz pbs-exporter_v0.6.4_linux_amd64.tar.gz
cp pbs-exporter-linux-amd64 /bin/

# Create a dedicated user for running the prometheus-pbs-exporter
useradd -m pbs-exporter -s /sbin/nologin

# Download systemd unit file (currently from gyptazy)
cd /etc/systemd/system
wget https://raw.githubusercontent.com/gyptazy/pbs-exporter/refs/heads/main/systemd/prometheus-pbs-exporter.service
systemctl daemon-reload

Configuration in Proxmox Backup Server GUI

Next, an API token is required so the pbs-exporter can access metrics from Proxmox Backup Server. Log in to the Proxmox Backup Server web interface and navigate to the Access Control section:

Select an existing user (for simplicity, root@pam) and use pbs-exporter as the token name. After creating the token, it is displayed only once. Make sure to store it securely, as it will be needed later.

Note: This setup is the quickest way to get started. For production environments, it is strongly recommended to create a dedicated user with limited permissions and a separate API token. When using a custom user, the systemd unit file must be adjusted accordingly, as the exporter defaults to root@pam with the token name pbs-exporter.

Configuration in Proxmox Backup Server CLI

After creating the API token, an environment file is required to store the exporter credentials. Create the file /etc/pbs-exporter.env, which is sourced by the systemd unit file. At minimum, this file must contain the API token. If a different user or token name is used, these values must be defined explicitly, as mentioned above.

Configuration

The exporter requires the API token to access metrics. Optionally, SSL certificate validation can be disabled if untrusted or self-signed certificates are used. For production environments, valid TLS certificates are strongly recommended. 


TOKEN=beef-1337-cafe-beef-cafe-1337
INSECURE=false

Once the environment file is in place, enable and start the exporter service using systemd: 


systemctl enable prometheus-pbs-exporter.service
systemctl start prometheus-pbs-exporter.service

Grafana Dashboard

The final step is importing the Grafana dashboard for the pbs-exporter. The project already provides a ready-to-use dashboard. Simply download the pbs-exporter Grafana dashboard and import it via the Grafana web interface to visualize Proxmox Backup Server metrics immediately.