mirror of
https://github.com/XRPLF/rippled.git
synced 2026-07-24 07:30:30 +00:00
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) <noreply@anthropic.com>
This commit is contained in:
Pratik Mankawde
@@ -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");
|
||||
|
||||
@@ -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)
|
||||
{
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user