From 8da882dccb9a234f0055905d103d4f4d08ce694a Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Tue, 8 Sep 2026 14:42:05 +0100 Subject: [PATCH] docs(telemetry): state when retries_remaining is recorded retries_remaining is stamped on the txq.accept_tx span before the transaction is applied and before the retry counter is decremented, so a span with txq_status="retried" always shows a non-zero count and exhaustion shows up as txq_status="failed" with zero. The attribute comment said only "retries left before discard", which reads as a post-decrement value and led to a runbook query that could never match. Also rename the drifted consensus_trace_strategy value in the plan docs from "attribute" to "random", the spelling the parser accepts, and note that it is experimental and not used. --- OpenTelemetryPlan/02-design-decisions.md | 3 +- .../05-configuration-reference.md | 36 +++++++++---------- src/xrpld/app/misc/detail/TxQSpanNames.h | 5 ++- 3 files changed, 24 insertions(+), 20 deletions(-) diff --git a/OpenTelemetryPlan/02-design-decisions.md b/OpenTelemetryPlan/02-design-decisions.md index 70c29093ad..300c3f3f89 100644 --- a/OpenTelemetryPlan/02-design-decisions.md +++ b/OpenTelemetryPlan/02-design-decisions.md @@ -487,7 +487,8 @@ The first 16 bytes are used as trace_id. See [Phase 4a implementation status](./ and `createDeterministicContext()` in `RCLConsensus.cpp` for the implementation. Switchable via `consensus_trace_strategy` config: -`"deterministic"` (default) or `"attribute"` (random trace_id, correlation via attribute queries). +`"deterministic"` (default) or `"random"` (random trace_id, correlation via attribute queries). +`"random"` is experimental and not used: it would break cross-node trace correlation. #### Why Not Random IDs with Propagation Only? diff --git a/OpenTelemetryPlan/05-configuration-reference.md b/OpenTelemetryPlan/05-configuration-reference.md index 0edf8f20f6..6f643f0f80 100644 --- a/OpenTelemetryPlan/05-configuration-reference.md +++ b/OpenTelemetryPlan/05-configuration-reference.md @@ -15,24 +15,24 @@ The authoritative `[telemetry]` example lives in `cfg/xrpld-example.cfg`. Teleme ### 5.1.2 Configuration Options Summary -| Option | Type | Default | Description | -| -------------------------- | ------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `enabled` | bool | `false` | Enable/disable telemetry | -| `traces_endpoint` | string | `http://localhost:4318/v1/traces` | Full OTLP/HTTP URL for spans, used verbatim | -| `use_tls` | bool | `false` | Enable TLS for exporter connection | -| `tls_ca_cert` | string | `""` | Path to CA certificate file | -| `batch_size` | uint | `512` | Spans per export batch | -| `batch_delay_ms` | uint | `5000` | Max delay before sending batch (ms) | -| `max_queue_size` | uint | `2048` | Maximum queued spans | -| `trace_transactions` | 0 or 1 | `1` | Enable transaction tracing | -| `trace_consensus` | 0 or 1 | `1` | Enable consensus tracing | -| `trace_rpc` | 0 or 1 | `1` | Enable RPC tracing | -| `trace_peer` | 0 or 1 | `1` | Enable peer message tracing (high volume) | -| `trace_ledger` | 0 or 1 | `1` | Enable ledger tracing | -| `tx_trace_strategy` | string | `"deterministic"` | TX trace ID strategy: `"deterministic"` (trace_id = txHash[0:16]) or `"attribute"` (random) | -| `consensus_trace_strategy` | string | `"deterministic"` | Consensus trace ID strategy: `"deterministic"` (trace_id = prevLedgerHash[0:16]) or `"attribute"` (random) | -| `service_name` | string | `"xrpld"` | Service name (`service.name`) for traces and metrics | -| `service_instance_id` | string | `` | Instance identifier | +| Option | Type | Default | Description | +| -------------------------- | ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `enabled` | bool | `false` | Enable/disable telemetry | +| `traces_endpoint` | string | `http://localhost:4318/v1/traces` | Full OTLP/HTTP URL for spans, used verbatim | +| `use_tls` | bool | `false` | Enable TLS for exporter connection | +| `tls_ca_cert` | string | `""` | Path to CA certificate file | +| `batch_size` | uint | `512` | Spans per export batch | +| `batch_delay_ms` | uint | `5000` | Max delay before sending batch (ms) | +| `max_queue_size` | uint | `2048` | Maximum queued spans | +| `trace_transactions` | 0 or 1 | `1` | Enable transaction tracing | +| `trace_consensus` | 0 or 1 | `1` | Enable consensus tracing | +| `trace_rpc` | 0 or 1 | `1` | Enable RPC tracing | +| `trace_peer` | 0 or 1 | `1` | Enable peer message tracing (high volume) | +| `trace_ledger` | 0 or 1 | `1` | Enable ledger tracing | +| `tx_trace_strategy` | string | `"deterministic"` | TX trace ID strategy: `"deterministic"` (trace_id = txHash[0:16]) or `"attribute"` (random) | +| `consensus_trace_strategy` | string | `"deterministic"` | Consensus trace ID strategy: `"deterministic"` (trace_id = prevLedgerHash[0:16]) or `"random"` (experimental, not used) | +| `service_name` | string | `"xrpld"` | Service name (`service.name`) for traces and metrics | +| `service_instance_id` | string | `` | Instance identifier | **Planned (not yet implemented)**: the following options appear in the design documents but are not parsed by `TelemetryConfig.cpp` in Phase 1b and later diff --git a/src/xrpld/app/misc/detail/TxQSpanNames.h b/src/xrpld/app/misc/detail/TxQSpanNames.h index 6b64b76a57..703553e7b9 100644 --- a/src/xrpld/app/misc/detail/TxQSpanNames.h +++ b/src/xrpld/app/misc/detail/TxQSpanNames.h @@ -121,7 +121,10 @@ inline constexpr auto expiredCount = makeStr("expired_count"); */ inline constexpr auto terCode = makeStr("ter_code"); /** - * "retries_remaining" — retries left before discard. + * "retries_remaining" — retries left as this attempt started, recorded before + * the transaction is applied and before any decrement. A span with + * txq_status="retried" therefore always shows a non-zero count; exhaustion + * shows up as txq_status="failed" with zero. */ inline constexpr auto retriesRemaining = makeStr("retries_remaining"); /**