feat(telemetry): add ledger-acquire and SHAMap fetch diagnostics (WP-A3)

Signals that separate a sync that is merely slow from one that will never
finish:

- sync_acquire{missing_state_nodes_max, missing_tx_nodes_max, in_flight,
  received_data_depth}: how many SHAMap nodes each in-flight acquire is
  still waiting for. getMissingNodes already computed this and the callers
  discarded it after a trace log. A count that stays flat means the
  acquire is wedged; a shrinking count means it is progressing. Recorded
  once per sweep, never inside the per-node walk, and reset when a tree
  completes so a finished acquire does not read as stuck forever.
- shamap_cache_hit_rate{treenode}: hit rate of the in-memory tree-node
  cache, which sits above the node store, so it is distinct from the
  existing NuDB ratio. A cold cache on a fresh node sends every traversal
  step to disk.
- sync_acquire_no_progress_total: timer ticks where an acquire made no
  progress, previously only logged.
- sync_addnode_total{good,duplicate,invalid}: whether arriving nodes are
  useful, duplicated or rejected, so wasted fetch work is visible.
- sync_acquire_source_total{local,network}: whether a ledger was served
  from the local store or had to be fetched.

Adds getBad()/getDuplicate() to SHAMapAddNode and an acquireProgress()
accessor on InboundLedgers so the xrpld gauge can read these without
libxrpl depending on telemetry.

ledger_seq is deliberately not a metric label: it is unbounded. Per-ledger
identity stays on the ledger.acquire span; the metrics expose bounded
aggregates instead.

The full-below cache hit rate is not exported: KeyCache updates different
counters than getHitRate() reads, so it would always report zero. That
libxrpl bug is documented rather than papered over.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Pratik Mankawde
2026-07-25 10:18:08 +01:00
parent 7c7509d01f
commit 3e2a1ea958
16 changed files with 1676 additions and 38 deletions

View File

@@ -24,6 +24,28 @@ public:
reset();
[[nodiscard]] int
getGood() const;
/**
* Nodes rejected as invalid in this tally.
*
* Complements getGood(): isInvalid() only answers "was there at least one",
* which cannot distinguish one bad node from a peer sending nothing but bad
* data. Exposed for the acquire telemetry counters, which need the count.
*
* @return Number of invalid nodes; 0 if none.
*/
[[nodiscard]] int
getBad() const;
/**
* Nodes already held, so re-receiving them was wasted work.
*
* A high duplicate share against a low good share means peers are re-sending
* data the node already has, which looks like healthy traffic but makes no
* acquire progress.
*
* @return Number of duplicate nodes; 0 if none.
*/
[[nodiscard]] int
getDuplicate() const;
[[nodiscard]] bool
isGood() const;
[[nodiscard]] bool
@@ -86,6 +108,18 @@ SHAMapAddNode::getGood() const
return good_;
}
inline int
SHAMapAddNode::getBad() const
{
return bad_;
}
inline int
SHAMapAddNode::getDuplicate() const
{
return duplicate_;
}
inline bool
SHAMapAddNode::isInvalid() const
{