feat(telemetry): correlate tx spans to the ledger being worked on

Add shared current_ledger_seq / current_ledger_hash span attributes so a
transaction's work can be joined to the ledger trace that produced it, and
fix discrepancy D1 (txq.enqueue was a detached trace root).

- Define current_ledger_seq / current_ledger_hash once in SpanNames.h and
  re-export via `using` from TxQ/TxApply/Tx span-name headers. These name the
  ledger being worked on (open/tentative apply or in-flight consensus build),
  distinct from ledger_seq (the built/validated ledger on ledger.build /
  consensus.round). Named after the RPC field ledger_current_index.
- txq.enqueue: set current_ledger_seq/hash from the view, and parent the span
  to the caller's tx.process span via an explicit captured SpanContext (new
  trailing TxQ::apply param) instead of a detached root. The parent is
  explicit, not ambient-inherited, and the ScopedSpanGuard scope is RAII-bound
  to the synchronous apply, so it cannot leak onto a reused worker (D1 fix).
  On the open-ledger rebuild path no tx.process context exists, so it stays a
  root and the attribute provides the correlation.
- tx.preclaim / tx.transactor: set both attributes from their ledger view.
  tx.preflight is stateless (no view) and is the documented exception.
- tx.process / tx.receive: set current_ledger_seq from the current open ledger
  index at submit/receive time (no hash: not yet applied to a ledger).
- Contract test pins the two new attribute key strings.

Neither key is a spanmetrics dimension, so there is no metric-cardinality
impact. Dashboards/collector/docs land on the later phases per the chain split.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Pratik Mankawde
2026-07-24 16:03:42 +01:00
parent 07b8e90bd5
commit fb76c43307
11 changed files with 136 additions and 6 deletions

View File

@@ -130,6 +130,19 @@ inline constexpr auto networkType = join(join(seg::xrpl, seg::network), makeStr(
inline constexpr auto txHash = makeStr("tx_hash");
inline constexpr auto peerId = makeStr("peer_id");
inline constexpr auto ledgerSeq = makeStr("ledger_seq");
/**
* Shared "ledger being worked on" attrs — the open/tentative or in-flight
* consensus-build ledger a transaction is applied into, NOT an established or
* validated ledger (that is `ledgerSeq`, set on ledger.build / consensus.round).
* Named after the RPC field `ledger_current_index` and the `currentLedgerSeq`
* log usage. Reused by the tx lifecycle, apply-pipeline, and TxQ spans so a
* transaction's work can be correlated to the ledger it targeted.
* `currentLedgerHash` is the current view's parent-ledger hash, which equals the
* consensus.round deterministic trace-id seed on the consensus-build path.
*/
inline constexpr auto currentLedgerSeq = makeStr("current_ledger_seq");
inline constexpr auto currentLedgerHash = makeStr("current_ledger_hash");
} // namespace attr
// ===== Shared attribute values =============================================

View File

@@ -101,6 +101,15 @@ inline constexpr auto transactor = join(seg::tx, op::transactor);
// ===== Attribute keys ======================================================
namespace attr {
/**
* Shared "ledger being worked on" attrs (defined in SpanNames.h). Set on
* tx.preclaim and tx.transactor (both run against a view whose seq() is the
* ledger being applied into). tx.preflight is stateless (no view) and is the
* documented exception — it carries neither.
*/
using ::xrpl::telemetry::attr::currentLedgerHash;
using ::xrpl::telemetry::attr::currentLedgerSeq;
/**
* "stage" — which apply-pipeline stage this span represents. Drives the
* collector spanmetrics `stage` dimension for per-stage RED metrics.