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

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

Browse Source 
Convert leading /// blocks in these 9 phase3-originating files to house
style /** */ (using the updated fix_doxy.py that now handles /// ->
block conversion). 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:41:37 +01:00
parent 6e99da094c
commit 5dc7eb25b8
9 changed files with 203 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -117,14 +117,16 @@ 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");

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

@@ -1,17 +1,18 @@
#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 messages.
Only compiled when XRPL_ENABLE_TELEMETRY is defined.
@see PropagationHelpers.h (high-level inject helpers),
TxTracing.h (transaction receive-side extraction).
*/
/**
* 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 messages.
*
* Only compiled when XRPL_ENABLE_TELEMETRY is defined.
*
* @see PropagationHelpers.h (high-level inject helpers),
* TxTracing.h (transaction receive-side extraction).
*/
#ifdef XRPL_ENABLE_TELEMETRY
@@ -34,12 +35,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)
{
@@ -68,11 +70,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

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 TxTracing.h for receive-side extraction helpers.
* @see TraceContextPropagator.h for low-level OTel context serialization.
* @see TxTracing.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