feat: implement initial borgmatic Prometheus exporterv1.0.0

1 files changed, 97 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5dc82ff
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# 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        Path to the borgmatic configuration file.
+                                 [default: /etc/borgmatic/config.yaml]
+  --textfile-collector-dir PATH  Directory where the .prom file will be
+                                 written.
+                                 [default: /var/lib/prometheus/node-exporter]
+  --all-archives                 Collect metrics for all archives, not just
+                                 the latest. Significantly slower for large
+                                 repositories.
+  -q, --quiet                    Suppress all non-error output.
+  -v, --verbose                  Enable verbose output.
+  --color / --no-color           Force or disable colored output.
+  --version                      Show version information and exit.
+  -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.