ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2026-07-23 23:20:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(telemetry): normalize remaining triple-slash Doxygen comments + refresh levelization

Browse Source 
Convert leading /// blocks to house-style /** */ across the telemetry
files carried on this branch (using the updated fix_doxy.py). Also
regenerate levelization results. Comment-only: code is byte-identical.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Pratik Mankawde
2026-07-20 17:42:04 +01:00
parent 84729d8eaa
commit 367fa87da8
12 changed files with 300 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/scripts/levelization/results/ordering.txt vendored
View File

@@ -112,6 +112,7 @@ test.csf > xrpl.basics
test.csf > xrpld.consensus
test.csf > xrpl.json
test.csf > xrpl.ledger
test.csf > xrpl.telemetry
test.json > test.jtx
test.json > xrpl.json
test.jtx > test.unit_test

34
include/xrpl/telemetry/SpanNames.h
View File

@@ -117,27 +117,33 @@ namespace attr {
inline constexpr auto networkId = join(join(seg::xrpl, seg::network), makeStr("id"));
inline constexpr auto networkType = join(join(seg::xrpl, seg::network), makeStr("type"));
/// Canonical shared attrs (rule 5 — <domain>_<field> underscore form).
///
/// Per the naming convention header note: shared cross-span attribute
/// keys use the underscore form, reserving the dotted xrpl.<domain>.<field>
/// form for resource attributes set on the OTel resource at startup.
/// Defined once here, aliased by domain-specific headers. These are
/// literal underscore-joined names, not dot-joined via `join()`, since
/// `join()` always inserts `.` between its arguments.
/**
* Canonical shared attrs (rule 5 — <domain>_<field> underscore form).
*
* Per the naming convention header note: shared cross-span attribute
* keys use the underscore form, reserving the dotted xrpl.<domain>.<field>
* form for resource attributes set on the OTel resource at startup.
* Defined once here, aliased by domain-specific headers. These are
* literal underscore-joined names, not dot-joined via `join()`, since
* `join()` always inserts `.` between its arguments.
*/
inline constexpr auto txHash = makeStr("tx_hash");
inline constexpr auto peerId = makeStr("peer_id");
inline constexpr auto ledgerSeq = makeStr("ledger_seq");
/// Shared close-time attrs — bare names, reused by consensus and ledger.
/**
* Shared close-time attrs — bare names, reused by consensus and ledger.
*/
inline constexpr auto closeTime = makeStr("close_time");
inline constexpr auto closeTimeCorrect = makeStr("close_time_correct");
inline constexpr auto closeResolutionMs = makeStr("close_resolution_ms");
/// Shared validation attrs — reused by the consensus and peer validation
/// spans. Same concept, same key on every span; the span name tells them
/// apart, so neither is emitter-prefixed. `ledgerHash` is a ledger-object
/// property (bare, like ledgerSeq); `fullValidation` is the is-full-validation
/// flag. Never the dotted xrpl. form (reserved for resource attrs).
/**
* Shared validation attrs — reused by the consensus and peer validation
* spans. Same concept, same key on every span; the span name tells them
* apart, so neither is emitter-prefixed. `ledgerHash` is a ledger-object
* property (bare, like ledgerSeq); `fullValidation` is the is-full-validation
* flag. Never the dotted xrpl. form (reserved for resource attrs).
*/
inline constexpr auto ledgerHash = makeStr("ledger_hash");
inline constexpr auto fullValidation = makeStr("full_validation");
} // namespace attr

15
include/xrpl/telemetry/Telemetry.h
View File

@@ -259,11 +259,12 @@ public:
*/
bool traceLedger = true;
/** Strategy for cross-node consensus trace correlation.
"deterministic" — derive trace_id from ledger hash so all
validators in the same round share the same trace_id.
"attribute" — random trace_id, correlate via ledger_id attribute.
*/
/**
* Strategy for cross-node consensus trace correlation.
* "deterministic" — derive trace_id from ledger hash so all
* validators in the same round share the same trace_id.
* "attribute" — random trace_id, correlate via ledger_id attribute.
*/
std::string consensusTraceStrategy = "deterministic";
};
@@ -337,7 +338,9 @@ public:
[[nodiscard]] virtual bool
shouldTraceLedger() const = 0;
/** @return The configured consensus trace correlation strategy. */
/**
* @return The configured consensus trace correlation strategy.
*/
[[nodiscard]] virtual std::string const&
getConsensusTraceStrategy() const = 0;

51
include/xrpl/telemetry/TraceContextPropagator.h
View File

@@ -1,18 +1,19 @@
#pragma once
/** Utilities for trace context propagation across nodes.
Provides serialization/deserialization of OTel trace context to/from
Protocol Buffer TraceContext messages (P2P cross-node propagation).
Wired into the P2P message flow via PropagationHelpers.h for
TMTransaction, TMProposeSet, and TMValidation messages.
Only compiled when XRPL_ENABLE_TELEMETRY is defined.
@see PropagationHelpers.h (high-level inject helpers),
TxTracing.h (transaction receive-side extraction),
ConsensusReceiveTracing.h (proposal/validation receive-side).
*/
/**
* Utilities for trace context propagation across nodes.
*
* Provides serialization/deserialization of OTel trace context to/from
* Protocol Buffer TraceContext messages (P2P cross-node propagation).
* Wired into the P2P message flow via PropagationHelpers.h for
* TMTransaction, TMProposeSet, and TMValidation messages.
*
* Only compiled when XRPL_ENABLE_TELEMETRY is defined.
*
* @see PropagationHelpers.h (high-level inject helpers),
* TxTracing.h (transaction receive-side extraction),
* ConsensusReceiveTracing.h (proposal/validation receive-side).
*/
#ifdef XRPL_ENABLE_TELEMETRY
@@ -35,12 +36,13 @@
namespace xrpl::telemetry {
/** Extract OTel context from a protobuf TraceContext message.
@param proto The protobuf TraceContext received from a peer.
@return An OTel Context with the extracted parent span, or an empty
context if the protobuf fields are missing or invalid.
*/
/**
* Extract OTel context from a protobuf TraceContext message.
*
* @param proto The protobuf TraceContext received from a peer.
* @return An OTel Context with the extracted parent span, or an empty
* context if the protobuf fields are missing or invalid.
*/
inline opentelemetry::context::Context
extractFromProtobuf(protocol::TraceContext const& proto)
{
@@ -69,11 +71,12 @@ extractFromProtobuf(protocol::TraceContext const& proto)
opentelemetry::nostd::shared_ptr<trace::Span>(new trace::DefaultSpan(spanCtx)));
}
/** Inject the current span's trace context into a protobuf TraceContext.
@param ctx The OTel context containing the span to propagate.
@param proto The protobuf TraceContext to populate.
*/
/**
* Inject the current span's trace context into a protobuf TraceContext.
*
* @param ctx The OTel context containing the span to propagate.
* @param proto The protobuf TraceContext to populate.
*/
inline void
injectToProtobuf(opentelemetry::context::Context const& ctx, protocol::TraceContext& proto)
{

26
include/xrpl/telemetry/TraceContextValidation.h
View File

@@ -1,6 +1,7 @@
#pragma once
/** Validation predicates for peer-supplied trace context.
/**
* Validation predicates for peer-supplied trace context.
*
* A protobuf TraceContext arrives inside untrusted peer messages
* (TMTransaction, TMProposeSet, TMValidation). Before a receiving node
@@ -28,7 +29,7 @@
* no OpenTelemetry headers, so receive sites that use SpanGuard keep
* SpanGuard's encapsulation of OTel types.
*
* @note Thread-safe: all functions are pure and operate only on their
* @note Thread-safe: all functions are pure and operate only on their
* arguments. No shared state.
*
* Usage:
@@ -50,10 +51,11 @@
namespace xrpl::telemetry {
/** True if the bytes are a valid OTel trace_id: 16 bytes, not all-zero.
/**
* True if the bytes are a valid OTel trace_id: 16 bytes, not all-zero.
*
* @param traceId The raw trace_id bytes from a protobuf TraceContext.
* @return true if usable as a trace identifier, false otherwise.
* @param traceId The raw trace_id bytes from a protobuf TraceContext.
* @return true if usable as a trace identifier, false otherwise.
*/
inline bool
isValidTraceId(std::string const& traceId)
@@ -61,10 +63,11 @@ isValidTraceId(std::string const& traceId)
return traceId.size() == 16 && std::ranges::any_of(traceId, [](char c) { return c != 0; });
}
/** True if the bytes are a valid OTel span_id: 8 bytes, not all-zero.
/**
* True if the bytes are a valid OTel span_id: 8 bytes, not all-zero.
*
* @param spanId The raw span_id bytes from a protobuf TraceContext.
* @return true if usable as a span identifier, false otherwise.
* @param spanId The raw span_id bytes from a protobuf TraceContext.
* @return true if usable as a span identifier, false otherwise.
*/
inline bool
isValidSpanId(std::string const& spanId)
@@ -72,15 +75,16 @@ isValidSpanId(std::string const& spanId)
return spanId.size() == 8 && std::ranges::any_of(spanId, [](char c) { return c != 0; });
}
/** True if the context carries a usable parent: a valid trace_id and a
/**
* True if the context carries a usable parent: a valid trace_id and a
* valid span_id together.
*
* Use this where both ids are taken from the peer (consensus receive,
* generic extraction). The transaction path derives its trace_id
* locally from the txID, so it checks isValidSpanId() alone instead.
*
* @param tc The protobuf TraceContext received from a peer.
* @return true if both ids are present and valid, false otherwise.
* @param tc The protobuf TraceContext received from a peer.
* @return true if both ids are present and valid, false otherwise.
*/
inline bool
isValidTraceContext(protocol::TraceContext const& tc)

61
include/xrpl/tx/detail/TxApplySpanNames.h
View File

@@ -1,6 +1,7 @@
#pragma once
/** Compile-time span name constants for the transaction apply pipeline.
/**
* Compile-time span name constants for the transaction apply pipeline.
*
* Defines the span names and attribute keys used by the three apply-pipeline
* stages — preflight, preclaim, and transactor (apply) — that run inside the
@@ -67,47 +68,73 @@ namespace xrpl::telemetry::tx_apply_span {
// ===== Span operation suffixes =============================================
namespace op {
/// "preflight" — stateless transaction checks (suffix form).
/**
* "preflight" — stateless transaction checks (suffix form).
*/
inline constexpr auto preflight = makeStr("preflight");
/// "preclaim" — ledger-aware checks before fee claim (suffix form).
/**
* "preclaim" — ledger-aware checks before fee claim (suffix form).
*/
inline constexpr auto preclaim = makeStr("preclaim");
/// "transactor" — the apply stage (suffix form, used with span()).
/**
* "transactor" — the apply stage (suffix form, used with span()).
*/
inline constexpr auto transactor = makeStr("transactor");
} // namespace op
// ===== Full span names (tx.<op>) ===========================================
/// "tx.preflight" — full name for hashSpan() at the preflight stage.
/**
* "tx.preflight" — full name for hashSpan() at the preflight stage.
*/
inline constexpr auto preflight = join(seg::tx, op::preflight);
/// "tx.preclaim" — full name for hashSpan() at the preclaim stage.
/**
* "tx.preclaim" — full name for hashSpan() at the preclaim stage.
*/
inline constexpr auto preclaim = join(seg::tx, op::preclaim);
/// "tx.transactor" — full name for hashSpan() at the apply stage. Shares the
/// txID-derived trace_id so it co-traces with tx.preflight and tx.preclaim.
/**
* "tx.transactor" — full name for hashSpan() at the apply stage. Shares the
* txID-derived trace_id so it co-traces with tx.preflight and tx.preclaim.
*/
inline constexpr auto transactor = join(seg::tx, op::transactor);
// ===== Attribute keys ======================================================
namespace attr {
/// "stage" — which apply-pipeline stage this span represents. Drives the
/// collector spanmetrics `stage` dimension for per-stage RED metrics.
/**
* "stage" — which apply-pipeline stage this span represents. Drives the
* collector spanmetrics `stage` dimension for per-stage RED metrics.
*/
inline constexpr auto stage = makeStr("stage");
/// "tx_type" — transaction type name (e.g., "Payment", "OfferCreate").
/// Matches tx_span::attr::txType so both share the spanmetrics dimension.
/**
* "tx_type" — transaction type name (e.g., "Payment", "OfferCreate").
* Matches tx_span::attr::txType so both share the spanmetrics dimension.
*/
inline constexpr auto txType = makeStr("tx_type");
/// "ter_result" — engine result code after the stage (e.g., "tesSUCCESS").
/**
* "ter_result" — engine result code after the stage (e.g., "tesSUCCESS").
*/
inline constexpr auto terResult = makeStr("ter_result");
/// "applied" — whether the transaction was applied to the ledger (apply only).
/**
* "applied" — whether the transaction was applied to the ledger (apply only).
*/
inline constexpr auto applied = makeStr("applied");
} // namespace attr
// ===== Attribute values (stage names) ======================================
namespace val {
/// "preflight" — value of the stage attribute on tx.preflight.
/**
* "preflight" — value of the stage attribute on tx.preflight.
*/
inline constexpr auto preflight = makeStr("preflight");
/// "preclaim" — value of the stage attribute on tx.preclaim.
/**
* "preclaim" — value of the stage attribute on tx.preclaim.
*/
inline constexpr auto preclaim = makeStr("preclaim");
/// "apply" — value of the stage attribute on tx.transactor.
/**
* "apply" — value of the stage attribute on tx.transactor.
*/
inline constexpr auto apply = makeStr("apply");
} // namespace val

3
src/tests/libxrpl/telemetry/TxApplySpanNames.cpp
View File

@@ -4,7 +4,8 @@
#include <string_view>
/** Contract tests for the transaction apply-pipeline span constants.
/**
* Contract tests for the transaction apply-pipeline span constants.
*
* The span names and attribute keys in TxApplySpanNames.h are a cross-component
* contract: the collector spanmetrics connector aggregates on these exact

51
src/xrpld/app/misc/detail/TxQSpanNames.h
View File

@@ -1,6 +1,7 @@
#pragma once
/** Compile-time span name constants for Transaction Queue tracing.
/**
* Compile-time span name constants for Transaction Queue tracing.
*
* Covers the TxQ lifecycle: enqueue decisions, direct apply, batch
* clear, ledger-close accept loop, per-tx apply, and cleanup.
@@ -55,7 +56,9 @@ namespace xrpl::telemetry::txq_span {
// ===== Span prefixes =======================================================
namespace prefix {
/// "txq" — root prefix for transaction queue spans.
/**
* "txq" — root prefix for transaction queue spans.
*/
inline constexpr auto txq = makeStr("txq");
} // namespace prefix
@@ -73,29 +76,51 @@ inline constexpr auto cleanup = makeStr("cleanup");
// ===== Attribute keys ======================================================
namespace attr {
/// Canonical shared constants (defined in SpanNames.h).
/**
* Canonical shared constants (defined in SpanNames.h).
*/
using ::xrpl::telemetry::attr::ledgerSeq;
using ::xrpl::telemetry::attr::txHash;
/// "txq_status" — domain-qualified (collides with tx_status, rpc_status).
/**
* "txq_status" — domain-qualified (collides with tx_status, rpc_status).
*/
inline constexpr auto txqStatus = makeStr("txq_status");
/// "fee_level_paid" — fee level paid by queued tx.
/**
* "fee_level_paid" — fee level paid by queued tx.
*/
inline constexpr auto feeLevelPaid = makeStr("fee_level_paid");
/// "required_fee_level" — minimum fee level for inclusion.
/**
* "required_fee_level" — minimum fee level for inclusion.
*/
inline constexpr auto requiredFeeLevel = makeStr("required_fee_level");
/// "queue_size" — current TxQ depth.
/**
* "queue_size" — current TxQ depth.
*/
inline constexpr auto queueSize = makeStr("queue_size");
/// "ledger_changed" — whether ledger changed since last attempt.
/**
* "ledger_changed" — whether ledger changed since last attempt.
*/
inline constexpr auto ledgerChanged = makeStr("ledger_changed");
/// "expired_count" — number of expired entries cleared.
/**
* "expired_count" — number of expired entries cleared.
*/
inline constexpr auto expiredCount = makeStr("expired_count");
/// "ter_code" — transaction engine result code.
/**
* "ter_code" — transaction engine result code.
*/
inline constexpr auto terCode = makeStr("ter_code");
/// "retries_remaining" — retries left before discard.
/**
* "retries_remaining" — retries left before discard.
*/
inline constexpr auto retriesRemaining = makeStr("retries_remaining");
/// "num_cleared" — entries cleared in batch.
/**
* "num_cleared" — entries cleared in batch.
*/
inline constexpr auto numCleared = makeStr("num_cleared");
/// "tx_type" — transaction type name (e.g., "Payment", "OfferCreate").
/**
* "tx_type" — transaction type name (e.g., "Payment", "OfferCreate").
*/
inline constexpr auto txType = makeStr("tx_type");
} // namespace attr

109
src/xrpld/consensus/ConsensusSpanNames.h
View File

@@ -1,6 +1,7 @@
#pragma once
/** Compile-time span name constants for consensus tracing.
/**
* Compile-time span name constants for consensus tracing.
*
* Used by RCLConsensus (app), Consensus.h (template), and PeerImp
* (overlay) for consensus lifecycle spans.
@@ -125,9 +126,11 @@ inline constexpr auto phaseOpen = join(seg::consensus, op::phaseOpen);
// ===== Attribute keys ========================================================
namespace attr {
/// Canonical shared constants (defined in SpanNames.h). `ledgerHash` and
/// `fullValidation` are shared with the peer.validation.receive span — same
/// concept, same key, distinguished by span name (not an emitter prefix).
/**
* Canonical shared constants (defined in SpanNames.h). `ledgerHash` and
* `fullValidation` are shared with the peer.validation.receive span — same
* concept, same key, distinguished by span name (not an emitter prefix).
*/
using ::xrpl::telemetry::attr::closeResolutionMs;
using ::xrpl::telemetry::attr::closeTime;
using ::xrpl::telemetry::attr::closeTimeCorrect;
@@ -135,43 +138,67 @@ using ::xrpl::telemetry::attr::fullValidation;
using ::xrpl::telemetry::attr::ledgerHash;
using ::xrpl::telemetry::attr::ledgerSeq;
/// Domain-qualified attrs (rule 5 — bare name ambiguous across domains).
/// Use `<domain>_<field>` underscore form for TraceQL ergonomics.
/**
* Domain-qualified attrs (rule 5 — bare name ambiguous across domains).
* Use `<domain>_<field>` underscore form for TraceQL ergonomics.
*/
inline constexpr auto ledgerId = makeStr("consensus_ledger_id");
inline constexpr auto mode = makeStr("consensus_mode");
inline constexpr auto round = makeStr("consensus_round");
inline constexpr auto roundId = makeStr("consensus_round_id");
/// Current phase name attached to consensus.round; updated on each
/// phase transition event (open/establish/accepted).
/**
* Current phase name attached to consensus.round; updated on each
* phase transition event (open/establish/accepted).
*/
inline constexpr auto consensusPhase = makeStr("consensus_phase");
/// Boolean flag set on consensus.check when checkConsensus reports stalled.
/**
* Boolean flag set on consensus.check when checkConsensus reports stalled.
*/
inline constexpr auto consensusStalled = makeStr("consensus_stalled");
/// Domain-owned bare attrs.
/**
* Domain-owned bare attrs.
*/
inline constexpr auto proposers = makeStr("proposers");
inline constexpr auto roundTimeMs = makeStr("round_time_ms");
inline constexpr auto proposing = makeStr("proposing");
/// Round continuity / context attrs (set on consensus.round at round start).
/**
* Round continuity / context attrs (set on consensus.round at round start).
*/
inline constexpr auto previousProposers = makeStr("previous_proposers");
inline constexpr auto previousRoundTimeMs = makeStr("previous_round_time_ms");
inline constexpr auto previousLedgerSeq = makeStr("previous_ledger_seq");
inline constexpr auto closeTimeResolutionMs = makeStr("close_time_resolution_ms");
/// Open-phase end metadata (set on consensus.phase.open before reset).
/**
* Open-phase end metadata (set on consensus.phase.open before reset).
*/
inline constexpr auto openDurationMs = makeStr("open_duration_ms");
inline constexpr auto peerPositionsAtClose = makeStr("peer_positions_at_close");
/// Ledger-close inputs.
/**
* Ledger-close inputs.
*/
inline constexpr auto txCountOpen = makeStr("tx_count_open");
/// Establish/check additional state.
/**
* Establish/check additional state.
*/
inline constexpr auto proposersFinished = makeStr("proposers_finished");
/// Accept/apply enrichment.
/**
* Accept/apply enrichment.
*/
inline constexpr auto disputesResolvedCount = makeStr("disputes_resolved_count");
/// Validation send/receive enrichment. (`full_validation` is shared — see the
/// `using` re-export above.)
/**
* Validation send/receive enrichment. (`full_validation` is shared — see the
* `using` re-export above.)
*/
inline constexpr auto validationSignTime = makeStr("validation_sign_time");
/// Receive-side hash prefixes for cross-peer correlation.
/**
* Receive-side hash prefixes for cross-peer correlation.
*/
inline constexpr auto prevLedgerPrefix = makeStr("prev_ledger_prefix");
inline constexpr auto positionHashPrefix = makeStr("position_hash_prefix");
/// "consensus_state" — domain-qualified (collides with other domains' state).
/**
* "consensus_state" — domain-qualified (collides with other domains' state).
*/
inline constexpr auto consensusState = makeStr("consensus_state");
inline constexpr auto parentCloseTime = makeStr("parent_close_time");
inline constexpr auto closeTimeSelf = makeStr("close_time_self");
@@ -185,27 +212,35 @@ inline constexpr auto haveCloseTimeConsensus = makeStr("have_close_time_consensu
inline constexpr auto agreeCount = makeStr("agree_count");
inline constexpr auto disagreeCount = makeStr("disagree_count");
inline constexpr auto thresholdPercent = makeStr("threshold_percent");
/// "consensus_result" — domain-qualified (collides with generic result).
/**
* "consensus_result" — domain-qualified (collides with generic result).
*/
inline constexpr auto consensusResult = makeStr("consensus_result");
inline constexpr auto quorum = makeStr("quorum");
inline constexpr auto traceStrategy = makeStr("trace_strategy");
inline constexpr auto modeOld = makeStr("mode_old");
inline constexpr auto modeNew = makeStr("mode_new");
/// "is_bow_out" — whether this proposal is a bow-out (resigning from round).
/**
* "is_bow_out" — whether this proposal is a bow-out (resigning from round).
*/
inline constexpr auto isBowOut = makeStr("is_bow_out");
/// Transaction/dispute attrs used in consensus accept spans.
/**
* Transaction/dispute attrs used in consensus accept spans.
*/
inline constexpr auto txId = makeStr("tx_id");
inline constexpr auto disputeOurVote = makeStr("dispute_our_vote");
inline constexpr auto disputeYays = makeStr("dispute_yays");
inline constexpr auto disputeNays = makeStr("dispute_nays");
inline constexpr auto txCount = makeStr("tx_count");
inline constexpr auto disputesCount = makeStr("disputes_count");
/// Trust flag (is the message origin a trusted UNL validator). Qualified by
/// message type, shared with the peer.{proposal,validation}.receive spans:
/// consensus.proposal.receive uses `proposal_trusted`, consensus.validation.
/// receive uses `validation_trusted`. Same concept on both emitters → same key.
/**
* Trust flag (is the message origin a trusted UNL validator). Qualified by
* message type, shared with the peer.{proposal,validation}.receive spans:
* consensus.proposal.receive uses `proposal_trusted`, consensus.validation.
* receive uses `validation_trusted`. Same concept on both emitters → same key.
*/
inline constexpr auto proposalTrusted = makeStr("proposal_trusted");
inline constexpr auto validationTrusted = makeStr("validation_trusted");
} // namespace attr
@@ -213,21 +248,29 @@ inline constexpr auto validationTrusted = makeStr("validation_trusted");
// ===== Event names ===========================================================
namespace event {
/// "dispute.resolve"
/**
* "dispute.resolve"
*/
inline constexpr auto disputeResolve = join(makeStr("dispute"), makeStr("resolve"));
/// "tx.included"
/**
* "tx.included"
*/
inline constexpr auto txIncluded = join(makeStr("tx"), makeStr("included"));
/// Phase transition events — fired on consensus.round at each transition
/// so the round-level span carries a complete timeline of phase changes,
/// including the handleWrongLedger recovery edge that re-enters Open.
/**
* Phase transition events — fired on consensus.round at each transition
* so the round-level span carries a complete timeline of phase changes,
* including the handleWrongLedger recovery edge that re-enters Open.
*/
inline constexpr auto phaseOpen = join(makeStr("phase"), makeStr("open"));
inline constexpr auto phaseEstablish = join(makeStr("phase"), makeStr("establish"));
inline constexpr auto phaseAccepted = join(makeStr("phase"), makeStr("accepted"));
inline constexpr auto phaseRecovery = join(makeStr("phase"), makeStr("recovery"));
/// Outcome events — fired on consensus.round at the establish→accepted
/// transition so the path that drove acceptance is queryable.
/**
* Outcome events — fired on consensus.round at the establish→accepted
* transition so the path that drove acceptance is queryable.
*/
inline constexpr auto outcomeYes = join(makeStr("outcome"), makeStr("yes"));
inline constexpr auto outcomeMovedOn = join(makeStr("outcome"), makeStr("moved_on"));
inline constexpr auto outcomeExpired = join(makeStr("outcome"), makeStr("expired"));

16
src/xrpld/telemetry/PropagationHelpers.h
View File

@@ -1,6 +1,7 @@
#pragma once
/** Helpers for injecting trace context into protobuf messages.
/**
* Helpers for injecting trace context into protobuf messages.
*
* Bridges the gap between SpanGuard (which hides OTel types) and the
* protobuf TraceContext message used for cross-node propagation.
@@ -13,7 +14,7 @@
* | |
* injectSpanContext(span, proto)
*
* @note When XRPL_ENABLE_TELEMETRY is disabled, getTraceBytes() returns
* @note When XRPL_ENABLE_TELEMETRY is disabled, getTraceBytes() returns
* {.valid=false}, so injectSpanContext becomes a no-op with zero overhead.
*
* Usage:
@@ -25,8 +26,8 @@
* overlay.relay(txID, tx, toSkip);
* @endcode
*
* @see ConsensusReceiveTracing.h for receive-side extraction helpers.
* @see TraceContextPropagator.h for low-level OTel context serialization.
* @see ConsensusReceiveTracing.h for receive-side extraction helpers.
* @see TraceContextPropagator.h for low-level OTel context serialization.
*/
#include <xrpl/proto/xrpl.pb.h>
@@ -34,7 +35,8 @@
namespace xrpl::telemetry {
/** Inject trace context from an active SpanGuard into a protobuf
/**
* Inject trace context from an active SpanGuard into a protobuf
* TraceContext message for cross-node propagation.
*
* Reads the span's trace_id, span_id, and trace_flags via
@@ -42,8 +44,8 @@ namespace xrpl::telemetry {
* Safe to call from any thread that holds a reference to the span.
* No-op if the span is null or inactive.
*
* @param span The active SpanGuard whose context to propagate.
* @param proto The protobuf TraceContext to populate.
* @param span The active SpanGuard whose context to propagate.
* @param proto The protobuf TraceContext to populate.
*/
inline void
injectSpanContext(SpanGuard const& span, protocol::TraceContext& proto)

73
src/xrpld/telemetry/TxSpanNames.h
View File

@@ -1,6 +1,7 @@
#pragma once
/** Compile-time span name constants for transaction tracing.
/**
* Compile-time span name constants for transaction tracing.
*
* Used by PeerImp (overlay) and NetworkOPs (app) for transaction
* lifecycle spans. Built on StaticStr/join() from SpanNames.h.
@@ -22,7 +23,9 @@ namespace xrpl::telemetry::tx_span {
// ===== Span prefixes =======================================================
namespace prefix {
/// "tx" — root prefix for transaction lifecycle spans.
/**
* "tx" — root prefix for transaction lifecycle spans.
*/
inline constexpr auto tx = seg::tx;
} // namespace prefix
@@ -41,29 +44,51 @@ inline constexpr auto process = join(prefix::tx, op::process);
// ===== Attribute keys ======================================================
namespace attr {
/// Canonical shared constants (defined in SpanNames.h).
/**
* Canonical shared constants (defined in SpanNames.h).
*/
using ::xrpl::telemetry::attr::peerId;
using ::xrpl::telemetry::attr::txHash;
/// "local" — whether tx originated locally.
/**
* "local" — whether tx originated locally.
*/
inline constexpr auto local = makeStr("local");
/// "path" — sync or async processing path.
/**
* "path" — sync or async processing path.
*/
inline constexpr auto path = makeStr("path");
/// "suppressed" — whether tx was suppressed as duplicate.
/**
* "suppressed" — whether tx was suppressed as duplicate.
*/
inline constexpr auto suppressed = makeStr("suppressed");
/// "tx_status" — domain-qualified (collides with rpc_status, txq_status).
/**
* "tx_status" — domain-qualified (collides with rpc_status, txq_status).
*/
inline constexpr auto txStatus = makeStr("tx_status");
/// "peer_version" — version of peer that sent the tx.
/**
* "peer_version" — version of peer that sent the tx.
*/
inline constexpr auto peerVersion = makeStr("peer_version");
/// "tx_type" — transaction type name (e.g., "Payment", "OfferCreate").
/**
* "tx_type" — transaction type name (e.g., "Payment", "OfferCreate").
*/
inline constexpr auto txType = makeStr("tx_type");
/// "fee" — transaction fee in drops.
/**
* "fee" — transaction fee in drops.
*/
inline constexpr auto fee = makeStr("fee");
/// "sequence" — transaction sequence number.
/**
* "sequence" — transaction sequence number.
*/
inline constexpr auto sequence = makeStr("sequence");
/// "ter_result" — engine result code after application.
/**
* "ter_result" — engine result code after application.
*/
inline constexpr auto terResult = makeStr("ter_result");
/// "applied" — whether the transaction was applied to the ledger.
/**
* "applied" — whether the transaction was applied to the ledger.
*/
inline constexpr auto applied = makeStr("applied");
} // namespace attr
@@ -73,16 +98,24 @@ namespace val {
inline constexpr auto sync = makeStr("sync");
inline constexpr auto async = makeStr("async");
inline constexpr auto knownBad = makeStr("known_bad");
/// Transaction was suppressed via HashRouter (duplicate, not flagged bad).
/**
* Transaction was suppressed via HashRouter (duplicate, not flagged bad).
*/
inline constexpr auto suppressed = makeStr("suppressed");
/// Transaction was rejected because it carried tfInnerBatchTxn, which
/// must never appear in network-relayed traffic.
/**
* Transaction was rejected because it carried tfInnerBatchTxn, which
* must never appear in network-relayed traffic.
*/
inline constexpr auto rejectedInnerBatch = makeStr("rejected_inner_batch");
/// Transaction was dropped because the validated ledger is too old to
/// confidently apply new transactions (server is out of sync).
/**
* Transaction was dropped because the validated ledger is too old to
* confidently apply new transactions (server is out of sync).
*/
inline constexpr auto droppedNoSync = makeStr("dropped_no_sync");
/// Transaction was dropped because the local job queue for jtTRANSACTION
/// is at MAX_TRANSACTIONS — backpressure on the receive side.
/**
* Transaction was dropped because the local job queue for jtTRANSACTION
* is at MAX_TRANSACTIONS — backpressure on the receive side.
*/
inline constexpr auto droppedQueueFull = makeStr("dropped_queue_full");
} // namespace val

9
src/xrpld/telemetry/TxTracing.h
View File

@@ -1,6 +1,7 @@
#pragma once
/** Helper functions for creating transaction trace spans.
/**
* Helper functions for creating transaction trace spans.
*
* Encapsulates the logic for creating SpanGuard instances with
* hash-derived trace IDs and optional protobuf parent extraction.
@@ -21,7 +22,8 @@
namespace xrpl::telemetry {
/** Create a "tx.receive" span for a transaction received from a peer.
/**
* Create a "tx.receive" span for a transaction received from a peer.
* trace_id is derived from txID[0:16]. If the incoming message carries
* a protobuf TraceContext with a valid span_id, it is used as the
* parent to preserve relay ordering.
@@ -53,7 +55,8 @@ txReceiveSpan(uint256 const& txID, [[maybe_unused]] protocol::TMTransaction cons
TraceCategory::Transactions, tx_span::receive, txID.data(), txID.kBytes);
}
/** Create a "tx.process" span for transaction processing in NetworkOPs.
/**
* Create a "tx.process" span for transaction processing in NetworkOPs.
* trace_id is derived from txID[0:16].
*/
inline SpanGuard