docs(telemetry): explain the telemetry dependency loop and the Compose floor

Two comment-only notes.

MetricsRegistry.cpp: record why the app and overlay includes exist and
what they cost. They are what makes loops.txt carry
xrpld.app <-> xrpld.telemetry and xrpld.overlay <-> xrpld.telemetry, where
ordering.txt previously had telemetry strictly below both. The observable
gauges are pull-model, so their callbacks need the concrete types to
sample live state. The cycle is confined to this translation unit: no
telemetry header includes app or overlay, and all of src/xrpld builds
into one target, so there is no header or link cycle. Inverting it needs
a metrics-source interface below overlay, which is left as follow-up.
Also note loops.txt is generated and must never be hand-edited.

docker-compose.yml: state the Compose >= 2.24.0 floor. The grafana
service uses the long-form env_file mapping, which older Compose cannot
parse, and it fails for the whole file rather than that one service. The
long form is required because .env.alerting is gitignored and absent in a
fresh clone, and the short form treats a missing env file as an error.

docker/telemetry/docker-compose.yml

@@ -12,6 +12,12 @@
 #   - grafana: dashboards on port 3000, pre-configured with Tempo,
 #     Prometheus, and Loki datasources.
 #
+# Requires Docker Compose >= 2.24.0. The grafana service uses the long-form
+# `env_file` mapping (`path:` / `required:`), which older Compose cannot parse —
+# and it fails for the whole file, not just that service. The long form is
+# needed: `.env.alerting` is gitignored and absent in a fresh clone, and the
+# short form treats a missing env file as an error.
+#
 # Usage:
 #   docker compose -f docker/telemetry/docker-compose.yml up -d
 #

src/xrpld/telemetry/MetricsRegistry.cpp

@@ -24,6 +24,23 @@
 
 #ifdef XRPL_ENABLE_TELEMETRY
 
+// The app and overlay includes below are why
+// .github/scripts/levelization/results/loops.txt records
+// `xrpld.app <-> xrpld.telemetry` and `xrpld.overlay <-> xrpld.telemetry`, where
+// ordering.txt previously had telemetry strictly below both. The observable
+// gauges are pull-model: their callbacks sample live state when the reader
+// thread fires, so they need the concrete types to call getJqTransOverflow(),
+// size(), getPeerDisconnectCharges(), foreach() and txMetrics().
+//
+// The cycle is confined to this translation unit. No telemetry header includes
+// app or overlay (MetricsRegistry.h forward-declares what it needs and takes a
+// ServiceRegistry&), and all of src/xrpld builds into a single CMake target, so
+// there is no header cycle and no link cycle to break.
+//
+// Inverting it properly means declaring a metrics-source interface below overlay
+// and implementing it there, which is deliberately left as follow-up rather than
+// widening this change. Note loops.txt is generated: it can only change as a
+// consequence of changing these includes, never by editing the baseline.
 #include <xrpld/app/ledger/AcquireStats.h>
 #include <xrpld/app/ledger/InboundLedgers.h>
 #include <xrpld/app/ledger/LedgerMaster.h>