From 95fb21b5d5676a59c8f16003ec344b86f2614285 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Thu, 27 Aug 2026 12:58:45 +0100
Subject: [PATCH 1/2] docs(telemetry): drop the inert insight prefix from the
 OTel examples

OTelCollector routes every instrument name through a static formatName()
that only lowercases the name and maps '.' and space to '_'. The sole read
of prefix_ is the startup log line at OTelCollector.cpp:802, and all four
instrument factories go through formatName(), so no prefix can ever reach
an exported name. StatsDCollector does prepend it, so the StatsD example
keeps the key and now states why.

Covers the three server=otel blocks in the 09 reference and the config
integration-test.sh generates. This branch introduces OTelCollector, so it
is where the inert examples first appear; phase-6's examples are all
server=statsd and stay as they are.
---
 .../09-data-collection-reference.md           | 23 +++++++++++++++----
 docker/telemetry/integration-test.sh          |  6 ++++-
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md
index 6a1289d4f7..5d64e87394 100644
--- a/OpenTelemetryPlan/09-data-collection-reference.md
+++ b/OpenTelemetryPlan/09-data-collection-reference.md
@@ -537,15 +537,26 @@ These are system-level metrics emitted by xrpld's `beast::insight` framework via
 [insight]
 server=otel
 endpoint=http://localhost:4318/v1/metrics
-prefix=xrpld
 ```
 
+`server=otel` is the only key here that changes what gets exported. No `prefix` is
+shown because it would do nothing on this path: `OTelCollector` routes every
+instrument name through its `static formatName()`, which only lowercases the raw
+name and maps `.` and space to `_`, and the only place the class reads `prefix_`
+is its startup log line. Exported names are therefore the lowercased raw names
+(`jobq_job_count`, `rpc_requests_total`) and the service is identified by the OTel
+resource `service.name`, not by a name prefix. `endpoint` is read from this section
+but likewise reaches only that log line — the real exporter URL is derived inside
+`Telemetry::initMetrics()` from `[telemetry] endpoint`, by swapping the trailing
+`/v1/traces` for `/v1/metrics`.
+
 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.
+listens on. `prefix` does appear below, because `StatsDCollector` really does
+prepend it to every metric name it serializes — so switching transports renames
+every series.
 
 ```ini
 [insight]
@@ -967,7 +978,6 @@ enabled=1
 [insight]
 server=otel
 endpoint=http://localhost:4318/v1/metrics
-prefix=xrpld
 ```
 
 ### Production Setup
@@ -983,9 +993,12 @@ max_queue_size=4096
 [insight]
 server=otel
 endpoint=http://otel-collector:4318/v1/metrics
-prefix=xrpld
 ```
 
+Neither block sets `[insight] prefix`: on the `server=otel` path it is inert and
+would only mislead — see [§2 Configuration](#configuration). It applies solely to
+`server=statsd`.
+
 ### Trace Category Toggle
 
 | Config Key           | Default | Controls                     |
diff --git a/docker/telemetry/integration-test.sh b/docker/telemetry/integration-test.sh
index 4308e3e67c..b4b07a0f37 100755
--- a/docker/telemetry/integration-test.sh
+++ b/docker/telemetry/integration-test.sh
@@ -342,9 +342,13 @@ trace_peer=1
 trace_ledger=1
 
 [insight]
+# server=otel is the only load-bearing key here -- it selects OTelCollector so
+# beast::insight metrics leave over OTLP. No prefix is set on purpose: on this
+# path it is inert, because OTelCollector's formatName() only lowercases the raw
+# instrument name and the one place the class reads prefix_ is its startup log
+# line. The service is identified by the OTel resource service.name.
 server=otel
 endpoint=http://localhost:4318/v1/metrics
-prefix=rippled
 
 [rpc_startup]
 { "command": "log_level", "severity": "warning" }

From f9d482ba2bab4a8e2c9d91b44ae4a995b9b9b257 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Thu, 27 Aug 2026 12:58:57 +0100
Subject: [PATCH 2/2] fix(telemetry): drop insight keys the OTel collector
 discards from devnet cfg

The devnet config was missed when the mainnet one was corrected. On the
OTel path prefix is inert, because formatName() ignores it, and
service_instance_id is read and then discarded -- OTelCollector.cpp does
`(void)instanceId`. The service_instance_id label Prometheus shows comes
from [telemetry] service_instance_id, which this file still sets, so
dashboards keep filtering by node.

The comment removed here claimed every insight-backed panel goes empty
without the [insight] copy of the key. That is not the case.
---
 docker/telemetry/xrpld-telemetry.cfg | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/docker/telemetry/xrpld-telemetry.cfg b/docker/telemetry/xrpld-telemetry.cfg
index b362465b7a..325e195b95 100644
--- a/docker/telemetry/xrpld-telemetry.cfg
+++ b/docker/telemetry/xrpld-telemetry.cfg
@@ -108,15 +108,13 @@ data/logs/devnet/debug.log
 
 # --- Insight (native OTel metrics via beast::insight) -----------------------
 
+# server is the only key that changes behaviour here. No prefix: formatName()
+# ignores it, so names stay bare (jobq_job_count). service_instance_id is read
+# and discarded (OTelCollector.cpp `(void)instanceId`); the label Prometheus
+# shows comes from [telemetry] service_instance_id below.
 [insight]
 server=otel
 endpoint=http://localhost:4318/v1/metrics
-prefix=xrpld
-# Sets the OTel service.instance.id resource attribute, which Prometheus
-# exposes as the `service_instance_id` label. Dashboards filter on it via the
-# $node template variable, so without this every insight-backed panel is
-# empty. Matches [telemetry] service_instance_id for a single node identity.
-service_instance_id=xrpld-devnet
 
 # --- OpenTelemetry tracing --------------------------------------------------