diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..4a5e90f --- /dev/null +++ b/README.md @@ -0,0 +1,131 @@ +<!-- +SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> + +SPDX-License-Identifier: BSD-3-Clause +--> + +# prometheus-pacman-exporter + +A Prometheus metrics exporter for [pacman](https://archlinux.org/pacman/), +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.12+ +- pacman +- checkupdates (optional) +- An AUR helper or other update command (optional) + +## Installation + +```bash +pip install prometheus-pacman-exporter +``` + +## Usage + +``` +Usage: prometheus-pacman-exporter [OPTIONS] + + Collect pacman package metrics and export them for Prometheus. + + Queries pacman for installed package statistics and available updates, then + writes them to a .prom file for consumption by the Prometheus node exporter + textfile collector. + + By default, updateable packages are determined using pacman --query + --upgrades. Use --use-checkupdates to query updates with checkupdates + instead. AUR update metrics can optionally be collected by providing --aur + together with --aur-command. + +Options: + --textfile-collector-dir DIRECTORY + Directory where the Prometheus collector + textfile will be written. + [default: /var/lib/prometheus/node-exporter] + --use-checkupdates Use checkupdates instead of pacman --query + --upgrades to check for available updates. + --aur Include AUR updates. + --aur-command TEXT Command used to check for AUR updates. + --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). + -q, --quiet Suppress all non-error output. + -v, --verbose Enable verbose output. + --version Show version information and exit. + -h, --help, -? Show this message and exit. +``` + +### Checking for updates + +By default, available repository updates are determined using: + +```bash +pacman --query --upgrades +``` + +This only reports updates already known to the local package database. + +Use `--use-checkupdates` to instead use +[`checkupdates`](https://man.archlinux.org/man/checkupdates.8), which checks +for available updates without modifying the system's package database: + +```bash +prometheus-pacman-exporter --use-checkupdates +``` + +### AUR updates + +AUR updates can be included with `--aur`. An update command must also be +provided with `--aur-command`: + +```bash +prometheus-pacman-exporter \ + --aur \ + --aur-command "paru --query --upgrades --aur" +``` + +The AUR command may use any AUR helper or custom program, provided its standard +output contains **exactly one available package update per line**. The exporter +counts the number of output lines; it does not interpret the contents of those +lines. + +For example, output such as: + +```text +package-one 1.2.3-1 -> 1.2.4-1 +package-two 4.5.6-1 -> 4.6.0-1 +``` + +is interpreted as two available AUR updates. + +Diagnostic or informational messages from the command should therefore be +written to standard error rather than standard output. + +The value of `--aur-command` is split into command-line arguments and executed +directly. It is not executed through a shell, so shell features such as pipes, +redirections, variable expansion, and command substitution are not available. + +## Metrics + +| Metric | Description | +| -------------------------------- | -------------------------------------------------- | +| `pacman_installed_packages` | Total number of installed packages | +| `pacman_explicit_packages` | Number of explicitly installed packages | +| `pacman_depends_packages` | Number of packages installed as dependencies | +| `pacman_unrequired_packages` | Number of packages not required by another package | +| `pacman_foreign_packages` | Number of packages not present in sync databases | +| `pacman_native_packages` | Number of packages present in sync databases | +| `pacman_orphan_packages` | Number of orphaned dependency packages | +| `pacman_updateable_packages` | Number of available repository package updates | +| `pacman_aur_updateable_packages` | Number of available AUR package updates | + +The AUR update metric is only collected when `--aur` is enabled. + +## License + +BSD-3-Clause. See [LICENSE](LICENSES/BSD-3-Clause.txt) for details. |