From 19f49cf9613e56cb148ec34df8304c8d374c5217 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 14 Aug 2026 21:45:09 +0100 Subject: [PATCH] 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 | 6 ++++++ src/xrpld/telemetry/MetricsRegistry.cpp | 17 +++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/docker/telemetry/docker-compose.yml b/docker/telemetry/docker-compose.yml index 8aa2c3df64..7e3d01d182 100644 --- a/docker/telemetry/docker-compose.yml +++ b/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 # diff --git a/src/xrpld/telemetry/MetricsRegistry.cpp b/src/xrpld/telemetry/MetricsRegistry.cpp index 73af238945..40e434416d 100644 --- a/src/xrpld/telemetry/MetricsRegistry.cpp +++ b/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 #include #include