From a23d83f39350ff16df77fe10e5c1105c6cc3d2d9 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Fri, 5 Jun 2026 19:36:34 +0100
Subject: [PATCH] docs(telemetry): add ledger.acquire to 09-doc + fix
 peer-quality dashboard metric prefix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 9 introduces the ledger.acquire span (InboundLedger fetch) that phases 7-8
do not have, so the forward-merged 09-data-collection-reference inventory is
extended here:
- §1.1: add ledger.acquire to the Ledger span table.
- §1.2: add its attributes (acquire_reason, timeouts, peer_count, outcome) and
  note it also sets ledger_seq; bump the span count.

Also fix two stale StatsD metric references in the Peer Quality dashboard
(xrpld-peer-quality.json): rippled_Peer_Finder_Active_{Inbound,Outbound}_Peers
-> xrpld_Peer_Finder_* to match the xrpld_ metric prefix the rest of the stack uses.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../09-data-collection-reference.md            | 18 ++++++++++++------
 .../grafana/dashboards/xrpld-peer-quality.json |  4 ++--
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md
index c64d4ddea7..8d2768f033 100644
--- a/OpenTelemetryPlan/09-data-collection-reference.md
+++ b/OpenTelemetryPlan/09-data-collection-reference.md
@@ -78,7 +78,7 @@ There are two independent telemetry pipelines entering a single **OTel Collector
 
 ## 1. OpenTelemetry Spans
 
-### 1.1 Complete Span Inventory (~36 spans)
+### 1.1 Complete Span Inventory (~37 spans)
 
 > **See also**: [02-design-decisions.md §2.3](./02-design-decisions.md#23-span-naming-conventions) for naming conventions and the full span catalog with rationale. [04-code-samples.md §4.6](./04-code-samples.md#46-span-flow-visualization) for span flow diagrams.
 
@@ -193,11 +193,12 @@ round trace via context propagation rather than direct parenting. The
 
 Controlled by `trace_ledger=1` in `[telemetry]` config.
 
-| Span Name         | Parent | Source File      | Description                                    |
-| ----------------- | ------ | ---------------- | ---------------------------------------------- |
-| `ledger.build`    | —      | BuildLedger.cpp  | Build new ledger from accepted transaction set |
-| `ledger.validate` | —      | LedgerMaster.cpp | Ledger promoted to validated status            |
-| `ledger.store`    | —      | LedgerMaster.cpp | Ledger stored to database/history              |
+| Span Name         | Parent | Source File       | Description                                    |
+| ----------------- | ------ | ----------------- | ---------------------------------------------- |
+| `ledger.build`    | —      | BuildLedger.cpp   | Build new ledger from accepted transaction set |
+| `ledger.validate` | —      | LedgerMaster.cpp  | Ledger promoted to validated status            |
+| `ledger.store`    | —      | LedgerMaster.cpp  | Ledger stored to database/history              |
+| `ledger.acquire`  | —      | InboundLedger.cpp | Fetch a missing ledger from peers              |
 
 **Where to find**: Tempo → TraceQL: `{resource.service.name="xrpld" && name=~"ledger.*"}`
 
@@ -382,9 +383,14 @@ aggregation. Per the 2026-05-13 naming redesign, span-attribute keys use the
 | `tx_count`            | int64   | `tx.apply`                                        | Transactions applied to the ledger               |
 | `tx_failed`           | int64   | `tx.apply`                                        | Failed transactions in the apply set             |
 | `validations`         | int64   | `ledger.validate`                                 | Number of validations received for this ledger   |
+| `acquire_reason`      | string  | `ledger.acquire`                                  | Why the ledger fetch was triggered               |
+| `timeouts`            | int64   | `ledger.acquire`                                  | Number of fetch timeouts                         |
+| `peer_count`          | int64   | `ledger.acquire`                                  | Peers queried during the fetch                   |
+| `outcome`             | string  | `ledger.acquire`                                  | Fetch outcome                                    |
 
 The apply-step span `tx.apply` (child of `ledger.build`) carries `tx_count`/`tx_failed`;
 the parent `ledger.build` carries `ledger_seq` and the close-time attributes.
+`ledger.acquire` (InboundLedger) also sets `ledger_seq`.
 
 **Tempo query**: `{span.ledger_seq=12345}` to find all spans for a specific ledger.
 
diff --git a/docker/telemetry/grafana/dashboards/xrpld-peer-quality.json b/docker/telemetry/grafana/dashboards/xrpld-peer-quality.json
index 6ffc83bcd9..72995c7996 100644
--- a/docker/telemetry/grafana/dashboards/xrpld-peer-quality.json
+++ b/docker/telemetry/grafana/dashboards/xrpld-peer-quality.json
@@ -303,14 +303,14 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "rippled_Peer_Finder_Active_Inbound_Peers{exported_instance=~\"$node\"}",
+          "expr": "xrpld_Peer_Finder_Active_Inbound_Peers{exported_instance=~\"$node\"}",
           "legendFormat": "Inbound [{{exported_instance}}]"
         },
         {
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "rippled_Peer_Finder_Active_Outbound_Peers{exported_instance=~\"$node\"}",
+          "expr": "xrpld_Peer_Finder_Active_Outbound_Peers{exported_instance=~\"$node\"}",
           "legendFormat": "Outbound [{{exported_instance}}]"
         }
       ],