docs: Improve wording

Author: simonvanlierde

README.md

@@ -1,8 +1,8 @@
 # Observability stack
 
-Central Grafana + Loki + Tempo + Prometheus + OTel Collector, wired together
-with logs ↔ traces ↔ metrics correlation. Meant to run on one host and
-receive telemetry from multiple projects over OTLP.
+One host running Grafana, Loki, Tempo, Prometheus, and an OpenTelemetry
+Collector, wired so logs, traces, and metrics cross-link. Point any number of
+projects at it over OTLP and their telemetry lands in one place.
 
 ```mermaid
 flowchart LR
@@ -42,7 +42,7 @@ Tear it down with `just demo-down`.
 
 ## Layout
 
-```
+```sh
 compose.yml             # core services
 compose.tunnel.yml      # production overlay: Cloudflare Tunnel
 compose.demo.yml        # demo overlay: sample telemetry source
@@ -130,13 +130,16 @@ Everything persists to local Docker volumes (`loki_data`, `tempo_data`,
 
 ## Design decisions
 
-Everything enters through **one OTLP gateway** (the collector), so projects
-configure a single endpoint and the backends can be swapped without touching
-any app. The stack is **single-host by design** — CML's telemetry volume
-doesn't justify distributed ingest, and one compose file is auditable — with
-a documented scale-out path (S3-backed Loki/Tempo above) when it stops
-fitting. Logs keep **label cardinality low** (`service`, `env`, `host` only;
-everything else is query-time filtering) because high-cardinality labels are
-how Loki installs fall over. RED metrics are **derived from traces** by
-Tempo's metrics generator, so any service that sends traces gets the
-Service Health dashboard for free, instrumented or not.
+Everything enters through one gateway — the collector — so a project
+configures a single OTLP endpoint, and a backend can be swapped without
+touching any app. It runs on one host on purpose: CML's telemetry is a handful
+of services at single-digit requests per second, so distributed ingest would
+add operational weight for no gain, while one compose file stays auditable by a
+single person. When local disk runs short, S3-backed Loki and Tempo (above)
+are the documented way out.
+
+Logs carry only low-cardinality labels — `service`, `env`, `host` — and
+everything else is a query-time filter; high-cardinality labels are the usual
+way a Loki install falls over. And because Tempo's metrics generator derives
+RED metrics from spans, any service that sends traces gets the Service Health
+dashboard whether or not it emits metrics of its own.

docs/adr/0001-observability-stack.md

@@ -4,11 +4,10 @@ Date: 2026-07-03. Status: accepted (records a decision already in production).
 
 ## Context
 
-CML runs several research platforms (RELab and others) that need logs,
-traces, and metrics in one place. Telemetry volume is modest — a handful of
-services, single-digit requests per second — but the projects are
-long-lived, maintained by a very small team, and must stay cheap and
-auditable.
+CML runs several long-lived research platforms (RELab and others) that need
+their logs, traces, and metrics in one place. The volume is modest — a handful
+of services at single-digit requests per second — but one small team maintains
+all of it, so whatever we run must stay cheap and auditable.
 
 ## Decision
 
@@ -17,34 +16,33 @@ the only ingestion endpoint, fanning out to Loki (logs), Tempo (traces), and
 Prometheus (metrics), with Grafana on top. Expose Grafana and the OTLP
 endpoints via Cloudflare Tunnel; bind everything else to `127.0.0.1`.
 
-- **OTLP-native:** projects configure one endpoint and one protocol.
-  Backends can be swapped (or moved to hosted equivalents) without touching
-  any application.
-- **Single-host:** one compose file is something one person can fully audit
-  and rebuild. Distributed ingest (Kubernetes, Mimir, multi-tenant Loki)
-  buys nothing at this volume and costs ongoing operational attention.
+- **OTLP-native:** one endpoint, one protocol. Swap a backend or move it to a
+  hosted equivalent without touching any application.
+- **Single-host:** one compose file one person can audit and rebuild.
+  Distributed ingest (Kubernetes, Mimir, multi-tenant Loki) would add operational
+  overhead for no benefit at this volume.
 - **Traces as the primary signal:** Tempo's metrics generator derives RED
-  metrics and a service graph from spans, so a service that only sends
-  traces still gets dashboards and error-rate alerting.
+  metrics and a service graph from spans, so a service that only sends traces
+  still gets dashboards and error-rate alerting.
 
 ## Alternatives considered
 
-- **Grafana Cloud / hosted SaaS:** less to operate, but recurring cost,
-  data residency questions for research data, and less useful as
-  institutional infrastructure knowledge.
-- **Per-project stacks:** no shared endpoint to maintain, but duplicates
-  storage and Grafana per project and makes cross-project correlation
-  impossible.
-- **ELK / OpenSearch:** heavier to run, log-centric; weaker native OTLP and
-  trace correlation story than the Grafana stack.
+- **Grafana Cloud / hosted SaaS:** less to operate, but a recurring bill,
+  data-residency questions for research data, and little institutional
+  infrastructure knowledge to show for it.
+- **Per-project stacks:** no shared endpoint to maintain, but each project
+  duplicates its own storage and Grafana, and cross-project correlation
+  becomes impossible.
+- **ELK / OpenSearch:** heavier to run and log-centric, with a weaker native
+  OTLP and trace-correlation story than the Grafana stack.
 
 ## Consequences
 
-- The host is a single point of failure; acceptable because the monitored
-  platforms degrade gracefully without telemetry (OTLP export is
+- The host is a single point of failure — acceptable, because the monitored
+  platforms degrade gracefully when telemetry stops (OTLP export is
   fire-and-forget) and the stack rebuilds from this repo in minutes.
-- Local disk bounds retention (30d logs/metrics, 7d traces). The documented
-  escape hatch is S3-compatible storage for Loki/Tempo — see
-  `compose.storage.s3.yml` — before any move to distributed ingest.
-- Everything is pinned and validated by `just check` in CI, so the stack
+- Local disk bounds retention (30d logs/metrics, 7d traces). The escape hatch,
+  reached before any move to distributed ingest, is S3-compatible storage for
+  Loki and Tempo — see `compose.storage.s3.yml`.
+- Every image is pinned and validated by `just check` in CI, so the stack
   stays reproducible.