From bca2b35bf01ada6dc161a9dcc803d076fa9687d4 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Mon, 24 Aug 2026 21:45:35 +0100 Subject: [PATCH] docs(telemetry): stop showing inert [insight] prefix on the OTel path ff8629bb11 dropped prefix=xrpld as inert and misleading, but four OTel-path sites still set it, so the branch contradicted itself. OTelCollector routes every instrument name through a static formatName() that only lowercases and maps '.'/space to '_'; the sole read of prefix_ is the startup log line at OTelCollector.cpp:810. All four instrument factories funnel through formatName(), so no prefix can reach an exported name. StatsDCollector does prepend it (StatsDCollector.cpp:551/592/640/715), so the StatsD example legitimately keeps it. Removed from the 09 reference's OTel config block and from both quick-reference setups, and from the cfg integration-test.sh generates. The StatsD example is unchanged and now states why it keeps the key. Also corrected run-full-validation.sh: [insight] endpoint was described as "already matches the built-in default", implying it would matter if it differed. CollectorManager reads it and hands it to OTelCollector, which also only logs it; the exporter URL is built in Telemetry::initMetrics() from [telemetry] endpoint. It is as inert as prefix was. --- .../09-data-collection-reference.md | 23 +++++++++++++++---- docker/telemetry/integration-test.sh | 6 ++++- .../telemetry/workload/run-full-validation.sh | 10 ++++++-- 3 files changed, 31 insertions(+), 8 deletions(-) diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md index 03b66bb9c9..61eb2e1fc4 100644 --- a/OpenTelemetryPlan/09-data-collection-reference.md +++ b/OpenTelemetryPlan/09-data-collection-reference.md @@ -598,15 +598,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] @@ -2168,7 +2179,6 @@ enabled=1 [insight] server=otel endpoint=http://localhost:4318/v1/metrics -prefix=xrpld ``` ### Production Setup @@ -2184,9 +2194,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 090ac28624..b24d90015a 100755 --- a/docker/telemetry/integration-test.sh +++ b/docker/telemetry/integration-test.sh @@ -397,9 +397,13 @@ trace_ledger=1 metrics_endpoint=http://localhost:4318/v1/metrics [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 service_instance_id=Node-${i} [rpc_startup] diff --git a/docker/telemetry/workload/run-full-validation.sh b/docker/telemetry/workload/run-full-validation.sh index 5acbbfbfc5..d5295c9b3e 100755 --- a/docker/telemetry/workload/run-full-validation.sh +++ b/docker/telemetry/workload/run-full-validation.sh @@ -331,8 +331,14 @@ trace_ledger=1 # Native OTel metrics via OTLP/HTTP. The collector has no StatsD receiver # (its metrics pipeline is [otlp, spanmetrics]), so beast::insight must export # over OTLP for system metrics to reach Prometheus at all. server=otel is the -# only load-bearing key here -- it selects the OTel collector; endpoint is -# read but already matches the built-in default. +# only load-bearing key here -- it selects the OTel collector. +# +# endpoint below is parsed but inert, exactly like prefix: CollectorManager +# reads it and hands it to OTelCollector, which uses it only in its startup log +# line. The URL the metric exporter actually posts to is derived in +# Telemetry::initMetrics() from [telemetry] endpoint, by swapping the trailing +# /v1/traces for /v1/metrics. It is kept here so the log line names the right +# URL; changing it would not redirect a single metric. # # No prefix is set on purpose. It would be inert: OTelCollector applies no # prefix to instrument names, so exported names are the lowercased raw names