diff --git a/docs/swarm/services.md b/docs/swarm/services.md
index 94ef096e..a95aeacd 100644
--- a/docs/swarm/services.md
+++ b/docs/swarm/services.md
@@ -61,3 +61,37 @@ See [`sso.md`](sso.md) for bootstrapping the first user and the OIDC
 relying-party flow, and [`secrets.md`](secrets.md) for where each of
 authelia's keys is generated and read.
 
+### Metrics (VictoriaMetrics + Grafana)
+
+The swarm's telemetry lands in one VictoriaMetrics and is read through
+one Grafana, in two containers at `metrics.<swarm-domain>` and
+`grafana.<swarm-domain>`. Two containers rather than one so Grafana can
+be restarted or broken without taking the time-series database with it.
+
+Both are **opt-in** — unlike authelia and matrix they do not follow
+`swarm.enableRequiredServices`, because turning them on starts a
+database that grows for as long as the swarm runs:
+
+```nix
+services.hyperhive.swarm.victoriametrics.enable = true;
+services.hyperhive.swarm.grafana.enable = true;
+```
+
+| Option | When you'd touch it |
+|---|---|
+| `swarm.victoriametrics.retentionPeriod` | Default `5y`. Lower it once you have measured how fast this swarm actually fills a disk — the default is deliberately generous because too-short silently discards history you cannot get back. |
+| `swarm.grafana.oidc.role` | Default `Admin` for everyone who logs in. Lower to `Viewer`/`Editor` if the swarm grows operators who should not be able to reconfigure Grafana. |
+| `swarm.grafana.datasourceUrl` | Only if you front VictoriaMetrics with something else. It defaults to the store on this host, which is the only thing it can reach. |
+
+**Logging in.** Grafana is behind swarm SSO, so the accounts are the
+authelia ones — there is no separate Grafana password, and the local
+login form is switched off whenever SSO is configured. If you enable
+Grafana on a host with no authelia, the form stays on and Grafana's
+default `admin`/`admin` applies; change it before exposing that host.
+
+The metrics **arrive** from the swarm's OTEL collector, not from agents
+directly — see [`../observability.md`](../observability.md). Neither
+container is reachable except through the gateway: both bind loopback,
+and VictoriaMetrics' write endpoint takes no credential, so the
+collector is the only intended writer.
+