From 29845aa117ded97113646acd253ffd1b6fa12606 Mon Sep 17 00:00:00 2001
From: Romain Paquet <rpqt@rpqt.fr>
Date: Wed, 29 Oct 2025 12:50:12 +0100
Subject: [PATCH] add description of prometheus service

---
 clanServices/prometheus/README.md   | 38 +++++++++++++++++++++++++++++
 clanServices/prometheus/default.nix |  4 +++
 2 files changed, 42 insertions(+)
 create mode 100644 clanServices/prometheus/README.md

diff --git a/clanServices/prometheus/README.md b/clanServices/prometheus/README.md
new file mode 100644
index 0000000..01c8a77
--- /dev/null
+++ b/clanServices/prometheus/README.md
@@ -0,0 +1,38 @@
+This module enables collecting metrics from machines in clan, using Prometheus.
+
+There are two roles:
+
+- A `target` role for machines on which to collect and export metrics.
+- A `scraper` roles for machines that fetch metrics from `target` machines and
+  store them in the long term.
+
+
+```nix
+inventory = {
+
+  machines = {
+    server01.tags.server = {};
+    server02.tags.server = {};
+    metrics.tags.server = {}; # metrics collector
+  };
+
+  instances = {
+    prometheus = {
+      module.name = "@rpqt/prometheus";
+      module.input = "self";
+
+      roles.scraper.machines."metrics" = {};
+
+      # Collect metrics on all servers
+      roles.target.tags.server = {
+        settings = {
+          exporters = {
+            # Enable the node-exporter metrics source
+            node.enabledCollectors = [ "systemd" ];
+          };
+        };
+      };
+    };
+  };
+};
+```
diff --git a/clanServices/prometheus/default.nix b/clanServices/prometheus/default.nix
index a5a5e68..d034f42 100644
--- a/clanServices/prometheus/default.nix
+++ b/clanServices/prometheus/default.nix
@@ -3,10 +3,13 @@
 {
   _class = "clan.service";
   manifest.name = "prometheus";
+  manifest.description = "Prometheus metrics collection across the clan network.";
+  manifest.readme = builtins.readFile ./README.md;
 
   # Only works with zerotier (until a unified network module is ready)
 
   roles.scraper = {
+    description = "A server that scrapes metrics from exporters of machines that have the 'target' role.";
     interface = {
       options.extraScrapeConfigs = lib.mkOption {
         type = lib.types.listOf lib.types.attrs;
@@ -63,6 +66,7 @@
   };
 
   roles.target = {
+    description = "A machine on which to collect and export metrics.";
     interface =
       { lib, ... }:
       {