Borgmatic Exporter

Borgmatic Exporter seamlessly integrates Prometheus metrics and Borgmatic. This project is based on the borg-exporter by @danihodovic, however it introduces a few changes:

• extra metrics
• native integration with the official Borgmatic docker image
• results caching

Metrics

Name	Type
borg_total_backups	Gauge
borg_total_chunks	Gauge
borg_total_size	Gauge
borg_total_compressed_size	Gauge
borg_total_deduplicated_size	Gauge
borg_total_deduplicated_compressed_size	Gauge
borg_last_backup_timestamp	Gauge
borg_last_backup_duration	Gauge
borg_last_backup_files	Gauge
borg_last_backup_deduplicated_compressed_size	Gauge
borg_last_backup_compressed_size	Gauge
borg_last_backup_size	Gauge

Installation

Docker

Recommended way of using Borgmatic Exporter is through Docker. The image is based on the official docker-borgmatic image, and it seamlessly integrates Prometheus metrics into the distribution by running both Borgmatic entrypoint and exporter server in parallel. All images are available here.

docker pull ghcr.io/maxim-mityutko/borgmatic-exporter:latest

1. Configure Borgmatic: https://github.com/borgmatic-collective/docker-borgmatic/blob/master/README.md

2. Configure Borgmatic Exporter:

   Borgmatic Exporter supports the following environment variables for customization:

   Name	Description	Default
   BORGMATIC_CONFIG	One or multiple references to Borgmatic configuration files	/etc/borgmatic.d/config.yml
   BORGMATIC_EXPORTER_HOST	Host for the metrics server	0.0.0.0
   BORGMATIC_EXPORTER_PORT	Port for the metrics server	9996
   BORGMATIC_EXPORTER_TIME	Display time each Borgmatic call takes	false
   BORGMATIC_EXPORTER_CACHE_TIMEOUT	Cache the response of the metrics endpoint for the given number of seconds	600

Notes

• Use colon (:) if multiple configs should be provided through the environment variable BORGMATIC_CONFIG, e.g. /etc/borgmatic/config_1.yml:/etc/borgmatic/config_2.yml
• If keyfiles need to be provided to Borgmatic Exporter, mount the volume containing the keys to both /root/.config/borg and /tmp/borgmatic-exporter-cache/.config/borg (ref: #43)
• Set BORGMATIC_EXPORTER_CACHE_TIMEOUT environment variable to 0 to disable metrics caching

Local

Install and configure borgmatic by following the instructions in the official repository, then install Borgmatic Exporter

git clone https://github.com/maxim-mityutko/borgmatic-exporter.git
pip install -Ur requirements.txt
python3 cli.py run -c <path-to-your-borgmatic-config-yml>

Observability and Monitoring

Grafana

• Global view

• Repository details view Dashboard is available in the repo or on Grafana's Dashboard Library.

Alerts

Alerting rules can be found here. By default alert will be triggered if there is no backup for repository within 25 hours.

Development

Local Environment

• Install Poetry
• Use provided Makefile to setup environment: make dev
• Run tests: make test

Docker

• Build and run

  docker build -t borgmatic:tag .
  docker run --name borgmatic borgmatic:tag

• Rename or remove existing container, if the same name is already in use

  docker container ls -a
  docker container rm container-id

• Exec into the container and create config

  docker exec -it borgmatic /bin/sh
  
  borgmatic config generate
  
  # The default config will have entries for both remote and local repo
  # Remote repo config should be commented before proceeding
  vi /etc/borgmatic/config.yaml
  
  borgmatic init --encryption repokey

• Misc

  # Output repo info in JSON format
  borgmatic info --json --last 1
  # Create backup
  borgmatic create
  # Run exporter
  python3 cli.py run --config /etc/borgmatic/config.yaml