From 77f338c0d08f145b66229b568513de65c5b8cf0f Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Mon, 17 Aug 2026 11:42:21 +0100
Subject: [PATCH] docs(telemetry): correct statsd config guidance for the
 native OTel path

09-data-collection-reference.md contradicted itself. Section 2 presents
server=otel as the recommended transport with StatsD as a fallback, but
the Known Issues table and both Configuration Quick Reference examples
still prescribed server=statsd, which on this branch reaches a collector
with no statsd receiver and an unpublished 8125/udp.

Switch the Known Issues row and the Minimal and Production examples to
server=otel with the OTLP metrics endpoint. Keep the labelled fallback
block, and state what it actually requires: re-adding the statsd
receiver and republishing the port. Also record that StatsDCollector
applies prefix to metric names while OTelCollector does not, so the two
transports do not produce the same series.

The phase-6 copy is left alone; server=statsd is correct there.
---
 .../09-data-collection-reference.md             | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md
index 1405987f52..ef3e97c0bf 100644
--- a/OpenTelemetryPlan/09-data-collection-reference.md
+++ b/OpenTelemetryPlan/09-data-collection-reference.md
@@ -530,7 +530,12 @@ endpoint=http://localhost:4318/v1/metrics
 prefix=xrpld
 ```
 
-Fallback (StatsD):
+Fallback (StatsD). `StatsDCollector` is still selected by this value, but the
+stack in `docker/telemetry/` no longer receives it: using this path also requires
+re-adding the `statsd` receiver to `otel-collector-config.yaml` and uncommenting
+port 8125 in `docker-compose.yml`, otherwise the metrics go to a port nothing
+listens on. Note also that `StatsDCollector` applies `prefix` to the metric name
+while `OTelCollector` does not, so switching transports renames every series.
 
 ```ini
 [insight]
@@ -920,7 +925,7 @@ state_accounting_full_duration
 | ------------------------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------- |
 | `warn` and `drop` metrics use non-standard StatsD `\|m` meter type | Metrics silently dropped by OTel StatsD receiver | Phase 6 Task 6.1 — needs `\|m` → `\|c` change in StatsDCollector.cpp |
 | `job_count` may not emit in standalone mode                        | Missing from Prometheus in some test configs     | Requires active job queue activity                                   |
-| `rpc_requests` depends on `[insight]` config                       | Zero series if StatsD not configured             | Requires `[insight] server=statsd` in xrpld.cfg                      |
+| `rpc_requests` depends on `[insight]` config                       | Zero series if `[insight]` is absent or unset    | Requires `[insight] server=otel` in xrpld.cfg                        |
 | Peer tracing enabled by default                                    | `peer.*` spans emit unless `trace_peer=0`        | High volume — set `trace_peer=0` to opt out on busy mainnet nodes    |
 
 ---
@@ -950,8 +955,8 @@ The telemetry system is designed with privacy in mind:
 enabled=1
 
 [insight]
-server=statsd
-address=127.0.0.1:8125
+server=otel
+endpoint=http://localhost:4318/v1/metrics
 prefix=xrpld
 ```
 
@@ -966,8 +971,8 @@ batch_size=1024
 max_queue_size=4096
 
 [insight]
-server=statsd
-address=otel-collector:8125
+server=otel
+endpoint=http://otel-collector:4318/v1/metrics
 prefix=xrpld
 ```