Added example alerting config

docs/README.md

@@ -9,6 +9,8 @@ and stores the latest values in the Prometheus registry exposed at `/metrics`.
   API token permissions, and collector switch.
 - [Metrics reference](metrics.md) lists exported metrics, labels, units, and
   numeric state mappings.
+- [Prometheus alerting](alerting.md) provides a ready-to-use rule group,
+  installation example, and collector requirements.
 - [Operations and troubleshooting](operations.md) covers native and container
   deployment, endpoint failover, logging, security, and common errors.
 - [Architecture and adding collectors](architecture.md) explains the collection

docs/alerting.md

@@ -0,0 +1,70 @@
+# Prometheus Alerting
+
+The repository includes a ready-to-use example rule group in
+[`examples/pve-exporter.rules.yml`](../examples/pve-exporter.rules.yml). It
+covers node, guest, storage, subscription, physical disk, ZFS, SDN, clock-skew,
+and memory-overcommit conditions.
+
+## Enable the rule file
+
+Make the rule file available to Prometheus and reference it from
+`prometheus.yml`:
+
+```yaml
+rule_files:
+  - /etc/prometheus/rules/pve-exporter.rules.yml
+
+scrape_configs:
+  - job_name: pve-exporter
+    static_configs:
+      - targets: [pve-exporter:9090]
+```
+
+For a containerized Prometheus deployment, mount the example at the configured
+path:
+
+```yaml
+services:
+  prometheus:
+    image: prom/prometheus:latest
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - ./examples/pve-exporter.rules.yml:/etc/prometheus/rules/pve-exporter.rules.yml:ro
+```
+
+Validate the file before reloading Prometheus:
+
+```sh
+promtool check rules examples/pve-exporter.rules.yml
+```
+
+## Collector requirements
+
+Prometheus evaluates a rule only when its referenced time series exist. Enable
+the matching exporter collectors:
+
+| Alerts | Required collector setting |
+| --- | --- |
+| Node filesystem, state, CPU, clock skew, memory overcommit | `metrics.nodeStatus` |
+| Guest CPU and memory overcommit | `metrics.qemu` and/or `metrics.lxc` |
+| Storage state and capacity | `metrics.storage` |
+| Subscription expiration | `metrics.subscription` |
+| Physical disk health and wear | `metrics.disk` |
+| ZFS state and errors | `metrics.zfs` |
+| SDN state | `metrics.sdn` |
+
+The default thresholds and `for` durations are operational examples. Review
+them against the size, workload, redundancy, and maintenance policy of your
+environment before enabling notifications.
+
+Three rules require deployment-specific review:
+
+- `PveUnexpectedStandaloneMode` should be removed or disabled when standalone
+  PVE operation is expected.
+- `PveNodeSubscriptionMissing` is informational and should be removed when
+  unsubscribed nodes are intentional.
+- `PveExporterDown` expects the Prometheus scrape job to be named
+  `pve-exporter`; adjust its `job` matcher if a different name is used.
+
+Every rule uses the `cluster` label. Standalone installations are supported and
+use the label value `Standalone node - <node>`.

docs/operations.md

@@ -48,6 +48,11 @@ scrape_configs:
 The Prometheus scrape interval and `proxmox.interval` are independent. A scrape
 does not contact PVE; it reads the latest values collected in the background.
 
+For alerting, load
+[`examples/pve-exporter.rules.yml`](../examples/pve-exporter.rules.yml) through
+Prometheus `rule_files`. The [alerting guide](alerting.md) lists the required
+collectors and a container mount example.
+
 ## API endpoint availability
 
 At startup and every five seconds, the exporter requests `api2/json/` from each