From f9f97eb41d13f9ac6390e43a7c4bab911b31f1d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= Date: Sun, 8 Feb 2026 23:39:08 +0100 Subject: [PATCH] docs: add NATS cache sharing documentation Document the new NATS cache sharing feature added in v0.3.0: - Add CLI flags for NATS configuration - Add NixOS module options under flake.nats - Add dedicated section explaining the feature Co-Authored-By: Claude Opus 4.5 --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 3cc7ffb..07c2643 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,10 @@ nix build | `--collector.flake` | `false` | Enable flake collector | | `--flake.url` | | Flake URL for revision comparison (required if flake collector enabled) | | `--flake.check-interval` | `1h` | Interval between remote flake checks | +| `--flake.nats.enable` | `false` | Enable NATS cache sharing | +| `--flake.nats.url` | `nats://localhost:4222` | NATS server URL | +| `--flake.nats.subject` | `nixos-exporter.remote-rev` | NATS subject for revision updates | +| `--flake.nats.credentials-file` | | NATS credentials file (optional) | ## NixOS Module Options @@ -58,6 +62,13 @@ services.prometheus.exporters.nixos = { enable = false; url = ""; # Required if flake.enable = true checkInterval = "1h"; + + nats = { + enable = false; + url = "nats://localhost:4222"; + subject = "nixos-exporter.remote-rev"; + credentialsFile = null; # Optional path to credentials file + }; }; }; ``` @@ -160,6 +171,19 @@ groups: - The `nixos_flake_revision_behind` metric requires `system.configurationRevision` to be set. Without it, the metric will always be 0 since there's no local revision to compare against. +## NATS Cache Sharing + +When running multiple nixos-exporter instances across different hosts, NATS cache sharing allows them to share remote revision data. This reduces the number of `nix flake metadata` calls and ensures all hosts see updates faster. + +When enabled: +- Hosts publish their remote revision when they fetch new data +- Hosts subscribe to receive updates from other hosts +- Updates are filtered by flake URL to avoid cross-contamination +- Auto-reconnect handles NATS server restarts gracefully +- Falls back to local fetching if NATS is unavailable + +Additionally, smart cache refresh is enabled: when the current system revision matches the cached remote revision, the exporter immediately checks for newer revisions instead of waiting for the next scheduled check. + ## License MIT