<!--
SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>

SPDX-License-Identifier: BSD-3-Clause
-->

# prometheus-borgmatic-exporter

A Prometheus metrics exporter for [borgmatic](https://torsion.org/borgmatic/),
designed to be run via a systemd timer and consumed by the [node exporter
textfile
collector](https://github.com/prometheus/node_exporter#textfile-collector).

## Requirements

- Python 3.11+
- borgmatic

## Installation

```bash
pip install prometheus-borgmatic-exporter
```

## Usage

```
Usage: prometheus-borgmatic-exporter [OPTIONS]

  Collect borgmatic repository metrics and export them for Prometheus.

  Queries borgmatic for repository and archive statistics and writes them
  to a .prom file for consumption by the Prometheus node exporter textfile
  collector.

  By default only the latest archive is queried per repository. Use
  --all-archives to collect metrics for every archive, at the cost of
  a significantly longer runtime.

  Using --all-archives will create one time series per archive and may
  significantly increase Prometheus storage usage.

Options:
  --borgmatic-bin PATH           Path to the borgmatic executable.
                                 [default: /usr/bin/borgmatic]
  --borgmatic-config PATH        Configuration file or directory. Can be
                                 specified multiple times. If not
                                 specified, borgmatic's default
                                 configuration discovery is used.
  --textfile-collector-dir PATH  Directory where the Prometheus collector
                                 textfile file will be written.
                                 [default: /var/lib/prometheus/node-exporter]
  --all-archives                 Collect metrics for all archives instead
                                 of only the latest archive. This can
                                 significantly increase runtime and
                                 Prometheus storage usage.
  -q, --quiet                    Suppress all non-error output.
  -v, --verbose                  Enable verbose output.
  --version                      Show version information and exit.
  --color [auto|always|never]    Colorize the output. A bare --color is
                                 the same as --color=always.
                                 [default: auto]
  --no-color                     Disable colorization (alias of
                                 --color=never).
  -h, --help, -?                 Show this message and exit.
```

## Metrics

All metrics carry the labels `repository_id`, `repository_label`, and `location`.

### Repository metrics

| Metric                                          | Description                                    |
| ----------------------------------------------- | ---------------------------------------------- |
| `borg_total_chunks`                             | Total number of chunks across all archives     |
| `borg_total_compressed_size_bytes`              | Total compressed size of all chunks            |
| `borg_total_original_size_bytes`                | Total original size of all chunks              |
| `borg_total_unique_chunks`                      | Number of unique chunks (deduplicated)         |
| `borg_total_deduplicated_compressed_size_bytes` | Compressed size of unique chunks               |
| `borg_total_deduplicated_size_bytes`            | Original size of unique chunks                 |
| `borg_last_modified_timestamp_seconds`          | Unix timestamp of last repository modification |
| `borg_archives`                                 | Total number of archives in the repository     |
| `borg_repository_encryption_info`               | Encryption mode as an info metric              |

### Latest archive metrics

| Metric                                        | Description                             |
| --------------------------------------------- | --------------------------------------- |
| `borg_latest_archive_compressed_size_bytes`   | Compressed size of the latest archive   |
| `borg_latest_archive_deduplicated_size_bytes` | Deduplicated size of the latest archive |
| `borg_latest_archive_files_total`             | Number of files in the latest archive   |
| `borg_latest_archive_original_size_bytes`     | Original size of the latest archive     |
| `borg_latest_archive_duration_seconds`        | Duration of the latest archive creation |

### Per-archive metrics (--all-archives only)

These metrics additionally carry `archive_id` and `archive_name` labels.

| Metric                                 | Description                      |
| -------------------------------------- | -------------------------------- |
| `borg_archive_compressed_size_bytes`   | Compressed size of the archive   |
| `borg_archive_deduplicated_size_bytes` | Deduplicated size of the archive |
| `borg_archive_files_total`             | Number of files in the archive   |
| `borg_archive_original_size_bytes`     | Original size of the archive     |
| `borg_archive_duration_seconds`        | Duration of the archive creation |

## License

BSD-3-Clause. See [LICENSE](LICENSES/BSD-3-Clause.txt) for details.