ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2026-07-30 10:30:22 +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

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