lostakj
92e54418bc
Use base units, export cumulative values as _total counters, update docs, dashboards and rules.
114 lines
3.6 KiB
Markdown
114 lines
3.6 KiB
Markdown
# Configuration Reference
|
|
|
|
The exporter reads `config.yaml` from the current working directory by default.
|
|
Use `-config` to select a different file:
|
|
|
|
```sh
|
|
./pve-exporter -config /etc/pve-exporter/config.yaml
|
|
```
|
|
|
|
## Complete example
|
|
|
|
```yaml
|
|
host: 0.0.0.0
|
|
port: 9090
|
|
logLevel: 4
|
|
|
|
proxmox:
|
|
token:
|
|
tokenId: monitoring@pve!exporter
|
|
secret: change-me
|
|
|
|
hosts:
|
|
- https://192.168.0.10:8006
|
|
- https://pve02.example.com:8006/
|
|
|
|
interval: 15
|
|
|
|
metrics:
|
|
clusterState: true
|
|
nodeStatus: true
|
|
qemu: true
|
|
lxc: true
|
|
disk: true
|
|
zfs: true
|
|
storage: true
|
|
subscription: true
|
|
sdn: true
|
|
```
|
|
|
|
## Server settings
|
|
|
|
| Setting | Type | Description |
|
|
| --- | --- | --- |
|
|
| `host` | IP address | Address on which the exporter HTTP server listens, for example `0.0.0.0` or `127.0.0.1`. DNS names are not accepted here. |
|
|
| `port` | integer | Exporter HTTP port. Prometheus metrics are served at `/metrics`. |
|
|
| `logLevel` | integer | Logrus level: `0=Panic`, `1=Fatal`, `2=Error`, `3=Warn`, `4=Info`, `5=Debug`, `6=Trace`. |
|
|
|
|
## Proxmox token
|
|
|
|
| Setting | Type | Description |
|
|
| --- | --- | --- |
|
|
| `proxmox.token.tokenId` | string | Full Proxmox API token ID, normally `user@realm!token-name`. |
|
|
| `proxmox.token.secret` | string | API token secret. Treat the configuration file as sensitive. |
|
|
|
|
Create a dedicated monitoring user and token, then assign the read-only
|
|
`PVEAuditor` role to both the user and the token. The role supplies the audit
|
|
permissions used by cluster, node, storage, disk, ZFS, guest, and subscription
|
|
API calls.
|
|
|
|
## API hosts and failover
|
|
|
|
`proxmox.hosts` is a non-empty list of Proxmox API base URLs. Both IP addresses
|
|
and DNS names are supported:
|
|
|
|
```yaml
|
|
proxmox:
|
|
hosts:
|
|
- https://192.168.0.10:8006
|
|
- https://pve02.example.com:8006/
|
|
```
|
|
|
|
A trailing slash is optional and normalized automatically. Every host must use
|
|
`http` or `https` and must belong to the same PVE cluster. The exporter checks
|
|
endpoint liveness every five seconds and distributes API requests across the
|
|
currently reachable endpoints.
|
|
|
|
Do not combine unrelated clusters in one list. Their API responses share the
|
|
same short-lived client cache and Prometheus registry. Run a separate exporter
|
|
for each cluster.
|
|
|
|
## Collection interval
|
|
|
|
`proxmox.interval` is the positive number of seconds between collection cycles.
|
|
The first cycle runs during application startup. Prometheus scrapes only the
|
|
values already present in the registry, so its scrape interval does not control
|
|
the PVE API request rate.
|
|
|
|
## Collector switches
|
|
|
|
All switches are booleans. Omitted switches default to `false`.
|
|
|
|
| Setting | Collector | Main metric prefix |
|
|
| --- | --- | --- |
|
|
| `clusterState` | Cluster mode, node count, and quorum | `pve_cluster_` |
|
|
| `nodeStatus` | Node health and resource usage | `pve_node_` |
|
|
| `qemu` | QEMU virtual machines | `pve_vm_` |
|
|
| `lxc` | LXC containers | `pve_ct_` |
|
|
| `disk` | Physical disk health and metadata | `pve_node_disk_` |
|
|
| `zfs` | ZFS pool topology, state, and errors | `pve_node_zfs_` |
|
|
| `storage` | Enabled PVE storage status and capacity | `pve_storage_` |
|
|
| `subscription` | Node subscription information | `pve_node_subscription_` |
|
|
| `sdn` | Software-defined network state | `pve_sdn_` |
|
|
|
|
The exporter-level `pve_metrics_collection_duration_seconds` summary is always
|
|
registered.
|
|
|
|
## Validation notes
|
|
|
|
- `host` must be a literal IP address.
|
|
- At least one Proxmox API host is required.
|
|
- API host URLs require an `http` or `https` scheme and an IP or DNS hostname.
|
|
- Token ID and secret cannot be empty.
|
|
- Keep `proxmox.interval` greater than zero and `logLevel` between `0` and `6`.
|