1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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 to check for
available package 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.
|
