From 4ebf780868a5b4dd425534816cfd32bcc618237b Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 14 Aug 2026 21:10:26 +0100 Subject: [PATCH 1/5] docs(telemetry): drop the plan-folder pointer from the trace_state note The trace_state comment pointed at a planning document that is not part of the shipped tree, so the reference would dangle for any reader of the repository. State the reserved-and-inert fact on its own. --- include/xrpl/proto/xrpl.proto | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/include/xrpl/proto/xrpl.proto b/include/xrpl/proto/xrpl.proto index b13c3d0b16..56fb3d0056 100644 --- a/include/xrpl/proto/xrpl.proto +++ b/include/xrpl/proto/xrpl.proto @@ -95,9 +95,8 @@ message TMPublicKey { // Older peers that do not understand field 1001 will simply ignore it // per protobuf wire-format rules, preserving backwards compatibility. // -// trace_state is reserved for future use (secure tracing pipeline, -// OpenTelemetryPlan/secure-OTel.md). It is currently neither populated -// on inject nor read on extract; consumers must not rely on it. +// trace_state is reserved for future use. It is currently neither +// populated on inject nor read on extract; consumers must not rely on it. message TraceContext { optional bytes trace_id = 1; // 16-byte trace identifier optional bytes span_id = 2; // 8-byte parent span identifier From 6ac68abfb56d629367bbb3b5ae26e54d4e03186c Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 14 Aug 2026 21:11:07 +0100 Subject: [PATCH 2/5] docs(telemetry): drop plan-document pointers from consensus tracing comments These comments pointed at a planning folder and at its rollout phase numbering, neither of which is part of the shipped tree, so the references would dangle for any reader of the repository. Each comment now states the fact it was pointing at. --- include/xrpl/telemetry/TraceContextPropagator.h | 11 ++++------- src/xrpld/app/consensus/RCLConsensus.cpp | 6 +++--- src/xrpld/app/consensus/RCLConsensus.h | 6 +++--- src/xrpld/telemetry/ConsensusReceiveTracing.h | 3 ++- 4 files changed, 12 insertions(+), 14 deletions(-) diff --git a/include/xrpl/telemetry/TraceContextPropagator.h b/include/xrpl/telemetry/TraceContextPropagator.h index e8d851e53e..9933e79292 100644 --- a/include/xrpl/telemetry/TraceContextPropagator.h +++ b/include/xrpl/telemetry/TraceContextPropagator.h @@ -101,13 +101,10 @@ injectToProtobuf(opentelemetry::context::Context const& ctx, protocol::TraceCont // Serialize flags proto.set_trace_flags(spanCtx.trace_flags().flags()); - // TODO(observability/secure-OTel): the protobuf TraceContext message - // also carries `trace_state` (field 4), which is currently neither - // populated here nor read by extractFromProtobuf above. The field is - // reserved for the secure tracing pipeline outlined in - // OpenTelemetryPlan/secure-OTel.md, where an authenticated token in - // tracestate will let receivers reject spoofed/poisoned trace context. - // Wire trace_state through inject/extract once the consumer lands. + // TODO: the protobuf TraceContext message also carries `trace_state` + // (field 4), which is currently neither populated here nor read by + // extractFromProtobuf above. The field is reserved for future use; + // wire it through inject/extract once a consumer lands. } } // namespace xrpl::telemetry diff --git a/src/xrpld/app/consensus/RCLConsensus.cpp b/src/xrpld/app/consensus/RCLConsensus.cpp index 35f5ed2131..5d8fb2ae5f 100644 --- a/src/xrpld/app/consensus/RCLConsensus.cpp +++ b/src/xrpld/app/consensus/RCLConsensus.cpp @@ -274,9 +274,9 @@ RCLConsensus::Adaptor::propose(RCLCxPeerPos::Proposal const& proposal) app_.getHashRouter().addSuppression(suppression); - // Inject the current thread's active span context (e.g. the - // consensus round span from Phase 4) so receiving peers can link - // their proposal.receive span as a child of this trace. + // Inject the current thread's active span context (e.g. the consensus + // round span) so receiving peers can link their proposal.receive span + // as a child of this trace. telemetry::SpanGuard::injectCurrentContextToProtobuf(*prop.mutable_trace_context()); app_.getOverlay().broadcast(prop); diff --git a/src/xrpld/app/consensus/RCLConsensus.h b/src/xrpld/app/consensus/RCLConsensus.h index 1ada9e7ee9..a7057e2f3a 100644 --- a/src/xrpld/app/consensus/RCLConsensus.h +++ b/src/xrpld/app/consensus/RCLConsensus.h @@ -127,9 +127,9 @@ class RCLConsensus * * Captured in makeAcceptSpan() and consumed by createValidationSpan() * on the jtACCEPT worker thread so the validation.send span can be - * follows-from linked to consensus.accept (matching the design doc - * and span hierarchy diagram). Reset on each startRoundTracing() - * to prevent a stale prior-round context from being linked. + * follows-from linked to consensus.accept. Reset on each + * startRoundTracing() to prevent a stale prior-round context from + * being linked. * * Thread safety: same model as roundSpanContext_. The write in * makeAcceptSpan happens on the main consensus thread under diff --git a/src/xrpld/telemetry/ConsensusReceiveTracing.h b/src/xrpld/telemetry/ConsensusReceiveTracing.h index 03974c5473..0a1a4458dc 100644 --- a/src/xrpld/telemetry/ConsensusReceiveTracing.h +++ b/src/xrpld/telemetry/ConsensusReceiveTracing.h @@ -34,7 +34,8 @@ * * @note Span names come from the canonical constants in * ConsensusSpanNames.h (consensus::span::proposalReceive / - * validationReceive) so they stay in sync with the rest of Phase 4. + * validationReceive) so they stay in sync with the rest of the + * consensus tracing surface. */ #include From 2bac88e67cc5da97345e5bf2d7a2b4171c3e73f1 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 14 Aug 2026 21:11:54 +0100 Subject: [PATCH 3/5] test(telemetry): label integration-test sections by what they verify The section labels carried rollout phase numbers that are defined only in a planning folder outside the shipped tree, so they meant nothing to a reader of the repository. The descriptive half of each label already identifies the section. --- docker/telemetry/integration-test.sh | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docker/telemetry/integration-test.sh b/docker/telemetry/integration-test.sh index f8263df63a..ba0974f2f4 100755 --- a/docker/telemetry/integration-test.sh +++ b/docker/telemetry/integration-test.sh @@ -409,7 +409,7 @@ for attempt in $(seq 1 60); do done # --------------------------------------------------------------------------- -# Step 7: Exercise RPC spans (Phase 2) +# Step 7: Exercise RPC spans # --------------------------------------------------------------------------- log "Exercising RPC spans..." @@ -424,7 +424,7 @@ log "RPC commands sent. Waiting 5s for batch export..." sleep 5 # --------------------------------------------------------------------------- -# Step 8: Submit transaction (Phase 3) +# Step 8: Submit transaction # --------------------------------------------------------------------------- log "Submitting Payment transaction..." @@ -477,7 +477,7 @@ else fi log "" -log "--- Phase 2: RPC Spans ---" +log "--- RPC Spans ---" check_span "rpc.request" check_span "rpc.process" check_span "rpc.command.server_info" @@ -485,26 +485,26 @@ check_span "rpc.command.server_state" check_span "rpc.command.ledger" log "" -log "--- Phase 3: Transaction Spans ---" +log "--- Transaction Spans ---" check_span "tx.process" check_span "tx.receive" check_span "tx.apply" log "" -log "--- Phase 4: Consensus Spans ---" +log "--- Consensus Spans ---" check_span "consensus.proposal.send" check_span "consensus.ledger_close" check_span "consensus.accept" check_span "consensus.validation.send" log "" -log "--- Phase 5: Ledger Spans ---" +log "--- Ledger Spans ---" check_span "ledger.build" check_span "ledger.validate" check_span "ledger.store" log "" -log "--- Phase 5: Peer Spans (trace_peer=1) ---" +log "--- Peer Spans (trace_peer=1) ---" check_span "peer.proposal.receive" check_span "peer.validation.receive" @@ -512,7 +512,7 @@ check_span "peer.validation.receive" # Step 10: Verify Prometheus spanmetrics # --------------------------------------------------------------------------- log "" -log "--- Phase 5: Spanmetrics ---" +log "--- Spanmetrics ---" log "Waiting 20s for Prometheus scrape cycle..." sleep 20 @@ -543,7 +543,7 @@ fi # Step 10b: Verify StatsD metrics in Prometheus # --------------------------------------------------------------------------- log "" -log "--- Phase 6: StatsD Metrics (beast::insight) ---" +log "--- StatsD Metrics (beast::insight) ---" log "Waiting 20s for StatsD aggregation + Prometheus scrape..." sleep 20 From 8670e31d6c0f12af68a24cbf729c17d750a537d4 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 14 Aug 2026 21:17:02 +0100 Subject: [PATCH 4/5] docs(telemetry): drop rollout phase numbers from the span catalog The catalog tagged every span with a rollout phase number defined only in a planning folder outside the shipped tree, so the column meant nothing to a reader of the repository. The span name and source file identify each entry. --- docker/telemetry/TESTING.md | 42 ++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docker/telemetry/TESTING.md b/docker/telemetry/TESTING.md index 2a6cfac9f2..723371a888 100644 --- a/docker/telemetry/TESTING.md +++ b/docker/telemetry/TESTING.md @@ -372,28 +372,28 @@ See the "Verification Queries" section below. ## Expected Span Catalog -All 16 production span names instrumented across Phases 2-5: +All 16 production span names: -| Span Name | Source File | Phase | Key Attributes | How to Trigger | -| --------------------------- | ----------------- | ----- | ---------------------------------------------------------------------------------------- | ------------------------- | -| `rpc.http_request` | ServerHandler.cpp | 2 | -- | Any HTTP RPC call | -| `rpc.ws_upgrade` | ServerHandler.cpp | 2 | -- | WebSocket upgrade | -| `rpc.ws_message` | ServerHandler.cpp | 2 | -- | WebSocket RPC message | -| `rpc.process` | ServerHandler.cpp | 2 | -- | RPC processing | -| `rpc.command.` | RPCHandler.cpp | 2 | `xrpl.rpc.command`, `xrpl.rpc.version`, `xrpl.rpc.role` | Any RPC command | -| `tx.process` | NetworkOPs.cpp | 3 | `xrpl.tx.hash`, `xrpl.tx.local`, `xrpl.tx.path` | Submit transaction | -| `tx.receive` | PeerImp.cpp | 3 | `xrpl.peer.id` | Peer relays transaction | -| `consensus.proposal.send` | RCLConsensus.cpp | 4 | `xrpl.consensus.round` | Consensus proposing phase | -| `consensus.ledger_close` | RCLConsensus.cpp | 4 | `xrpl.consensus.ledger.seq`, `xrpl.consensus.mode` | Ledger close event | -| `consensus.accept` | RCLConsensus.cpp | 4 | `xrpl.consensus.proposers`, `xrpl.consensus.round_time_ms` | Ledger accepted | -| `consensus.validation.send` | RCLConsensus.cpp | 4 | `xrpl.consensus.ledger.seq`, `xrpl.consensus.proposing` | Validation sent | -| `consensus.accept.apply` | RCLConsensus.cpp | 4 | `xrpl.consensus.close_time`, `close_time_correct`, `close_resolution_ms`, `state` | Ledger apply + close time | -| `tx.apply` | BuildLedger.cpp | 5 | `xrpl.ledger.tx_count`, `xrpl.ledger.tx_failed` | Ledger close (tx set) | -| `ledger.build` | BuildLedger.cpp | 5 | `xrpl.ledger.seq`, `xrpl.ledger.close_time`, `close_time_correct`, `close_resolution_ms` | Ledger build | -| `ledger.validate` | LedgerMaster.cpp | 5 | `xrpl.ledger.seq`, `xrpl.ledger.validations` | Ledger validated | -| `ledger.store` | LedgerMaster.cpp | 5 | `xrpl.ledger.seq` | Ledger stored | -| `peer.proposal.receive` | PeerImp.cpp | 5 | `xrpl.peer.id`, `xrpl.peer.proposal.trusted` | Peer sends proposal | -| `peer.validation.receive` | PeerImp.cpp | 5 | `xrpl.peer.id`, `xrpl.peer.validation.trusted` | Peer sends validation | +| Span Name | Source File | Key Attributes | How to Trigger | +| --------------------------- | ----------------- | ---------------------------------------------------------------------------------------- | ------------------------- | +| `rpc.http_request` | ServerHandler.cpp | -- | Any HTTP RPC call | +| `rpc.ws_upgrade` | ServerHandler.cpp | -- | WebSocket upgrade | +| `rpc.ws_message` | ServerHandler.cpp | -- | WebSocket RPC message | +| `rpc.process` | ServerHandler.cpp | -- | RPC processing | +| `rpc.command.` | RPCHandler.cpp | `xrpl.rpc.command`, `xrpl.rpc.version`, `xrpl.rpc.role` | Any RPC command | +| `tx.process` | NetworkOPs.cpp | `xrpl.tx.hash`, `xrpl.tx.local`, `xrpl.tx.path` | Submit transaction | +| `tx.receive` | PeerImp.cpp | `xrpl.peer.id` | Peer relays transaction | +| `consensus.proposal.send` | RCLConsensus.cpp | `xrpl.consensus.round` | Consensus proposing phase | +| `consensus.ledger_close` | RCLConsensus.cpp | `xrpl.consensus.ledger.seq`, `xrpl.consensus.mode` | Ledger close event | +| `consensus.accept` | RCLConsensus.cpp | `xrpl.consensus.proposers`, `xrpl.consensus.round_time_ms` | Ledger accepted | +| `consensus.validation.send` | RCLConsensus.cpp | `xrpl.consensus.ledger.seq`, `xrpl.consensus.proposing` | Validation sent | +| `consensus.accept.apply` | RCLConsensus.cpp | `xrpl.consensus.close_time`, `close_time_correct`, `close_resolution_ms`, `state` | Ledger apply + close time | +| `tx.apply` | BuildLedger.cpp | `xrpl.ledger.tx_count`, `xrpl.ledger.tx_failed` | Ledger close (tx set) | +| `ledger.build` | BuildLedger.cpp | `xrpl.ledger.seq`, `xrpl.ledger.close_time`, `close_time_correct`, `close_resolution_ms` | Ledger build | +| `ledger.validate` | LedgerMaster.cpp | `xrpl.ledger.seq`, `xrpl.ledger.validations` | Ledger validated | +| `ledger.store` | LedgerMaster.cpp | `xrpl.ledger.seq` | Ledger stored | +| `peer.proposal.receive` | PeerImp.cpp | `xrpl.peer.id`, `xrpl.peer.proposal.trusted` | Peer sends proposal | +| `peer.validation.receive` | PeerImp.cpp | `xrpl.peer.id`, `xrpl.peer.validation.trusted` | Peer sends validation | --- From 974835589ae22f6b6022d552fe105e24fcefbca8 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 14 Aug 2026 21:19:49 +0100 Subject: [PATCH 5/5] docs(telemetry): drop the plan task reference from a StatsD panel note Two panel descriptions pointed at a rollout phase and task number defined only in a planning folder outside the shipped tree. The note still names the file and the change it is waiting on, which is the part a reader can act on. --- .../telemetry/grafana/dashboards/statsd-rpc-pathfinding.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json b/docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json index a30a3aa82b..fb417c40a0 100644 --- a/docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json +++ b/docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json @@ -287,7 +287,7 @@ }, { "title": "Resource Warnings Rate", - "description": "Rate of resource warning events from the Resource Manager. Sourced from the warn meter (Logic.h) which increments when a consumer (peer or RPC client) exceeds the warning threshold for resource usage. A rising rate indicates aggressive clients that may need throttling. NOTE: This panel will show no data until the |m -> |c fix is applied in StatsDCollector.cpp (Phase 6 Task 6.1).", + "description": "Rate of resource warning events from the Resource Manager. Sourced from the warn meter (Logic.h) which increments when a consumer (peer or RPC client) exceeds the warning threshold for resource usage. A rising rate indicates aggressive clients that may need throttling. NOTE: This panel will show no data until the |m -> |c fix is applied in StatsDCollector.cpp.", "type": "stat", "gridPos": { "h": 8, @@ -335,7 +335,7 @@ }, { "title": "Resource Drops Rate", - "description": "Rate of resource drop events from the Resource Manager. Sourced from the drop meter (Logic.h) which increments when a consumer is disconnected or blocked due to excessive resource usage. Non-zero values mean the node is actively rejecting abusive connections. NOTE: This panel will show no data until the |m -> |c fix is applied in StatsDCollector.cpp (Phase 6 Task 6.1).", + "description": "Rate of resource drop events from the Resource Manager. Sourced from the drop meter (Logic.h) which increments when a consumer is disconnected or blocked due to excessive resource usage. Non-zero values mean the node is actively rejecting abusive connections. NOTE: This panel will show no data until the |m -> |c fix is applied in StatsDCollector.cpp.", "type": "stat", "gridPos": { "h": 8,