From e7980978c7a79e905dbf4bee09ba62cca83ef00a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= Date: Thu, 5 Feb 2026 00:52:39 +0100 Subject: [PATCH] docs: document monitoring auto-generation in CLAUDE.md Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7db25b4..74112e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -122,9 +122,10 @@ This ensures documentation matches the exact nixpkgs version (currently NixOS 25 - Core modules: nix.nix, sshd.nix, sops.nix, acme.nix, autoupgrade.nix - Monitoring: node-exporter and promtail on every host - `/modules/` - Custom NixOS modules - - `homelab/` - Homelab-specific options (DNS automation, etc.) + - `homelab/` - Homelab-specific options (DNS automation, monitoring scrape targets) - `/lib/` - Nix library functions - `dns-zone.nix` - DNS zone generation functions + - `monitoring.nix` - Prometheus scrape target generation functions - `/services/` - Reusable service modules, selectively imported by hosts - `home-assistant/` - Home automation stack - `monitoring/` - Observability stack (Prometheus, Grafana, Loki, Tempo) @@ -156,6 +157,7 @@ All hosts automatically get: - Internal ACME CA integration (ca.home.2rjus.net) - Daily auto-upgrades with auto-reboot - Prometheus node-exporter + Promtail (logs to monitoring01) +- Monitoring scrape target auto-registration via `homelab.monitoring` options - Custom root CA trust - DNS zone auto-registration via `homelab.dns` options @@ -310,7 +312,7 @@ This means: 11. Deploy by running `nixos-rebuild boot --flake URL#` on the host. 12. Run auto-upgrade on DNS servers (ns1, ns2) to pick up the new host's DNS entry -**Note:** DNS A records are auto-generated from the host's `systemd.network.networks` static IP configuration. No manual zone file editing is required. +**Note:** DNS A records and Prometheus node-exporter scrape targets are auto-generated from the host's `systemd.network.networks` static IP configuration. No manual zone file or Prometheus config editing is required. ### Important Patterns @@ -333,6 +335,23 @@ All hosts ship metrics and logs to `monitoring01`: - **Tracing**: Tempo for distributed tracing - **Profiling**: Pyroscope for continuous profiling +**Scrape Target Auto-Generation:** + +Prometheus scrape targets are automatically generated from host configurations, following the same pattern as DNS zone generation: + +- **Node-exporter**: All flake hosts with static IPs are automatically added as node-exporter targets +- **Service targets**: Defined via `homelab.monitoring.scrapeTargets` in service modules +- **External targets**: Non-flake hosts defined in `/services/monitoring/external-targets.nix` +- **Library**: `lib/monitoring.nix` provides `generateNodeExporterTargets` and `generateScrapeConfigs` + +Host monitoring options (`homelab.monitoring.*`): +- `enable` (default: `true`) - Include host in Prometheus node-exporter scrape targets +- `scrapeTargets` (default: `[]`) - Additional scrape targets exposed by this host (job_name, port, metrics_path, scheme, scrape_interval, honor_labels) + +Service modules declare their scrape targets directly (e.g., `services/ca/default.nix` declares step-ca on port 9000). The Prometheus config on monitoring01 auto-generates scrape configs from all hosts. + +To add monitoring targets for non-NixOS hosts, edit `/services/monitoring/external-targets.nix`. + ### DNS Architecture - `ns1` (10.69.13.5) - Primary authoritative DNS + resolver