From 55a674f042214ea9f537210d36b82931ac7cc8bd Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Wed, 10 Jun 2026 10:03:31 +0100
Subject: [PATCH] docs(telemetry): remove sampling_ratio knob from phase-6 docs
 and configs

Head sampling is fixed at 1.0 and not configurable. Drop sampling_ratio
from the docker sample/test configs and the data-collection reference;
rewrite the span-metric sampling caveat and volume guidance to point at
collector-side tail sampling.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 OpenTelemetryPlan/09-data-collection-reference.md | 13 ++++++-------
 docker/telemetry/TESTING.md                       |  1 -
 docker/telemetry/integration-test.sh              |  1 -
 docker/telemetry/xrpld-telemetry.cfg              |  1 -
 4 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md
index 12504d6490..7d4555d7d0 100644
--- a/OpenTelemetryPlan/09-data-collection-reference.md
+++ b/OpenTelemetryPlan/09-data-collection-reference.md
@@ -403,11 +403,11 @@ The `stage` dimension (3 values: `preflight`, `preclaim`, `apply`) turns the
 apply-pipeline spans into per-stage RED metrics with no native instruments — the
 _Transaction Overview_ dashboard charts rate, p95 latency, and failure rate by stage.
 
-> **Sampling caveat**: span-derived metrics inherit the **tracer head-sampling**
-> ratio (`sampling_ratio` in `[telemetry]`, via `TraceIdRatioBasedSampler`). At
-> `sampling_ratio < 1.0` the stage RED metrics undercount proportionally — they
-> reflect sampled traces, not the full transaction volume. Native StatsD/meter
-> metrics do not sample. Account for this when reading absolute stage rates.
+> **Sampling caveat**: xrpld head sampling is fixed at 1.0 (every trace is
+> recorded), so span-derived metrics are not undercounted at the node. If the
+> collector is configured with tail sampling, span-derived metrics reflect only
+> the retained traces, whereas native StatsD/meter metrics do not sample.
+> Account for any collector-side tail sampling when reading absolute stage rates.
 
 **Where to query**: Prometheus → `traces_span_metrics_calls_total{span_name="rpc.command.server_info"}`
 
@@ -727,7 +727,7 @@ The telemetry system is designed with privacy in mind:
 - **Transaction hashes** are included (public on-ledger data) but not transaction contents
 - **Peer IDs** are internal identifiers, not IP addresses
 - **All telemetry is opt-in** — disabled by default at build time (`-Dtelemetry=OFF`)
-- **Sampling** reduces data volume — `sampling_ratio=0.01` recommended for production
+- **Sampling** — head sampling is fixed at 1.0 (sample everything); reduce data volume with collector-side tail sampling
 - **Data stays local** — the default stack sends data to `localhost` only
 
 ---
@@ -754,7 +754,6 @@ prefix=xrpld
 [telemetry]
 enabled=1
 endpoint=http://otel-collector:4318/v1/traces
-sampling_ratio=0.01
 trace_peer=0
 batch_size=1024
 max_queue_size=4096
diff --git a/docker/telemetry/TESTING.md b/docker/telemetry/TESTING.md
index d733d09d83..6fe7bdc732 100644
--- a/docker/telemetry/TESTING.md
+++ b/docker/telemetry/TESTING.md
@@ -285,7 +285,6 @@ online_delete=256
 [telemetry]
 enabled=1
 endpoint=http://localhost:4318/v1/traces
-sampling_ratio=1.0
 batch_size=512
 batch_delay_ms=2000
 max_queue_size=2048
diff --git a/docker/telemetry/integration-test.sh b/docker/telemetry/integration-test.sh
index 634addcf91..7a36d43b4f 100755
--- a/docker/telemetry/integration-test.sh
+++ b/docker/telemetry/integration-test.sh
@@ -312,7 +312,6 @@ enabled=1
 service_instance_id=Node-${i}
 endpoint=http://localhost:4318/v1/traces
 exporter=otlp_http
-sampling_ratio=1.0
 batch_size=512
 batch_delay_ms=2000
 max_queue_size=2048
diff --git a/docker/telemetry/xrpld-telemetry.cfg b/docker/telemetry/xrpld-telemetry.cfg
index 8c5e8e777b..d233ad751a 100644
--- a/docker/telemetry/xrpld-telemetry.cfg
+++ b/docker/telemetry/xrpld-telemetry.cfg
@@ -49,7 +49,6 @@ enabled=1
 service_instance_id=xrpld-standalone
 endpoint=http://localhost:4318/v1/traces
 exporter=otlp_http
-sampling_ratio=1.0
 batch_size=512
 batch_delay_ms=5000
 max_queue_size=2048