From 5dc7eb25b8aa2153e595e12f3614e7eb22abef55 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Mon, 20 Jul 2026 17:41:37 +0100 Subject: [PATCH] chore(telemetry): normalize remaining triple-slash Doxygen comments 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) --- include/xrpl/telemetry/SpanNames.h | 18 +++-- .../xrpl/telemetry/TraceContextPropagator.h | 49 +++++++------ .../xrpl/telemetry/TraceContextValidation.h | 26 ++++--- include/xrpl/tx/detail/TxApplySpanNames.h | 61 +++++++++++----- .../libxrpl/telemetry/TxApplySpanNames.cpp | 3 +- src/xrpld/app/misc/detail/TxQSpanNames.h | 51 +++++++++---- src/xrpld/telemetry/PropagationHelpers.h | 16 ++-- src/xrpld/telemetry/TxSpanNames.h | 73 ++++++++++++++----- src/xrpld/telemetry/TxTracing.h | 9 ++- 9 files changed, 203 insertions(+), 103 deletions(-) diff --git a/include/xrpl/telemetry/SpanNames.h b/include/xrpl/telemetry/SpanNames.h index ff28c3c196..41fe1720cf 100644 --- a/include/xrpl/telemetry/SpanNames.h +++ b/include/xrpl/telemetry/SpanNames.h @@ -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 — _ underscore form). -/// -/// Per the naming convention header note: shared cross-span attribute -/// keys use the underscore form, reserving the dotted xrpl.. -/// 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 — _ underscore form). + * + * Per the naming convention header note: shared cross-span attribute + * keys use the underscore form, reserving the dotted xrpl.. + * 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"); diff --git a/include/xrpl/telemetry/TraceContextPropagator.h b/include/xrpl/telemetry/TraceContextPropagator.h index 4eabd9cf2b..6a698c1933 100644 --- a/include/xrpl/telemetry/TraceContextPropagator.h +++ b/include/xrpl/telemetry/TraceContextPropagator.h @@ -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(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) { diff --git a/include/xrpl/telemetry/TraceContextValidation.h b/include/xrpl/telemetry/TraceContextValidation.h index 1c1554acf0..e69b2d17ca 100644 --- a/include/xrpl/telemetry/TraceContextValidation.h +++ b/include/xrpl/telemetry/TraceContextValidation.h @@ -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) diff --git a/include/xrpl/tx/detail/TxApplySpanNames.h b/include/xrpl/tx/detail/TxApplySpanNames.h index 2084458cf5..1228bd57ef 100644 --- a/include/xrpl/tx/detail/TxApplySpanNames.h +++ b/include/xrpl/tx/detail/TxApplySpanNames.h @@ -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.) =========================================== -/// "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 diff --git a/src/tests/libxrpl/telemetry/TxApplySpanNames.cpp b/src/tests/libxrpl/telemetry/TxApplySpanNames.cpp index 170fef3ae4..52c4bdab0e 100644 --- a/src/tests/libxrpl/telemetry/TxApplySpanNames.cpp +++ b/src/tests/libxrpl/telemetry/TxApplySpanNames.cpp @@ -4,7 +4,8 @@ #include -/** 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 diff --git a/src/xrpld/app/misc/detail/TxQSpanNames.h b/src/xrpld/app/misc/detail/TxQSpanNames.h index 24c2cfa458..e062e361d1 100644 --- a/src/xrpld/app/misc/detail/TxQSpanNames.h +++ b/src/xrpld/app/misc/detail/TxQSpanNames.h @@ -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 diff --git a/src/xrpld/telemetry/PropagationHelpers.h b/src/xrpld/telemetry/PropagationHelpers.h index 8cb9954624..88ad887a34 100644 --- a/src/xrpld/telemetry/PropagationHelpers.h +++ b/src/xrpld/telemetry/PropagationHelpers.h @@ -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 @@ -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) diff --git a/src/xrpld/telemetry/TxSpanNames.h b/src/xrpld/telemetry/TxSpanNames.h index 443171c5c9..e8d75f17af 100644 --- a/src/xrpld/telemetry/TxSpanNames.h +++ b/src/xrpld/telemetry/TxSpanNames.h @@ -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 diff --git a/src/xrpld/telemetry/TxTracing.h b/src/xrpld/telemetry/TxTracing.h index a6633034d3..02900fa9b4 100644 --- a/src/xrpld/telemetry/TxTracing.h +++ b/src/xrpld/telemetry/TxTracing.h @@ -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