Fix doxygen style issue

* XRPLF/develop:
  ci: Rewrite clang-tidy workflow(s) in a reusable manner (7062)
  chore: Ignore identifier-naming update in git blame (7066)
  refactor: Enable clang-tidy `readability-identifier-naming` check (6571)

.codecov.yml

@@ -1,32 +1,10 @@
 codecov:
   require_ci_to_pass: true
-  # The C++ and Rust uploads land minutes apart; without this gate Codecov
-  # publishes a near-zero total from whichever one arrives first.
-  notify:
-    after_n_builds: 2
-    wait_for_ci: true
 
 comment:
   behavior: default
   layout: reach,diff,flags,tree,reach
-  show_carryforward_flags: true
-  after_n_builds: 2
-
-# C++ and Rust coverage upload from independent workflows under the `cpp` and
-# `rust` flags; carryforward keeps one language's total when only the other reran.
-flag_management:
-  default_rules:
-    carryforward: true
-  individual_flags:
-    - name: cpp
-      carryforward: true
-      paths:
-        - include/
-        - src/
-    - name: rust
-      carryforward: true
-      paths:
-        - crates/
+  show_carryforward_flags: false
 
 coverage:
   range: "70..85"
@@ -58,17 +36,3 @@ ignore:
   - "src/tests/"
   - "include/xrpl/beast/test/"
   - "include/xrpl/beast/unit_test/"
-  # Telemetry modules. Telemetry compiles in by default (conanfile.py,
-  # CMakeLists.txt), but the unit-test suite never starts an exporter, so these
-  # files record no coverage. This block belongs on the earliest branch that
-  # adds telemetry code — codecov config only flows child-ward, so an ignore
-  # added on a later branch can never cover the branches before it.
-  - "src/xrpld/telemetry/"
-  - "src/libxrpl/telemetry/"
-  - "include/xrpl/telemetry/"
-  - "src/libxrpl/beast/insight/OTelCollector.cpp"
-  - "include/xrpl/beast/insight/OTelCollector.h"
-  # Per-module span-name and span-label constant headers: compile-time
-  # constants only, colocated with their subsystem rather than under telemetry/.
-  - "**/*SpanNames.h"
-  - "**/*SpanLabels.h"

.cspell.config.yaml

@@ -7,7 +7,6 @@ ignorePaths:
   - cmake/**
   - LICENSE.md
   - .clang-tidy
-  - nix/check-tools/*.txt # generated, and full of Nix store hashes
 language: en
 allowCompoundWords: true # TODO (#6334)
 ignoreRandomStrings: true
@@ -64,14 +63,11 @@ words:
   - blindings
   - bookdir
   - Bougalis
-  - bthomee
   - Britto
   - Btrfs
   - Buildx
   - canonicality
-  - CGNAT
   - canonicalised
-  - cctools
   - changespq
   - checkme
   - choco
@@ -104,8 +100,6 @@ words:
   - dearmor
   - decryptor
   - dedented
-  - Dedup
-  - dedup
   - deleteme
   - demultiplexer
   - deserializaton
@@ -115,18 +109,14 @@ words:
   - disablerepo
   - distro
   - doxyfile
-  - dsymutil
-  - dthms
   - dxrpl
   - elgamal
   - enabled
   - enablerepo
   - endmacro
   - envrc
-  - EOCFG
   - exceptioned
   - EXPECT_STREQ
-  - exfiltration
   - Falco
   - fcontext
   - finalizers
@@ -135,8 +125,6 @@ words:
   - fsanitize
   - funclets
   - Gamal
-  - gantt
-  - Gantt
   - gcov
   - gcovr
   - ghead
@@ -144,17 +132,11 @@ words:
   - godexsoft
   - gpgcheck
   - gpgkey
-  - havetxset
-  - Hinnant
   - hotwallet
-  - hicpp
-  - htpasswd
   - hwaddress
   - hwrap
   - ifndef
   - inequation
-  - initialiser
-  - Injectivity
   - insuf
   - insuff
   - invasively
@@ -165,7 +147,6 @@ words:
   - itype
   - jemalloc
   - jlog
-  - jmeter
   - jtnofill
   - keylet
   - keylets
@@ -183,20 +164,18 @@ words:
   - libxrpl
   - llection
   - LOCALGOOD
-  - logql
   - logwstream
-  - Lombrozo
-  - lresolv
   - lseq
   - lsmf
   - ltype
   - mathbunnyru
   - mcmodel
   - MEMORYSTATUSEX
+  - MPTAMM
+  - MPTDEX
   - Merkle
   - misprediction
   - missingok
-  - MPTAMM
   - mptbalance
   - MPTDEX
   - mptflags
@@ -222,17 +201,14 @@ words:
   - nftokens
   - nftpage
   - nikb
-  - Nikolaos
   - nixfmt
   - nixos
   - nixpkgs
-  - NETOP
   - NOLINT
   - NOLINTNEXTLINE
   - nonxrp
   - noreplace
   - noripple
-  - nostd
   - nostdinc
   - notifempty
   - nudb
@@ -241,9 +217,6 @@ words:
   - Nyffenegger
   - onlatest
   - ostr
-  - otelc
-  - otelcol
-  - otool
   - oxalica
   - pargs
   - partitioner
@@ -253,12 +226,8 @@ words:
   - permdex
   - perminute
   - permissioned
-  - pgrep
-  - pkill
-  - pimpl
   - pointee
   - populator
-  - pratik
   - preauth
   - preauthorization
   - preauthorize
@@ -274,21 +243,14 @@ words:
   - qalloc
   - qbsprofile
   - queuable
-  - ransitioned
   - Raphson
   - rcflags
-  - reparent
   - replayer
-  - repodata
-  - repomd
-  - reqps
   - rerandomize
   - rerandomization
   - rerandomized
   - rerandomizes
   - rerere
-  - retargeted
-  - retargets
   - retriable
   - RIPD
   - ripdtop
@@ -305,11 +267,6 @@ words:
   - rustfmt
   - rustup
   - sahyadri
-  - sanitisation
-  - sanitise
-  - sanitised
-  - sanitiser
-  - sanitising
   - Satoshi
   - scons
   - Schnorr
@@ -329,8 +286,6 @@ words:
   - sles
   - soci
   - socidb
-  - Sonatype
-  - speciality
   - sponsee
   - sponsees
   - SRPMS
@@ -338,7 +293,6 @@ words:
   - statsd
   - STATSDCOLLECTOR
   - stissue
-  - stledgerentry
   - stnum
   - stobj
   - stobject
@@ -351,15 +305,12 @@ words:
   - summands
   - superpeer
   - superpeers
-  - Swatinem
-  - synthesise
   - takergets
   - takerpays
   - ters
   - TMEndpointv2
   - toolchain
   - tparam
-  - traceql
   - trixie
   - tx
   - txid
@@ -367,7 +318,6 @@ words:
   - txjson
   - txn
   - txns
-  - txqueue
   - txs
   - ubsan
   - UBSAN
@@ -382,8 +332,6 @@ words:
   - unfindable
   - unflatten
   - unfund
-  - ungated
-  - unheld
   - unimpair
   - unroutable
   - unscalable
@@ -394,20 +342,17 @@ words:
   - unsquelch
   - unsquelched
   - unsquelching
-  - unstored
   - unsuffixed
   - unvalidated
   - unveto
   - unvetoed
   - upvotes
   - USDB
-  - utilisation
   - variadics
   - venv
   - vfalco
   - vinnie
   - wasmi
-  - werror
   - wextra
   - wptr
   - writeme
@@ -415,18 +360,12 @@ words:
   - wthread
   - xbridge
   - xchain
-  - xcrun
   - ximinez
   - XMACRO
-  - xored
   - xrpkuwait
   - xrpl
   - xrpld
   - xrplf
   - xxhash
   - xxhasher
-  - xychart
-  - zpages
-  - zstdio
-  - ripplex
-  - mseconds
+  - CGNAT

.envrc

@@ -1,10 +1,3 @@
 watch_file nix/*.nix
 
-# Pinned Rust toolchain, read by nix/packages.nix via fromRustupToolchainFile.
-watch_file rust-toolchain.toml
-
-# The dev shell derivation includes all of conan/ (see nix/devshell.nix), so any
-# change in there has to invalidate direnv's cached environment.
-watch_dir conan
-
 use flake

.github/actions/cargo-cache/action.yml

@@ -1,39 +0,0 @@
-name: Use cargo artifacts cache
-description: >
-  Cache the cargo build artifacts with rust-cache. Never caches ~/.cargo/bin:
-  when saving the cache, rust-cache deletes all binaries that were already
-  present there, which on persistent self-hosted runners wipes the tools
-  installed by prepare-runner. Harmless on ephemeral runners, but kept
-  consistent everywhere.
-
-inputs:
-  workspaces:
-    description: "Workspaces to cache, as 'workspace -> target' lines."
-    required: false
-    default: crates
-  key:
-    description: "Additional part of the cache key."
-    required: false
-    default: ""
-  cache-directories:
-    description: "Additional non-workspace directories to cache."
-    required: false
-    default: ""
-  save-if:
-    description: >
-      Condition for saving the cache after the job. Defaults to save only from develop branch
-    required: false
-    default: ${{ github.ref == 'refs/heads/develop' }}
-
-runs:
-  using: composite
-
-  steps:
-    - name: Use cargo artifacts cache
-      uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
-      with:
-        cache-bin: "false"
-        cache-directories: ${{ inputs.cache-directories }}
-        key: ${{ inputs.key }}
-        save-if: ${{ inputs.save-if }}
-        workspaces: ${{ inputs.workspaces }}

.github/actions/generate-version/action.yml

@@ -0,0 +1,44 @@
+name: Generate build version number
+description: "Generate build version number."
+
+outputs:
+  version:
+    description: "The generated build version number."
+    value: ${{ steps.version.outputs.version }}
+
+runs:
+  using: composite
+  steps:
+    # When a tag is pushed, the version is used as-is.
+    - name: Generate version for tag event
+      if: ${{ startsWith(github.ref, 'refs/tags/') }}
+      shell: bash
+      env:
+        VERSION: ${{ github.ref_name }}
+      run: echo "VERSION=${VERSION}" >>"${GITHUB_ENV}"
+
+    # When a tag is not pushed, then the version (e.g. 1.2.3-b0) is extracted
+    # from the BuildInfo.cpp file and the shortened commit hash appended to it.
+    # We use a plus sign instead of a hyphen because Conan recipe versions do
+    # not support two hyphens.
+    - name: Generate version for non-tag event
+      if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      shell: bash
+      run: |
+        echo 'Extracting version from BuildInfo.cpp.'
+        VERSION="$(cat src/libxrpl/protocol/BuildInfo.cpp | grep "versionString =" | awk -F '"' '{print $2}')"
+        if [[ -z "${VERSION}" ]]; then
+            echo 'Unable to extract version from BuildInfo.cpp.'
+            exit 1
+        fi
+
+        echo 'Appending shortened commit hash to version.'
+        SHA='${{ github.sha }}'
+        VERSION="${VERSION}+${SHA:0:7}"
+
+        echo "VERSION=${VERSION}" >>"${GITHUB_ENV}"
+
+    - name: Output version
+      id: version
+      shell: bash
+      run: echo "version=${VERSION}" >>"${GITHUB_OUTPUT}"

.github/actions/release-info/action.yml

@@ -1,44 +0,0 @@
-name: Release info
-description: "Derive the version, release channel and package release number for this build."
-
-outputs:
-  version:
-    description: "The build version number."
-    value: ${{ steps.version.outputs.version }}
-  channel:
-    description: "The release channel this build belongs to."
-    value: ${{ steps.release_info.outputs.channel }}
-  pkg_release:
-    description: "The package release number: 1 for a tag, <run number>.<commit date>git<short commit hash> otherwise."
-    value: ${{ steps.release_info.outputs.pkg_release }}
-
-runs:
-  using: composite
-  steps:
-    # A tag names its own version. Anything else takes it from BuildInfo.cpp and
-    # appends the commit hash as build metadata, joined with a plus sign because a
-    # Conan version cannot contain two hyphens.
-    - name: Determine version
-      id: version
-      shell: bash
-      env:
-        IS_TAG: ${{ startsWith(github.ref, 'refs/tags/') }}
-        REF_NAME: ${{ github.ref_name }}
-        SHA: ${{ github.sha }}
-      run: |
-        if [[ "${IS_TAG}" == "true" ]]; then
-            version="${REF_NAME}"
-        else
-            version="$(awk -F'"' '/versionString =/ { print $2 }' src/libxrpl/protocol/BuildInfo.cpp)"
-            if [[ -z "${version}" ]]; then
-                echo "Unable to read versionString from BuildInfo.cpp." >&2
-                exit 1
-            fi
-            version="${version}+${SHA:0:7}"
-        fi
-
-        echo "version=${version}" | tee -a "${GITHUB_OUTPUT}"
-
-    - name: Determine release channel and package release
-      id: release_info
-      uses: XRPLF/actions/release-info@7cc0e4a8d9d0b838f92c48d312856b190341bbba

.github/actions/setup-nix-env/action.yml

@@ -1,70 +0,0 @@
-name: Setup Nix environment
-description: "Build the flake's CI environment and put its tools on PATH."
-
-# The environment from nix/ci-env.nix, the same one the Linux CI images bake in
-# (see nix/docker). Exported onto PATH rather than entered with `nix develop`:
-# the composite actions below run plain `bash` and would escape a dev shell.
-
-runs:
-  using: composite
-
-  steps:
-    - name: Build the CI environment
-      id: build
-      shell: bash
-      env:
-        # --out-link doubles as a GC root for the length of the job.
-        OUT_LINK: ${{ runner.temp }}/xrpld-ci-env
-      run: |
-        # --extra-experimental-features: flakes may not be on in the runner's nix.conf.
-        nix --extra-experimental-features "nix-command flakes" \
-            build .#default --out-link "${OUT_LINK}" --print-build-logs
-        echo "path=$(readlink -f "${OUT_LINK}")" >>"${GITHUB_OUTPUT}"
-
-    - name: Export the environment
-      shell: bash
-      env:
-        ENV_PATH: ${{ steps.build.outputs.path }}
-      run: |
-        echo "${ENV_PATH}/bin" >>"${GITHUB_PATH}"
-
-        # Already KEY=VALUE per line. See `darwinEnv` in nix/ci-env.nix.
-        ENV_FILE="${ENV_PATH}/share/xrpld-ci-env/env"
-        if [ -f "${ENV_FILE}" ]; then
-            cat "${ENV_FILE}" >>"${GITHUB_ENV}"
-        fi
-
-        # XrplSanity.cmake otherwise rejects a Nix compiler as one that leaked.
-        echo "XRPL_DEVSHELL=ci-env" >>"${GITHUB_ENV}"
-
-        # Unlike the Linux nix images, macOS needs no SSL_CERT_FILE: it has its
-        # own trust store, and pinning would break TLS to hosts relying on it.
-
-        # In RUNNER_TEMP, which the runner empties per job, like the `.conan2`
-        # prepare-runner hands the system toolchain - but under its own name:
-        # that Conan is a different version, and the two would migrate each
-        # other's cache.
-        echo "CONAN_HOME=${RUNNER_TEMP}/.conan2-nix" >>"${GITHUB_ENV}"
-
-    # Config, profiles and remote, exactly as the dev shell sets them up on
-    # entry; the `setup-conan` action is skipped for this toolchain.
-    - name: Setup Conan
-      shell: bash
-      run: ./conan/init.sh
-
-    # `Check tools` runs later but swallows failures; a bad export would just
-    # build with the system toolchain.
-    - name: Verify the toolchain resolves into the Nix store
-      shell: bash
-      run: |
-        for tool in clang clang++ cmake ninja conan; do
-            path="$(command -v "${tool}" || true)"
-            echo "${tool} -> ${path:-<not found>}"
-            case "${path}" in
-                /nix/store/*) ;;
-                *)
-                    echo "::error::${tool} does not resolve into the Nix store"
-                    exit 1
-                    ;;
-            esac
-        done

.github/dependabot.yml

@@ -4,8 +4,7 @@ updates:
     directories:
       - /
       - .github/actions/build-deps/
-      - .github/actions/cargo-cache/
-      - .github/actions/release-info/
+      - .github/actions/generate-version/
       - .github/actions/set-compiler-env/
       - .github/actions/setup-conan/
     schedule:
@@ -20,19 +19,3 @@ updates:
       github-actions:
         patterns:
           - "*"
-
-  - package-ecosystem: cargo
-    directory: /crates
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "chore: [DEPENDABOT] "
-    target-branch: develop
-    open-pull-requests-limit: 10
-    groups:
-      rust-dependencies:
-        patterns:
-          - "*"

.github/pull_request_template.md

@@ -18,7 +18,7 @@ If too broad, please consider splitting into multiple PRs.
 If there is a relevant task or issue, please link it here.
 -->
 
-## Context of Change
+### Context of Change
 
 <!--
 Please include the context of a change.
@@ -29,7 +29,7 @@ If a refactor, how is this better than the previous implementation?
 If there is a spec or design document for this feature, please link it here.
 -->
 
-## API Impact
+### API Impact
 
 <!--
 Please check [x] relevant options, delete irrelevant ones.

.github/scripts/levelization/results/loops.txt

@@ -7,12 +7,6 @@ Loop: xrpld.app xrpld.rpc
 Loop: xrpld.app xrpld.shamap
   xrpld.shamap > xrpld.app
 
-Loop: xrpld.app xrpld.telemetry
-  xrpld.telemetry ~= xrpld.app
-
 Loop: xrpld.overlay xrpld.rpc
   xrpld.rpc ~= xrpld.overlay
 
-Loop: xrpld.overlay xrpld.telemetry
-  xrpld.telemetry ~= xrpld.overlay
-

.github/scripts/levelization/results/ordering.txt

@@ -53,10 +53,6 @@ libxrpl.shamap > xrpl.basics
 libxrpl.shamap > xrpl.nodestore
 libxrpl.shamap > xrpl.protocol
 libxrpl.shamap > xrpl.shamap
-libxrpl.telemetry > xrpl.basics
-libxrpl.telemetry > xrpl.config
-libxrpl.telemetry > xrpl.protocol
-libxrpl.telemetry > xrpl.telemetry
 libxrpl.tx > xrpl.basics
 libxrpl.tx > xrpl.conditions
 libxrpl.tx > xrpl.core
@@ -64,7 +60,6 @@ libxrpl.tx > xrpl.json
 libxrpl.tx > xrpl.ledger
 libxrpl.tx > xrpl.protocol
 libxrpl.tx > xrpl.server
-libxrpl.tx > xrpl.telemetry
 libxrpl.tx > xrpl.tx
 test.app > test.jtx
 test.app > test.unit_test
@@ -87,6 +82,7 @@ test.app > xrpl.tx
 test.basics > test.jtx
 test.basics > xrpl.basics
 test.basics > xrpl.core
+test.basics > xrpld.rpc
 test.basics > xrpl.json
 test.basics > xrpl.protocol
 test.beast > xrpl.basics
@@ -117,7 +113,6 @@ test.jtx > xrpl.config
 test.jtx > xrpl.core
 test.jtx > xrpld.app
 test.jtx > xrpld.core
-test.jtx > xrpld.overlay
 test.jtx > xrpld.rpc
 test.jtx > xrpl.json
 test.jtx > xrpl.ledger
@@ -135,12 +130,8 @@ test.ledger > xrpl.json
 test.ledger > xrpl.ledger
 test.ledger > xrpl.protocol
 test.nodestore > test.jtx
-test.nodestore > test.unit_test
 test.nodestore > xrpl.basics
-test.nodestore > xrpl.config
-test.nodestore > xrpld.app
 test.nodestore > xrpld.core
-test.nodestore > xrpld.telemetry
 test.nodestore > xrpl.nodestore
 test.nodestore > xrpl.rdb
 test.overlay > test.jtx
@@ -192,8 +183,6 @@ tests.libxrpl > xrpl.basics
 tests.libxrpl > xrpl.config
 tests.libxrpl > xrpl.consensus
 tests.libxrpl > xrpl.core
-tests.libxrpl > xrpld.app
-tests.libxrpl > xrpld.rpc
 tests.libxrpl > xrpl.json
 tests.libxrpl > xrpl.ledger
 tests.libxrpl > xrpl.net
@@ -201,11 +190,9 @@ tests.libxrpl > xrpl.nodestore
 tests.libxrpl > xrpl.peerfinder
 tests.libxrpl > xrpl.protocol
 tests.libxrpl > xrpl.protocol_autogen
-tests.libxrpl > xrpl.rdb
 tests.libxrpl > xrpl.resource
 tests.libxrpl > xrpl.server
 tests.libxrpl > xrpl.shamap
-tests.libxrpl > xrpl.telemetry
 tests.libxrpl > xrpl.tx
 xrpl.conditions > xrpl.basics
 xrpl.conditions > xrpl.protocol
@@ -214,7 +201,6 @@ xrpl.consensus > xrpl.basics
 xrpl.consensus > xrpl.json
 xrpl.consensus > xrpl.ledger
 xrpl.consensus > xrpl.protocol
-xrpl.consensus > xrpl.telemetry
 xrpl.core > xrpl.basics
 xrpl.core > xrpl.json
 xrpl.core > xrpl.protocol
@@ -250,15 +236,10 @@ xrpl.server > xrpl.resource
 xrpl.shamap > xrpl.basics
 xrpl.shamap > xrpl.nodestore
 xrpl.shamap > xrpl.protocol
-xrpl.telemetry > xrpl.basics
-xrpl.telemetry > xrpl.config
-xrpl.telemetry > xrpl.core
-xrpl.telemetry > xrpl.protocol
 xrpl.tx > xrpl.basics
 xrpl.tx > xrpl.core
 xrpl.tx > xrpl.ledger
 xrpl.tx > xrpl.protocol
-xrpl.tx > xrpl.telemetry
 xrpld.app > test.unit_test
 xrpld.app > xrpl.basics
 xrpld.app > xrpl.config
@@ -275,7 +256,6 @@ xrpld.app > xrpl.rdb
 xrpld.app > xrpl.resource
 xrpld.app > xrpl.server
 xrpld.app > xrpl.shamap
-xrpld.app > xrpl.telemetry
 xrpld.app > xrpl.tx
 xrpld.core > xrpl.basics
 xrpld.core > xrpl.config
@@ -296,7 +276,6 @@ xrpld.overlay > xrpl.protocol
 xrpld.overlay > xrpl.resource
 xrpld.overlay > xrpl.server
 xrpld.overlay > xrpl.shamap
-xrpld.overlay > xrpl.telemetry
 xrpld.overlay > xrpl.tx
 xrpld.peerfinder > xrpl.basics
 xrpld.peerfinder > xrpld.app
@@ -307,11 +286,10 @@ xrpld.perflog > xrpl.basics
 xrpld.perflog > xrpl.config
 xrpld.perflog > xrpl.core
 xrpld.perflog > xrpld.app
+xrpld.perflog > xrpld.rpc
 xrpld.perflog > xrpl.json
 xrpld.perflog > xrpl.nodestore
 xrpld.perflog > xrpl.protocol
-xrpld.perflog > xrpl.server
-xrpld.perflog > xrpl.telemetry
 xrpld.rpc > xrpl.basics
 xrpld.rpc > xrpl.config
 xrpld.rpc > xrpl.core
@@ -325,20 +303,9 @@ xrpld.rpc > xrpl.rdb
 xrpld.rpc > xrpl.resource
 xrpld.rpc > xrpl.server
 xrpld.rpc > xrpl.shamap
-xrpld.rpc > xrpl.telemetry
 xrpld.rpc > xrpl.tx
 xrpld.shamap > xrpl.basics
 xrpld.shamap > xrpld.core
 xrpld.shamap > xrpl.nodestore
 xrpld.shamap > xrpl.protocol
 xrpld.shamap > xrpl.shamap
-xrpld.telemetry > xrpl.basics
-xrpld.telemetry > xrpl.consensus
-xrpld.telemetry > xrpl.core
-xrpld.telemetry > xrpld.core
-xrpld.telemetry > xrpl.json
-xrpld.telemetry > xrpl.nodestore
-xrpld.telemetry > xrpl.protocol
-xrpld.telemetry > xrpl.rdb
-xrpld.telemetry > xrpl.server
-xrpld.telemetry > xrpl.telemetry

.github/scripts/otel-naming/README.md

@@ -1,71 +0,0 @@
-# OTel naming-consistency check
-
-`check_otel_naming.py` enforces the OpenTelemetry span-attribute naming
-convention documented in
-[CONTRIBUTING.md](../../../CONTRIBUTING.md#telemetry-span-attribute-naming)
-across every layer of the telemetry pipeline. The `*SpanNames.h` constants are
-the single source of truth (L1); every other layer must agree with them.
-
-## Running locally
-
-```
-python .github/scripts/otel-naming/check_otel_naming.py
-```
-
-It takes no arguments, can be run from any directory inside the repo, and uses
-only the Python standard library (no `pip install`, matching the levelization
-check). A non-zero exit code means a violation was found; the output lists each
-violation as `RULE | location | token | expected`.
-
-## What it checks
-
-The valid key set is **derived dynamically from the OTel code** — there is no
-hardcoded allowlist:
-
-- **L1 keys** come from the `namespace attr { ... }` blocks of every
-  `*SpanNames.h`, resolving the `makeStr("x")` / `join(seg::a, seg::b)` DSL
-  (cross-file, so `join(seg::rpc, ...)` resolves `seg::rpc` from the base
-  `SpanNames.h`). Each constant is resolved against **its own** header, so two
-  headers that define a same-named constant (e.g. a base `attr::ledgerHash` and
-  a domain `attr::ledgerHash`) each contribute their real wire key — a later
-  header cannot clobber an earlier one's value in a flat table.
-- **Legitimate dotted keys** = ONLY the keys the code actually sets as resource
-  attributes, i.e. the entries inside `Telemetry.cpp`'s `Resource::Create({...})`
-  call: the `semconv::service::*` keys (`service.*`) plus any `attr::<name>`
-  constants passed there (`xrpl.network.*`). A dotted key that is _declared_ in a
-  header but never set as a resource attr is a span attribute in resource
-  clothing — a Rule-A violation, even if it lives in the base `SpanNames.h`.
-
-### Rules (each fails the build, when its inputs are present)
-
-| Rule | Check                                                                                                                                                                                                                                                                                    |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A    | No stray dotted span-attribute key (only the derived resource keys may be dotted).                                                                                                                                                                                                       |
-| G    | Attribute keys are `lower_snake_case` (`^[a-z][a-z0-9_]*$` per dot-segment) — no camelCase, UPPERCASE, or spaces.                                                                                                                                                                        |
-| F    | No string literals as attribute keys or span-name arguments in `setAttribute`/`addEvent`/`span`/`rootSpan`/`childSpan` (`rootSpan` shares `span`'s `(cat, prefix, name)` signature). Attribute _values_ are exempt (runtime data); `*SpanNames.h` definitions and test files are exempt. |
-| B    | Every collector `spanmetrics.dimensions` name exists in the L1 key set.                                                                                                                                                                                                                  |
-| C    | Every Tempo span-filter tag exists in the L1 key set.                                                                                                                                                                                                                                    |
-| D    | Every dashboard label resolves to an L1 span attribute, a native-metric label (L6, emitted by MetricsRegistry), or a Prometheus/Grafana builtin. TraceQL scope prefixes (`span.`/`resource.`/…) are stripped before the L1 lookup.                                                       |
-| E    | No dotted `xrpl.<domain>.<field>` attribute key in the runbook (only the L1 resource attrs `xrpl.network.*` may be dotted). Span names, filenames, OTel-standard keys, and metric labels are not flagged.                                                                                |
-
-Rule F runs **unconditionally** (it is a purely syntactic check on the
-call-sites and needs no `*SpanNames.h`), so a code path that calls
-`SpanGuard::span`/`setAttribute` directly without ever defining a header is
-still caught.
-
-### Warnings (printed, never fail the build)
-
-| Rule | Check                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| H    | A namespace-qualified constant (e.g. `foo::bar::myKey`) used at a telemetry call-site is not defined in any `*SpanNames.h`. The constant should live in the proper header; defining it in-place bypasses rules A/G/F. Warns rather than fails — the argument may be a legitimately dynamic value, and the header may live on a later branch. Bare locals and `std::` names are not warned.                                                                                                                                                                                                                                                                                                                   |
-| M    | A constant defined in a `*SpanNames.h` that no code in `src/**` or `include/**` references — the reverse of every failing rule above, which all start from a consumer and look for its L1 source. Deleting the last `setAttribute(attr::foo, …)` while leaving `attr::foo` in the header otherwise passes every rule and the compiler, and the telemetry silently stops being emitted. Whole files are searched rather than telemetry call sites only, since a constant is also passed to helpers and used as an attribute _value_. Constants only test code references are reported separately. Warns rather than fails: in a stacked chain a constant may legitimately land a commit before its call site. |
-
-## Presence-gated
-
-Every rule runs **only when the source files it needs are present** in the tree
-and is otherwise skipped (printed as `SKIP: <rule> — <reason>`), never failed.
-This keeps the check correct no matter how telemetry work is split across PRs —
-a stacked chain, one large PR, or independent per-stage PRs where (for example)
-the collector config lands before the dashboards. The collector/Tempo/dashboard/
-runbook layers are introduced in later phases; on a branch without them, only
-the L1-intrinsic rules (A, G, F) run.

.github/scripts/rename/binary.sh

@@ -49,7 +49,7 @@ ${SED_COMMAND} -i -E 's@ripple/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@xrpld \(`xrpld`\)@xrpld@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' CONTRIBUTING.md
-${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/install.md
+${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/build/install.md
 
 popd
 echo "Processing complete."

.github/scripts/rename/docs.sh

@@ -77,8 +77,8 @@ ${SED_COMMAND} -i 's/Ripple integrators/XRPL developers/' README.md
 ${SED_COMMAND} -i 's/sanitizer-configuration-for-rippled/sanitizer-configuration-for-xrpld/' docs/build/sanitizers.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/levelization/README.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/strategy-matrix/generate.py
-${SED_COMMAND} -i 's@/rippled@/xrpld@g' docs/install.md
-${SED_COMMAND} -i 's@github.com/XRPLF/xrpld@github.com/XRPLF/rippled@g' docs/install.md
+${SED_COMMAND} -i 's@/rippled@/xrpld@g' docs/build/install.md
+${SED_COMMAND} -i 's@github.com/XRPLF/xrpld@github.com/XRPLF/rippled@g' docs/build/install.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' docs/Doxyfile
 ${SED_COMMAND} -i 's/ripple_basics/basics/' include/xrpl/basics/CountedObject.h
 ${SED_COMMAND} -i 's/<ripple/<xrpl/' include/xrpl/protocol/AccountID.h

.github/scripts/strategy-matrix/generate.py

@@ -7,21 +7,7 @@ from pathlib import Path
 
 THIS_DIR = Path(__file__).parent.resolve()
 
-_BASE_CMAKE_ARGS = [
-    "-Dtests=ON",
-    "-Dwerr=ON",
-    "-Dxrpld=ON",
-    "-Dwextra=ON",
-    "-Drust=ON",
-]
-
-# The package formats a config can be packaged as, each with its own
-# install-test job in reusable-package.yml.
-PACKAGE_TYPES = ("deb", "rpm")
-
-# The package name a variant suffixes, as build_pkg.py's BASE_NAME spells it:
-# the two have to agree, or the artifact globs miss what was built.
-BASE_NAME = "xrpld"
+_BASE_CMAKE_ARGS = ["-Dtests=ON", "-Dwerr=ON", "-Dxrpld=ON", "-Dwextra=ON"]
 
 # Maps sanitizer names (as used in cmake) to short config-name suffixes.
 _SANITIZER_SUFFIX: dict[str, str] = {
@@ -31,19 +17,6 @@ _SANITIZER_SUFFIX: dict[str, str] = {
 }
 
 
-def config_name(
-    distro: str,
-    compiler: str,
-    build_type: str,
-    arch: str,
-    suffix: str = "",
-    sanitizer: str = "",
-) -> str:
-    """Name a config. Its artifacts are named after it, so packaging reuses this."""
-    parts = [s for s in [suffix, _SANITIZER_SUFFIX.get(sanitizer, "")] if s]
-    return "-".join([f"{distro}-{compiler}-{build_type.lower()}-{arch}", *parts])
-
-
 def get_cmake_args(build_type: str, extra_args: str) -> str:
     """Get the full list of CMake arguments for a config."""
     args = _BASE_CMAKE_ARGS.copy()
@@ -58,51 +31,22 @@ def get_cmake_args(build_type: str, extra_args: str) -> str:
 
 
 # Every config must declare 'minimal'. Minimal configs form the reduced matrix
-# built for pull requests by default; the full matrix adds the rest.
-#
-# Configs may also opt into 'benchmark' to smoke-run the benchmarks, or carry a
-# 'package' map to be packaged as well. Note that either applies to every entry
-# a config expands into, so only set them on configs that expand to a single
-# combination.
-
-
-@dataclasses.dataclass
-class PackageConfig:
-    """The 'package' map of a config whose binaries are also packaged."""
-
-    type: str  # has to match what the image provides
-    # The packaging container image: a vanilla distro image, not the nix image
-    # the config itself builds in.
-    image: str
-    # A flavour of the package, named xrpld-<variant>, for a config whose
-    # binaries are not the plain release build. A variant needs no counterpart
-    # in the other format.
-    variant: str = ""
-
-    def __post_init__(self) -> None:
-        assert self.type in PACKAGE_TYPES, (
-            f"unsupported package type {self.type!r}: "
-            f"use one of {', '.join(PACKAGE_TYPES)}."
-        )
+# built for pull requests by default; the full matrix adds the rest. Packaging
+# configs declare it too, but packaging is gated in the workflow, not by it.
 
 
 @dataclasses.dataclass
 class LinuxConfig:
-    """One entry in a linux.json 'configs' array."""
+    """One entry in linux.json's 'configs' or 'package_configs' arrays."""
 
     compiler: list[str]
     build_type: list[str]
     arch: list[str]
     minimal: bool
-    benchmark: bool = False  # if true, smoke-run the benchmarks after testing
     sanitizers: list[str] = dataclasses.field(default_factory=list)
     suffix: str = ""
     extra_cmake_args: str = ""
-    package: PackageConfig | None = None  # set to also package this config
-
-    def __post_init__(self) -> None:
-        if isinstance(self.package, dict):
-            self.package = PackageConfig(**self.package)
+    image: str = ""  # only used by package_configs entries
 
 
 @dataclasses.dataclass
@@ -111,16 +55,22 @@ class LinuxFile:
 
     image_tag: str
     configs: dict[str, list[LinuxConfig]]  # distro → configs
+    package_configs: dict[str, list[LinuxConfig]]  # distro → packaging configs
 
     @classmethod
     def load(cls, path: Path) -> "LinuxFile":
         data = json.loads(path.read_text())
+
+        def parse(section: dict) -> dict[str, list[LinuxConfig]]:
+            return {
+                distro: [LinuxConfig(**c) for c in cfgs]
+                for distro, cfgs in section.items()
+            }
+
         return cls(
             image_tag=data["image_tag"],
-            configs={
-                distro: [LinuxConfig(**c) for c in cfgs]
-                for distro, cfgs in data["configs"].items()
-            },
+            configs=parse(data["configs"]),
+            package_configs=parse(data.get("package_configs", {})),
         )
 
 
@@ -131,11 +81,7 @@ class PlatformConfig:
     build_type: list[str]
     minimal: bool
     build_only: bool = False  # if true, skip tests (e.g. macos/Windows Debug)
-    benchmark: bool = False  # if true, smoke-run the benchmarks after testing
     extra_cmake_args: str = ""
-    # "" is the runner's system compiler, "nix" the flake's CI environment.
-    # macOS only: Linux always builds in a Nix image, Windows has no Nix.
-    toolchain: str = ""
 
     def __post_init__(self) -> None:
         if isinstance(self.build_type, str):
@@ -179,25 +125,20 @@ class MatrixEntry:
     cmake_args: str
     cmake_target: str
     build_only: bool
-    benchmark: bool
     build_type: str
     architecture: Architecture
     sanitizers: str
     image: str = ""  # container image; empty for macOS/Windows (runs natively)
     compiler: str = ""  # compiler name ("gcc" or "clang"); empty for macOS/Windows
-    toolchain: str = ""  # "nix" for the flake's CI environment; see PlatformConfig
 
 
 @dataclasses.dataclass
 class PackagingEntry:
     """One entry in the generated packaging strategy matrix."""
 
-    xrpld_artifact_name: str
-    validator_keys_artifact_name: str
+    artifact_name: str
     image: str
-    package_type: str  # "deb" or "rpm"; drives the format-specific steps
-    package_variant: str  # passed to build_pkg.py --variant; empty for xrpld
-    package_name: str  # the name it builds under, which the artifact globs use
+    distro: str  # e.g. "debian" or "rhel"; drives package-format-specific steps
 
 
 # ---------------------------------------------------------------------------
@@ -238,9 +179,13 @@ def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
                 effective_sanitizers,
                 effective_archs.items(),
             ):
-                name = config_name(
-                    distro, compiler, build_type, arch, cfg.suffix, sanitizer
-                )
+                name = f"{distro}-{compiler}-{build_type.lower()}-{arch}"
+                suffix_parts = [
+                    s for s in [cfg.suffix, _SANITIZER_SUFFIX.get(sanitizer, "")] if s
+                ]
+                if suffix_parts:
+                    name += "-" + "-".join(suffix_parts)
+
                 entries.append(
                     MatrixEntry(
                         config_name=name,
@@ -248,7 +193,6 @@ def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
                         cmake_args=get_cmake_args(build_type, cfg.extra_cmake_args),
                         cmake_target="all",
                         build_only=False,
-                        benchmark=cfg.benchmark,
                         build_type=build_type,
                         architecture=arch_info,
                         sanitizers=sanitizer,
@@ -260,59 +204,28 @@ def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
 
 
 def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
-    """Generate the packaging matrix from the configs that carry a 'package' map.
+    """Generate the packaging matrix from a LinuxFile's package_configs section.
 
-    Packaging consumes the binaries that config's build job uploaded, so the
-    artifact names come from the same config name, and a packaged config is one
-    that passes -Dvalidator_keys=ON.
-
-    Packaging itself runs in vanilla distro images (debian:trixie, almalinux:10)
-    instead of the nix-based build images, because deb/rpm tooling (debhelper,
-    rpm-build) is taken from the distro's archive rather than from nixpkgs.
+    Packaging uses vanilla distro images (debian:bookworm, ubi9, …) instead of
+    the nix-based build images, because deb/rpm tooling (debhelper, rpm-build)
+    is taken from the distro's archive rather than from nixpkgs. Each config
+    entry carries its own 'image'.
     """
     entries = []
-    for distro, configs in linux.configs.items():
+    for distro, configs in linux.package_configs.items():
         for cfg in configs:
-            if cfg.package is None:
-                continue
-            for compiler, build_type, arch in itertools.product(
-                cfg.compiler, cfg.build_type, cfg.arch
-            ):
-                # The packaging workflow hardcodes an amd64 runner.
-                assert arch == "amd64", f"cannot package {distro} on {arch}"
-                name = config_name(distro, compiler, build_type, arch, cfg.suffix)
+            for compiler, build_type in itertools.product(cfg.compiler, cfg.build_type):
                 entries.append(
                     PackagingEntry(
-                        xrpld_artifact_name=f"xrpld-{name}",
-                        validator_keys_artifact_name=f"validator-keys-{name}",
-                        image=cfg.package.image,
-                        package_type=cfg.package.type,
-                        package_variant=cfg.package.variant,
-                        package_name=(
-                            f"{BASE_NAME}-{cfg.package.variant}"
-                            if cfg.package.variant
-                            else BASE_NAME
-                        ),
+                        artifact_name=f"xrpld-{distro}-{compiler}-{build_type.lower()}-amd64",
+                        image=cfg.image,
+                        distro=distro,
                     )
                 )
 
     return entries
 
 
-def package_names_by_type(entries: list[PackagingEntry]) -> dict[str, list[str]]:
-    """The names of the packages in 'entries', keyed by format.
-
-    Derived from the packaging matrix rather than listed again, so the packages
-    the install-test jobs look for are the packages that were built.
-    """
-    return {
-        package_type: sorted(
-            {e.package_name for e in entries if e.package_type == package_type}
-        )
-        for package_type in PACKAGE_TYPES
-    }
-
-
 def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]:
     """Expand a PlatformFile (macOS or Windows) into matrix entries.
 
@@ -326,20 +239,15 @@ def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]
         if minimal and not cfg.minimal:
             continue
         for build_type in cfg.build_type:
-            name = f"{platform_name}-{arch}-{build_type.lower()}"
-            if cfg.toolchain:
-                name += f"-{cfg.toolchain}"
             entries.append(
                 MatrixEntry(
-                    config_name=name,
+                    config_name=f"{platform_name}-{arch}-{build_type.lower()}",
                     cmake_args=get_cmake_args(build_type, cfg.extra_cmake_args),
                     cmake_target="install" if is_windows else "all",
                     build_only=cfg.build_only,
-                    benchmark=cfg.benchmark,
                     build_type=build_type,
                     architecture=Architecture(platform=pf.platform, runner=pf.runner),
                     sanitizers="",
-                    toolchain=cfg.toolchain,
                 )
             )
     return entries
@@ -381,10 +289,6 @@ if __name__ == "__main__":
 
     if args.packaging:
         matrix = expand_linux_packaging(LinuxFile.load(THIS_DIR / "linux.json"))
-        # One list per format, so each install-test job installs the packages its
-        # own format produced.
-        for package_type, names in package_names_by_type(matrix).items():
-            print(f"{package_type}_package_names={json.dumps(names)}")
     else:
         if args.config in ("linux", None):
             matrix += expand_linux_matrix(

.github/scripts/strategy-matrix/linux.json

@@ -1,5 +1,5 @@
 {
-  "image_tag": "sha-060957e",
+  "image_tag": "sha-fecfc0c",
   "configs": {
     "ubuntu": [
       {
@@ -14,8 +14,7 @@
         "compiler": ["clang"],
         "build_type": ["Release"],
         "arch": ["amd64"],
-        "minimal": true,
-        "benchmark": true
+        "minimal": true
       },
 
       {
@@ -70,25 +69,27 @@
         "compiler": ["gcc"],
         "build_type": ["Release"],
         "arch": ["amd64"],
-        "minimal": false,
-        "extra_cmake_args": "-Dvalidator_keys=ON",
-        "package": {
-          "type": "deb",
-          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-49cdc10"
-        }
-      },
+        "minimal": false
+      }
+    ],
+
+    "rhel": [
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false
+      }
+    ]
+  },
+  "package_configs": {
+    "debian": [
       {
         "compiler": ["gcc"],
         "build_type": ["Release"],
         "arch": ["amd64"],
         "minimal": false,
-        "suffix": "assert",
-        "extra_cmake_args": "-Dvalidator_keys=ON -Dassert=ON",
-        "package": {
-          "type": "deb",
-          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-49cdc10",
-          "variant": "assert"
-        }
+        "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-577d745"
       }
     ],
 
@@ -98,11 +99,7 @@
         "build_type": ["Release"],
         "arch": ["amd64"],
         "minimal": false,
-        "extra_cmake_args": "-Dvalidator_keys=ON",
-        "package": {
-          "type": "rpm",
-          "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-49cdc10"
-        }
+        "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-577d745"
       }
     ]
   }

.github/scripts/strategy-matrix/macos.json

@@ -12,19 +12,6 @@
       "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
       "build_only": true,
       "minimal": false
-    },
-    {
-      "build_type": "Release",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
-      "toolchain": "nix",
-      "minimal": false
-    },
-    {
-      "build_type": "Debug",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
-      "toolchain": "nix",
-      "build_only": true,
-      "minimal": false
     }
   ]
 }

.github/scripts/telemetry/check_bucket_parity.py

@@ -1,130 +0,0 @@
-#!/usr/bin/env python3
-"""Assert the C++ millisecond ladder agrees with the collector's spanmetrics ladder.
-
-The two are specified to match so a span-derived latency panel and a native
-histogram panel can be read on the same scale. Nothing else couples them, so
-extending one ladder alone -- sub-millisecond edges below 1ms, second-scale
-edges up to 30s -- silently leaves the other short. That failure is quiet:
-Prometheus returns the second-highest edge for a quantile landing in the
-`+Inf` bucket, so every quantile above a too-low ceiling reads back as a flat
-number that looks like a measurement rather than an error. This check is what
-makes the drift loud.
-
-The rule is containment, not equality:
-
-  * every representable collector edge MUST appear in the C++ ladder, so the
-    shared range reads identically;
-  * the C++ ladder MAY carry extra edges ABOVE the collector's highest edge,
-    because jobs outlive spans -- the updatepaths job type was measured
-    averaging ~60s, which no span approaches. Demanding equality would force a
-    ceiling that censors it, recreating the failure this guards against;
-  * collector edges below 1ms are expected to be ABSENT rather than missing:
-    beast::insight::Event rounds every duration up to a whole millisecond
-    before it reaches the histogram, so those edges could never collect a
-    sample.
-
-Exit 0 when the ladders agree, 1 with a diff when they do not.
-"""
-
-import re
-import sys
-from pathlib import Path
-
-HEADER = Path("include/xrpl/telemetry/HistogramBuckets.h")
-COLLECTOR = Path("docker/telemetry/otel-collector-config.yaml")
-
-# beast::insight::Event applies ceil<milliseconds>, so anything below 1ms
-# collapses onto the 1ms edge.
-REPRESENTABLE_FLOOR_MS = 1.0
-
-UNIT_TO_MS = {"ms": 1.0, "s": 1000.0}
-
-
-def collector_edges_ms():
-    """Parse the spanmetrics bucket list, normalising each edge to milliseconds."""
-    text = COLLECTOR.read_text()
-    match = re.search(r"buckets:\s*\[(.*?)\]", text, re.S)
-    if not match:
-        sys.exit(f"{COLLECTOR}: no 'buckets:' list found")
-
-    edges = []
-    for raw in match.group(1).split(","):
-        token = raw.strip()
-        if not token:
-            continue
-        parsed = re.fullmatch(r"([0-9.]+)(ms|s)", token)
-        if not parsed:
-            sys.exit(f"{COLLECTOR}: cannot parse bucket edge {token!r}")
-        edges.append(float(parsed.group(1)) * UNIT_TO_MS[parsed.group(2)])
-    return edges
-
-
-def cpp_edges_ms():
-    """Parse kMillisecondBuckets out of the header that owns every ladder."""
-    text = HEADER.read_text()
-    match = re.search(r"kMillisecondBuckets\{(.*?)\};", text, re.S)
-    if not match:
-        sys.exit(f"{HEADER}: kMillisecondBuckets not found")
-    return [
-        float(token.strip().replace("'", ""))
-        for token in match.group(1).split(",")
-        if token.strip()
-    ]
-
-
-def main():
-    collector = collector_edges_ms()
-    cpp = cpp_edges_ms()
-    required = [edge for edge in collector if edge >= REPRESENTABLE_FLOOR_MS]
-    if not required:
-        sys.exit(f"{COLLECTOR}: no edges at or above {REPRESENTABLE_FLOOR_MS} ms")
-    collector_top = max(required)
-
-    missing = [edge for edge in required if edge not in cpp]
-    # An extra C++ edge inside the collector's range means the two scales
-    # disagree where they overlap. Above the collector's top it is a deliberate
-    # extension.
-    inside_range = [e for e in cpp if e not in required and e < collector_top]
-
-    if not missing and not inside_range:
-        extensions = [e for e in cpp if e > collector_top]
-        summary = f"OK: all {len(required)} representable collector edges present"
-        if extensions:
-            pretty = ", ".join(f"{e:g}" for e in extensions)
-            summary += (
-                f"; {len(extensions)} extension edge(s) above "
-                f"{collector_top:g} ms: [{pretty}]"
-            )
-        print(summary)
-        return 0
-
-    print("Bucket ladder parity violated.", file=sys.stderr)
-    print(
-        f"  collector (>= {REPRESENTABLE_FLOOR_MS:g} ms): "
-        f"{[f'{e:g}' for e in required]}",
-        file=sys.stderr,
-    )
-    print(
-        f"  HistogramBuckets.h            : {[f'{e:g}' for e in cpp]}", file=sys.stderr
-    )
-    for edge in missing:
-        print(f"  MISSING from the C++ ladder: {edge:g} ms", file=sys.stderr)
-    for edge in inside_range:
-        print(
-            f"  C++ edge {edge:g} ms lies inside the collector's range but is not "
-            "a collector edge -- add it to the collector or drop it here",
-            file=sys.stderr,
-        )
-    print(
-        "\nThe two ladders must agree over their shared range. Extra C++ edges are\n"
-        "permitted only ABOVE the collector's highest edge. To re-price the shared\n"
-        f"range, edit the ladder in {HEADER} and the\n"
-        f"spanmetrics 'buckets:' list in {COLLECTOR}\n"
-        "in the same change, so both sides stay in step.",
-        file=sys.stderr,
-    )
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/scripts/telemetry/check_regression_bounds.py

@@ -1,496 +0,0 @@
-#!/usr/bin/env python3
-"""Assert every workload-gate absolute bound is the one its own baseline implies.
-
-The regression gate in ``docker/telemetry/workload`` fails CI when a span or
-job-queue quantile grows. Whether it *can* fail is decided by
-``regression-thresholds.json``, and that file's numbers are derived from
-``baselines/baseline-timings.json`` plus the two histogram ladders. Nothing
-tied the three together, and the gate has now been broken three times by the
-same class of drift:
-
-  1. the microsecond ladder's floor moved 100us -> 1us, voiding every
-     job_queue baseline captured before it;
-  2. the spanmetrics ladder's floor moved 1ms -> 0.01ms, voiding every
-     sub-millisecond span baseline captured before it;
-  3. the absolute bounds stayed calibrated for a 5-25ms band the spans had
-     left, so a 100x regression on ``span.ledger.store.p95`` reported zero
-     regressions and exit 0.
-
-Each time the gate stayed green, which is indistinguishable from a passing
-build. Documentation did not prevent recurrence, so this is a check.
-
-The rule it enforces is the one recorded in ``regression-thresholds.json``
-under ``_absolute_bound_derivation``: for a baseline sitting in the half-open
-bucket ``(lo, hi]`` of its ladder, with ``hi_next`` the next edge above ``hi``,
-
-    max_abs_increase_* == hi_next - baseline
-
-so the gate trips only when the reading clears the bucket *above* the
-baseline's own. Six rules are checked:
-
-  A  the baseline's key set equals the surface ``regression-metrics.json``
-     declares (a stale key left behind reads as covered but never gates);
-  B  every gated key has a per-metric override, not a fallback default;
-  C  each absolute bound equals ``hi_next - baseline``;
-  D  each percentage bound stays below ``100 * bound / baseline``, so the
-     absolute bound remains the operative half of the ``AND`` -- the span
-     ladder's 2s/3s/4s edges are only 1.25x-1.5x apart, where this silently
-     stops being true;
-  E  no baseline carries the ladder-floor signature ``quantile x first_edge``,
-     which means every sample landed in the first bucket and the number is
-     interpolation arithmetic rather than a latency;
-  F  every entry in ``excluded_keys`` names a key the surface would otherwise
-     declare, carries a reason, and has neither a threshold override nor a
-     baseline value left behind.
-
-Rule A subtracts ``excluded_keys`` from BOTH sides of its comparison, so a
-quantile removed from the gated set neither reads as a missing baseline nor as
-an undeclared one -- an exclusion left in the baseline is one failure, rule F's,
-which names the file to edit. Rule F is what keeps that subtraction honest: an
-exclusion is the one edit here that makes the gate cover LESS, so a stale or
-misspelt entry must fail rather than silently widen itself.
-
-A PLACEHOLDER baseline -- ``"placeholder": true`` or an empty ``metrics``
-object -- exits 0, because that is the documented bootstrap state and CI has to
-stay green while a baseline is being recaptured. A missing, unreadable or
-malformed input is a different thing and exits 1: a check that reports success
-without having checked anything is the same green-build-that-is-not failure this
-script exists to prevent, so renaming or deleting one of its inputs must not
-silence it.
-
-A baseline ENTRY that is not an object, or whose value is not a positive finite
-number, is rejected before any rule runs -- see ``check_key`` and
-``_unusable_baseline``. Every rule does arithmetic on that value,
-and a degenerate one made the script crash with a traceback (rule D divides by
-it) or emit advice about the wrong file (a negative value inverts rule D's
-comparison). Reporting malformed input is what this script is for, so it must
-name the key rather than die on it.
-
-Exit 0 when every rule holds, 1 with per-key detail otherwise.
-"""
-
-import json
-import math
-import re
-import sys
-from pathlib import Path
-
-WORKLOAD = Path("docker/telemetry/workload")
-BASELINE = WORKLOAD / "baselines/baseline-timings.json"
-THRESHOLDS = WORKLOAD / "regression-thresholds.json"
-METRICS = WORKLOAD / "regression-metrics.json"
-COLLECTOR = Path("docker/telemetry/otel-collector-config.yaml")
-HEADER = Path("include/xrpl/telemetry/HistogramBuckets.h")
-
-UNIT_TO_MS = {"ms": 1.0, "s": 1000.0}
-# A bound may differ from the derived value only by double round-tripping.
-REL_TOLERANCE = 1e-12
-
-
-def is_number(value):
-    """True for a real JSON number. bool is an int subclass, so exclude it."""
-    return not isinstance(value, bool) and isinstance(value, (int, float))
-
-
-def read_text_or_exit(path):
-    """Read a required text input, or exit 1 naming the input that failed."""
-    try:
-        return path.read_text()
-    except OSError as exc:
-        sys.exit(f"{path}: required input could not be read -- {exc}")
-
-
-def read_json_or_exit(path):
-    """Read and parse a required JSON object, or exit 1 naming what failed.
-
-    All three JSON inputs are objects. A top-level null, list or number parses
-    fine and then dies on the first .get, so check the shape here rather than
-    report it as a traceback pointing into this script.
-    """
-    try:
-        parsed = json.loads(read_text_or_exit(path))
-    except json.JSONDecodeError as exc:
-        sys.exit(f"{path}: required input is not valid JSON -- {exc}")
-    if not isinstance(parsed, dict):
-        sys.exit(
-            f"{path}: required input is valid JSON but its top level is "
-            f"{type(parsed).__name__}, not an object -- nothing can be read from it"
-        )
-    return parsed
-
-
-def span_edges_ms():
-    """Parse the spanmetrics bucket list, normalising each edge to milliseconds."""
-    match = re.search(r"buckets:\s*\[(.*?)\]", read_text_or_exit(COLLECTOR), re.S)
-    if not match:
-        sys.exit(f"{COLLECTOR}: no 'buckets:' list found")
-    edges = []
-    for raw in match.group(1).split(","):
-        token = raw.strip()
-        if not token:
-            continue
-        parsed = re.fullmatch(r"([0-9.]+)(ms|s)", token)
-        if not parsed:
-            sys.exit(f"{COLLECTOR}: cannot parse bucket edge {token!r}")
-        edges.append(float(parsed.group(1)) * UNIT_TO_MS[parsed.group(2)])
-    return edges
-
-
-def microsecond_edges():
-    """Parse kMicrosecondBuckets out of the header that owns every ladder."""
-    match = re.search(r"kMicrosecondBuckets\{(.*?)\};", read_text_or_exit(HEADER), re.S)
-    if not match:
-        sys.exit(f"{HEADER}: kMicrosecondBuckets not found")
-    return [
-        float(token.strip().replace("'", ""))
-        for token in match.group(1).split(",")
-        if token.strip()
-    ]
-
-
-def declared_keys(metrics_cfg):
-    """Rebuild the flat key set regression-metrics.json declares.
-
-    Deliberately reimplemented rather than imported from ``prom_queries.py``,
-    which pulls in aiohttp; CI telemetry checks stay dependency-free. The key
-    format is fixed by that file's own ``_key_format`` field.
-
-    ``excluded_keys`` is NOT subtracted here: rule F needs the full product to
-    tell a real exclusion from a misspelt one. Callers that want the gated
-    surface subtract it themselves.
-    """
-    keys = set()
-    spans = metrics_cfg.get("spans", {})
-    for name in spans.get("names", []):
-        for quantile in spans.get("_quantiles", []):
-            keys.add(f"span.{name}.p{_quantile_label(quantile)}")
-    jobs = metrics_cfg.get("job_queue", {})
-    for name in jobs.get("names", []):
-        for phase in jobs.get("_phases", []):
-            for quantile in jobs.get("_quantiles", []):
-                keys.add(f"job.{name}.{phase}.p{_quantile_label(quantile)}")
-    return keys
-
-
-def _quantile_label(quantile):
-    """0.95 -> '95', 0.5 -> '50', matching capture_timings.py's key format."""
-    return f"{quantile * 100:g}".replace(".", "")
-
-
-def brackets(value, edges):
-    """Return ``(lo, hi, hi_next)`` for the bucket ``(lo, hi]`` holding value."""
-    padded = [0.0] + list(edges)
-    for i in range(1, len(padded)):
-        if value <= padded[i]:
-            hi_next = padded[i + 1] if i + 1 < len(padded) else None
-            return padded[i - 1], padded[i], hi_next
-    return None, None, None
-
-
-def resolve_override(key, thresholds):
-    """Return the override rule for a key, or None if it falls back to defaults."""
-    group, quantile = key.rsplit(".", 1)
-    return thresholds.get("overrides", {}).get(group, {}).get(quantile)
-
-
-def check_exclusions(metrics_cfg, thresholds, baseline_metrics, declared):
-    """Apply rule F to every entry in ``excluded_keys``.
-
-    An exclusion is the only edit to this config that makes the gate cover
-    LESS, so each entry has to prove it is deliberate and complete:
-
-      * it names a key the names x quantiles product would otherwise declare,
-        so a typo or a stale entry surviving a surface change is caught rather
-        than silently subtracting nothing;
-      * it carries a non-empty reason, because "why is this not gated" is the
-        question a future maintainer will ask and prose is the only answer;
-      * no threshold override and no baseline value are left behind, since
-        either would read as gated to anyone grepping for the key.
-
-    Args:
-        metrics_cfg:      Parsed regression-metrics.json.
-        thresholds:       Parsed regression-thresholds.json.
-        baseline_metrics: The baseline's ``metrics`` map.
-        declared:         Output of declared_keys(), before exclusions come off.
-
-    Returns:
-        A list of failure strings, empty when every entry is well formed.
-    """
-    failures = []
-    for key, reason in sorted(metrics_cfg.get("excluded_keys", {}).items()):
-        if key not in declared:
-            failures.append(
-                f"{key}: listed in excluded_keys but not produced by the "
-                f"names x quantiles product, so it subtracts nothing -- fix the "
-                f"spelling or drop the entry (rule F)"
-            )
-            continue
-        if not isinstance(reason, str) or not reason.strip():
-            failures.append(
-                f"{key}: excluded with no reason. Record why it is not gated, "
-                f"with the measurement behind it (rule F)"
-            )
-        if resolve_override(key, thresholds) is not None:
-            failures.append(
-                f"{key}: excluded but still has a threshold override, which "
-                f"reads as gated -- remove it from {THRESHOLDS} (rule F)"
-            )
-        if key in baseline_metrics:
-            failures.append(
-                f"{key}: excluded but still has a baseline value, so rule A "
-                f"would pass while nothing gates it -- remove it from "
-                f"{BASELINE} (rule F)"
-            )
-    return failures
-
-
-def _unusable_baseline(key, value, unit):
-    """Reject a baseline value no rule below could evaluate, or None if it is fine.
-
-    Every rule downstream does arithmetic on this number, and two of them break
-    on a degenerate one rather than reporting it:
-
-      * rule D computes ``100 * bound / value``, which raises
-        ZeroDivisionError on ``0.0``. The script then dies with a traceback
-        instead of naming the key -- a validator that crashes where it should
-        report is the same green-build-that-is-not failure in reverse;
-      * a NEGATIVE value makes that same ratio negative, so ``pct >= ratio`` is
-        true for any configured percentage and rule D fires with a message
-        telling the maintainer to lower ``max_pct_increase``. The advice is
-        wrong: the fault is the baseline, not the threshold;
-      * a non-numeric value raises TypeError inside rule E's subtraction.
-
-    Rule E does not cover the zero case, which is easy to assume it does: its
-    test ``abs(value - quantile * first_edge) <= 1e-9 * first_edge`` reduces to
-    ``quantile <= 1e-9`` when value is ``0.0``, and that is false for every
-    quantile this harness captures (0.5, 0.95, 0.99).
-
-    None of these arise from the normal pipeline -- ``histogram_quantile`` over
-    a first-bucket-only histogram returns ``quantile x first_edge``, never zero,
-    and rule E is the guard for exactly that. They arise from a hand-edited or
-    truncated baseline, which is precisely the input this script exists to
-    reject.
-
-    Args:
-        key:   Flat metric key, for the message.
-        value: The baseline value as read from the file.
-        unit:  The entry's unit, for the message.
-
-    Returns:
-        A failure string, or None when the value is usable.
-    """
-    # bool is a subclass of int; True would otherwise pass as the number 1.
-    if not is_number(value):
-        return (
-            f"{key}: baseline value {value!r} is not a number, so no bound can be "
-            f"derived from it. Recapture the baseline from a CI run rather than "
-            f"editing it by hand -- see baselines/README.md"
-        )
-    if not math.isfinite(value) or value <= 0:
-        return (
-            f"{key}: baseline is {value!r}{unit}, but a captured latency quantile "
-            f"is strictly positive and finite. A zero baseline leaves the "
-            f"percentage bound undefined, a negative one inverts it, and neither "
-            f"can bracket to a bucket -- so no rule below can be evaluated. "
-            f"Recapture the baseline from a CI run rather than editing it by hand "
-            f"-- see baselines/README.md"
-        )
-    return None
-
-
-def check_key(key, entry, thresholds, ladders):
-    """Apply rules B, C, D and E to one gated key. Returns a list of failures.
-
-    The rules assume the baseline entry holds a strictly positive, finite
-    number, which is what ``histogram_quantile`` yields. Anything else is
-    malformed input, and reporting malformed input is this script's whole job,
-    so it is rejected up front rather than arithmetic being attempted on it --
-    see ``_unusable_baseline``.
-
-    The entry's SHAPE is checked first, for the same reason. A hand edit that
-    writes the bare number instead of the ``{"value": .., "unit": ..}`` object
-    leaves no ``.get`` to call, and the script died with an AttributeError
-    traceback naming a line in itself rather than the key at fault.
-    """
-    if not isinstance(entry, dict):
-        return [
-            f"{key}: baseline entry {entry!r} is not an object carrying value and "
-            f"unit, so no bound can be derived from it. Recapture the baseline "
-            f"from a CI run rather than editing it by hand -- see "
-            f"baselines/README.md"
-        ]
-
-    value, unit = entry.get("value"), entry.get("unit", "")
-    edges = ladders.get(unit)
-    if value is None or edges is None:
-        return [f"{key}: baseline has no value, or unknown unit {unit!r}"]
-
-    unusable = _unusable_baseline(key, value, unit)
-    if unusable:
-        return [unusable]
-
-    failures = []
-    first_edge = edges[0]
-    quantile = int(key.rsplit(".p", 1)[1]) / 100.0
-    if abs(value - quantile * first_edge) <= 1e-9 * first_edge:
-        failures.append(
-            f"{key}: baseline {value!r} equals quantile {quantile:g} x the ladder "
-            f"floor {first_edge:g}{unit}, so every sample landed in the first "
-            f"bucket and this is bucket arithmetic, not a latency. No absolute "
-            f"bound can gate it -- add a finer ladder edge or drop the metric "
-            f"from {METRICS} (rule E)"
-        )
-        return failures
-
-    _, _, hi_next = brackets(value, edges)
-    if hi_next is None:
-        return [
-            f"{key}: baseline {value!r}{unit} sits in or above the ladder's top "
-            f"bucket, so there is no hi_next to derive a bound from -- extend the "
-            f"ladder (rule C)"
-        ]
-
-    rule = resolve_override(key, thresholds)
-    if rule is None:
-        failures.append(
-            f"{key}: no per-metric override, so it falls back to the defaults and "
-            f"gates on the percentage bound alone. Add an override in "
-            f"{THRESHOLDS} with "
-            f"max_abs_increase_{unit} = {hi_next - value!r} (rule B)"
-        )
-        return failures
-
-    if not isinstance(rule, dict):
-        return [
-            f"{key}: threshold override {rule!r} is not an object carrying "
-            f"max_abs_increase_{unit} and max_pct_increase -- fix it in {THRESHOLDS}"
-        ]
-
-    bound = rule.get("max_abs_increase_ms", rule.get("max_abs_increase_us"))
-    if bound is not None and not is_number(bound):
-        return [
-            f"{key}: max_abs_increase_{unit} is {bound!r}, not a number, so it "
-            f"cannot be compared with the derived bound -- fix it in {THRESHOLDS}"
-        ]
-    expected = hi_next - value
-    if bound is None or abs(bound - expected) > REL_TOLERANCE * expected:
-        failures.append(
-            f"{key}: absolute bound is {bound!r}, expected {expected!r} "
-            f"(hi_next {hi_next:g} - baseline {value!r}) (rule C)"
-        )
-
-    pct = rule.get("max_pct_increase")
-    if pct is None:
-        failures.append(f"{key}: no max_pct_increase, so the metric never gates")
-    elif not is_number(pct):
-        failures.append(
-            f"{key}: max_pct_increase is {pct!r}, not a number -- fix it in "
-            f"{THRESHOLDS}"
-        )
-    elif bound is not None and pct >= 100.0 * bound / value:
-        failures.append(
-            f"{key}: max_pct_increase {pct:g}% is at or above the absolute bound's "
-            f"{100.0 * bound / value:.1f}% of baseline, so the percentage bound "
-            f"becomes the operative one and the bucket guarantee is lost. Lower it "
-            f"or document the metric as percentage-gated (rule D)"
-        )
-    return failures
-
-
-def main():
-    missing = [
-        p for p in (BASELINE, THRESHOLDS, METRICS, COLLECTOR, HEADER) if not p.exists()
-    ]
-    if missing:
-        print("Cannot check workload regression bounds.", file=sys.stderr)
-        for path in missing:
-            print(f"  {path}: required input is absent", file=sys.stderr)
-        print(
-            "\nA missing input is not a reason to pass. Deleting or renaming one of\n"
-            "these would otherwise leave the gate reporting success without having\n"
-            "checked a single bound -- the failure this script exists to prevent. If\n"
-            "the workload harness has genuinely moved, update the paths here.",
-            file=sys.stderr,
-        )
-        return 1
-
-    baseline = read_json_or_exit(BASELINE)
-    thresholds = read_json_or_exit(THRESHOLDS)
-    metrics_cfg = read_json_or_exit(METRICS)
-
-    if baseline.get("placeholder") is True or not baseline.get("metrics"):
-        print("OK: baseline is a placeholder, bounds cannot be derived yet")
-        return 0
-
-    ladders = {"ms": span_edges_ms(), "us": microsecond_edges()}
-    gated = baseline["metrics"]
-    # A list or a string is truthy, so it survives the placeholder test above
-    # and then either crashes or reports its characters as gated keys.
-    if not isinstance(gated, dict):
-        sys.exit(
-            f"{BASELINE}: 'metrics' is {type(gated).__name__}, not an object of "
-            f"key -> {{value, unit}} -- recapture the baseline from a CI run"
-        )
-    failures = []
-
-    declared = declared_keys(metrics_cfg)
-    failures.extend(check_exclusions(metrics_cfg, thresholds, gated, declared))
-    # Rule A compares against the GATED surface, so a deliberately excluded
-    # quantile is not reported as a baseline that was never captured.
-    #
-    # The same keys come off rule A's over-coverage side too. An excluded key
-    # left in the baseline is rule F's finding, reported with the file to edit;
-    # rule A would add a second failure for the same single mistake, saying the
-    # key is not declared -- which is not even true, it is declared and then
-    # excluded. Only exclusions the surface really declares are subtracted, so a
-    # misspelt exclusion naming a stale baseline key still reaches rule A.
-    excluded_declared = set(metrics_cfg.get("excluded_keys", {})) & declared
-    declared -= excluded_declared
-    for key in sorted(set(gated) - declared - excluded_declared):
-        failures.append(
-            f"{key}: in the baseline but not declared by {METRICS}, so it is "
-            f"reported every run and can never gate -- remove it (rule A)"
-        )
-    for key in sorted(declared - set(gated)):
-        failures.append(
-            f"{key}: declared by {METRICS} but absent from the baseline, so it "
-            f"never gates -- capture a baseline for it (rule A)"
-        )
-
-    for key in sorted(gated):
-        if key in declared:
-            failures.extend(check_key(key, gated[key], thresholds, ladders))
-
-    if not failures:
-        excluded = metrics_cfg.get("excluded_keys", {})
-        print(
-            f"OK: {len(gated)} gated key(s); every absolute bound equals "
-            f"hi_next - baseline, every key has an override, and the absolute "
-            f"bound is the operative half of the AND for all of them"
-        )
-        # Printed, not silent: an exclusion narrows the gate, so the count
-        # belongs in the CI log where a reviewer sees it without opening a file.
-        if excluded:
-            print(
-                f"    {len(excluded)} declared key(s) deliberately not gated: "
-                f"{', '.join(sorted(excluded))} (see excluded_keys in {METRICS})"
-            )
-        return 0
-
-    print(
-        "Workload regression bounds are not derived from the baseline.", file=sys.stderr
-    )
-    for failure in failures:
-        print(f"  {failure}", file=sys.stderr)
-    print(
-        f"\nThe rule is recorded in {THRESHOLDS} under _absolute_bound_derivation:\n"
-        "a bound is hi_next - baseline, where hi_next is the edge above the top of\n"
-        "the bucket holding the baseline. Refreshing a baseline therefore obliges\n"
-        "you to re-derive its bound; see baselines/README.md.",
-        file=sys.stderr,
-    )
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/scripts/telemetry/test_check_regression_bounds.py

@@ -1,462 +0,0 @@
-#!/usr/bin/env python3
-"""Tests for check_regression_bounds.py.
-
-The checker reads five files by path relative to the working directory, so each
-test assembles a scratch tree holding copies of the real inputs, mutates one
-thing, and runs the checker as a subprocess there. Testing the real entry point
-is deliberate: the contract under test is the exit code CI reads, and an
-in-process call would not exercise it.
-
-Two groups:
-
-* the input-handling contract -- a placeholder baseline must PASS because that
-  is the documented bootstrap state, while a missing, unreadable or malformed
-  input must FAIL. A checker that returns success without having checked
-  anything is the failure this whole gate exists to prevent;
-* one case per rule (A to F), so a rule that stops flagging is caught.
-
-stdlib unittest only; the repo installs no third-party runner for CI.
-"""
-
-import json
-import os
-import shutil
-import stat
-import subprocess
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-SCRIPT_DIR = Path(__file__).resolve().parent
-CHECKER = SCRIPT_DIR / "check_regression_bounds.py"
-REPO = SCRIPT_DIR.parents[2]
-
-WORKLOAD = "docker/telemetry/workload"
-BASELINE = f"{WORKLOAD}/baselines/baseline-timings.json"
-THRESHOLDS = f"{WORKLOAD}/regression-thresholds.json"
-METRICS = f"{WORKLOAD}/regression-metrics.json"
-COLLECTOR = "docker/telemetry/otel-collector-config.yaml"
-HEADER = "include/xrpl/telemetry/HistogramBuckets.h"
-INPUTS = (BASELINE, THRESHOLDS, METRICS, COLLECTOR, HEADER)
-
-
-class CheckerCase(unittest.TestCase):
-    """Base class giving each test an isolated copy of the checker's inputs."""
-
-    def setUp(self):
-        self.tree = Path(tempfile.mkdtemp())
-        # Bound to THIS tree, not read off self.tree when the cleanup finally
-        # runs. A test that calls setUp again for a fresh tree (see the
-        # degenerate-baseline subTests) rebinds self.tree, and a late read would
-        # make every registered cleanup remove the LAST tree, leaving each
-        # earlier one behind in /tmp.
-        self.addCleanup(self._cleanup, self.tree)
-        for rel in INPUTS:
-            dest = self.tree / rel
-            dest.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copy(REPO / rel, dest)
-        script = self.tree / ".github/scripts/telemetry/check_regression_bounds.py"
-        script.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copy(CHECKER, script)
-
-    def _cleanup(self, tree):
-        """Remove one scratch tree, restoring permissions rmtree needs first."""
-        for path in tree.rglob("*"):
-            if path.is_file():
-                path.chmod(stat.S_IRUSR | stat.S_IWUSR)
-        shutil.rmtree(tree, ignore_errors=True)
-
-    def run_checker(self):
-        """Run the checker in the scratch tree, returning (code, stdout+stderr)."""
-        proc = subprocess.run(
-            [sys.executable, ".github/scripts/telemetry/check_regression_bounds.py"],
-            cwd=self.tree,
-            capture_output=True,
-            text=True,
-        )
-        return proc.returncode, proc.stdout + proc.stderr
-
-    def edit_json(self, rel, mutate):
-        """Load a scratch input, hand it to mutate(), write it back."""
-        path = self.tree / rel
-        data = json.loads(path.read_text())
-        mutate(data)
-        path.write_text(json.dumps(data, indent=2))
-
-    def read_json(self, rel):
-        """Read a scratch input without modifying it."""
-        return json.loads((self.tree / rel).read_text())
-
-    def gated(self, key):
-        """Return ``(baseline_value, configured_bound)`` for one gated key.
-
-        Read from the scratch copies of the real inputs rather than written as
-        literals, because a literal here is a copy of one particular baseline:
-        a hard-coded figure breaks the moment the baseline is refreshed, which is
-        the very drift check_regression_bounds.py exists to catch. Deriving the
-        figure keeps the assertion pinned to the rule instead of to a snapshot.
-        """
-        group, quantile = key.rsplit(".", 1)
-        rule = self.read_json(THRESHOLDS)["overrides"][group][quantile]
-        bound = rule.get("max_abs_increase_ms", rule.get("max_abs_increase_us"))
-        return self.read_json(BASELINE)["metrics"][key]["value"], bound
-
-
-class TestInputHandling(CheckerCase):
-    """A placeholder passes; a missing or broken input must not."""
-
-    def test_unmodified_tree_passes(self):
-        code, out = self.run_checker()
-        self.assertEqual(code, 0, out)
-        self.assertIn("gated key(s)", out)
-
-    def test_placeholder_flag_passes(self):
-        self.edit_json(BASELINE, lambda d: d.update(placeholder=True))
-        code, out = self.run_checker()
-        self.assertEqual(code, 0, out)
-        self.assertIn("placeholder", out)
-
-    def test_empty_metrics_baseline_passes(self):
-        self.edit_json(BASELINE, lambda d: d.update(metrics={}))
-        code, out = self.run_checker()
-        self.assertEqual(code, 0, out)
-        self.assertIn("placeholder", out)
-
-    def test_missing_baseline_fails_naming_the_input(self):
-        (self.tree / BASELINE).unlink()
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("baseline-timings.json", out)
-
-    def test_missing_collector_config_fails_naming_the_input(self):
-        (self.tree / COLLECTOR).unlink()
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("otel-collector-config.yaml", out)
-
-    @unittest.skipIf(os.geteuid() == 0, "root ignores the read permission bit")
-    def test_unreadable_baseline_fails(self):
-        (self.tree / BASELINE).chmod(0)
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("baseline-timings.json", out)
-        self.assertIn("could not be read", out)
-        self.assertNotIn("Traceback", out)
-
-    def test_malformed_baseline_json_fails(self):
-        (self.tree / BASELINE).write_text("{ not json")
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("valid JSON", out)
-
-    def test_malformed_thresholds_json_fails(self):
-        (self.tree / THRESHOLDS).write_text("]")
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("valid JSON", out)
-
-    def test_non_object_top_level_fails_naming_the_input(self):
-        """Valid JSON of the wrong shape must be named, not raise a traceback.
-
-        A top-level null, list or number parses, so it reaches the first .get
-        and dies pointing at a line in the checker rather than at the file the
-        operator has to fix.
-        """
-        for rel, text in (
-            (BASELINE, "null"),
-            (THRESHOLDS, "[]"),
-            (METRICS, "5"),
-        ):
-            with self.subTest(input=rel):
-                self.setUp()
-                (self.tree / rel).write_text(text)
-                code, out = self.run_checker()
-                self.assertEqual(code, 1, out)
-                self.assertIn(rel, out)
-                self.assertIn("not an object", out)
-                self.assertNotIn("Traceback", out)
-
-    def test_non_object_metrics_map_fails_naming_the_input(self):
-        """A string 'metrics' is truthy, so it slips past the placeholder test.
-
-        Left unchecked it reports the string's own characters as gated keys,
-        which is worse than a crash: the advice is wrong rather than absent.
-        An empty map still has to pass, because that is the bootstrap state.
-        """
-        self.edit_json(BASELINE, lambda d: d.update(metrics="span.tx.process.p99"))
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("'metrics' is str", out)
-        self.assertNotIn("Traceback", out)
-
-        self.setUp()
-        self.edit_json(BASELINE, lambda d: d.update(metrics={}))
-        code, out = self.run_checker()
-        self.assertEqual(code, 0, out)
-
-
-class TestRules(CheckerCase):
-    """One case per rule, so a rule that stops flagging is caught."""
-
-    def test_rule_a_flags_baseline_key_not_declared(self):
-        self.edit_json(
-            BASELINE,
-            lambda d: d["metrics"].update(
-                {"span.rpc.process.p99": {"unit": "ms", "value": 9.0}}
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule A)", out)
-
-    def test_rule_a_flags_declared_key_without_baseline(self):
-        self.edit_json(METRICS, lambda d: d["spans"]["names"].append("consensus.round"))
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule A)", out)
-
-    def test_rule_b_flags_missing_override(self):
-        self.edit_json(THRESHOLDS, lambda d: d["overrides"].pop("span.ledger.build"))
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule B)", out)
-
-    def test_rule_b_names_the_unit_suffixed_key(self):
-        """The key it tells the operator to add must be the key the code reads.
-
-        The bound is stored as max_abs_increase_ms or _us. A message naming a
-        bare max_abs_increase sends the operator to add a key nothing reads, so
-        the gate keeps failing with no explanation. Both suffixes are covered,
-        because a test on the ms side alone passes on a hard-coded "_ms".
-        """
-        for group, suffix in (
-            ("span.ledger.build", "max_abs_increase_ms"),
-            ("job.transaction.queued", "max_abs_increase_us"),
-        ):
-            with self.subTest(group=group):
-                self.setUp()
-                self.edit_json(THRESHOLDS, lambda d: d["overrides"].pop(group))
-                code, out = self.run_checker()
-                self.assertEqual(code, 1, out)
-                self.assertIn("(rule B)", out)
-                self.assertIn(suffix, out)
-                self.assertNotIn("max_abs_increase =", out)
-
-    def test_non_numeric_threshold_is_reported_not_crashed(self):
-        """A hand-edited bound that is a string must be named, not raise."""
-        self.edit_json(
-            THRESHOLDS,
-            lambda d: d["overrides"]["span.ledger.build"]["p95"].update(
-                max_abs_increase_ms="5.5"
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("not a number", out)
-        self.assertNotIn("Traceback", out)
-
-    def test_rule_c_flags_rounded_bound(self):
-        """A bound rounded for readability is still not the derived bound."""
-        _, exact = self.gated("span.tx.process.p99")
-        rounded = round(exact, 4)
-        self.assertNotEqual(rounded, exact, "pick a key whose bound rounds visibly")
-        self.edit_json(
-            THRESHOLDS,
-            lambda d: d["overrides"]["span.tx.process"]["p99"].update(
-                max_abs_increase_ms=rounded
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule C)", out)
-
-    def test_rule_c_accepts_bound_within_relative_tolerance(self):
-        """The tolerance is 1e-12 relative, not exact equality."""
-        _, exact = self.gated("span.tx.process.p99")
-        self.edit_json(
-            THRESHOLDS,
-            lambda d: d["overrides"]["span.tx.process"]["p99"].update(
-                max_abs_increase_ms=exact * (1 + 5e-13)
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 0, out)
-
-    def test_rule_d_flags_percentage_bound_becoming_operative(self):
-        """Rule D trips at exactly 100 x bound / baseline, its ``>=`` boundary."""
-        baseline, bound = self.gated("span.tx.apply.p99")
-        boundary = 100.0 * bound / baseline
-        self.edit_json(
-            THRESHOLDS,
-            lambda d: d["overrides"]["span.tx.apply"]["p99"].update(
-                max_pct_increase=boundary
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule D)", out)
-
-    def test_rule_d_accepts_percentage_bound_just_below_the_boundary(self):
-        """The other side of rule D's boundary, so the test cannot pass vacuously."""
-        baseline, bound = self.gated("span.tx.apply.p99")
-        boundary = 100.0 * bound / baseline
-        self.edit_json(
-            THRESHOLDS,
-            lambda d: d["overrides"]["span.tx.apply"]["p99"].update(
-                max_pct_increase=boundary * (1 - 1e-9)
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 0, out)
-
-    def test_rule_a_ignores_an_excluded_key(self):
-        """An excluded key must not read as a baseline that was never captured.
-
-        The unmodified tree already exercises this — span.ledger.validate p95
-        and p99 are declared by the names x quantiles product, excluded, and
-        absent from the baseline — so this asserts the subtraction is what makes
-        it pass, by naming the keys in the reported exclusion line.
-        """
-        code, out = self.run_checker()
-        self.assertEqual(code, 0, out)
-        self.assertIn("span.ledger.validate.p95", out)
-        self.assertIn("deliberately not gated", out)
-
-    def test_rule_f_flags_exclusion_that_subtracts_nothing(self):
-        """A misspelt or stale exclusion silently narrows nothing — catch it."""
-        self.edit_json(
-            METRICS,
-            lambda d: d["excluded_keys"].update({"span.ledger.validate.p97": "typo"}),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule F)", out)
-        self.assertIn("subtracts nothing", out)
-
-    def test_rule_f_flags_exclusion_without_a_reason(self):
-        self.edit_json(
-            METRICS,
-            lambda d: d["excluded_keys"].update({"span.ledger.validate.p95": "   "}),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule F)", out)
-        self.assertIn("no reason", out)
-
-    def test_rule_f_flags_override_left_behind(self):
-        """An excluded key still carrying a bound reads as gated."""
-        self.edit_json(
-            THRESHOLDS,
-            lambda d: d["overrides"]["span.ledger.validate"].update(
-                {"p95": {"max_pct_increase": 50.0, "max_abs_increase_ms": 0.25}}
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule F)", out)
-        self.assertIn("still has a threshold override", out)
-
-    def test_rule_f_flags_baseline_value_left_behind(self):
-        """Excluded but still in the baseline: rule A passes, nothing gates."""
-        self.edit_json(
-            BASELINE,
-            lambda d: d["metrics"].update(
-                {"span.ledger.validate.p95": {"unit": "ms", "value": 0.24}}
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule F)", out)
-        self.assertIn("still has a baseline value", out)
-
-    # A key that is GATED, so seeding it exercises the numeric guard rather than
-    # rule F. It must not be one of the excluded keys: putting a value there
-    # trips "excluded but still has a baseline value" first and the test would
-    # pass for the wrong reason.
-    DEGENERATE_KEY = "span.tx.process.p50"
-
-    def _seed_degenerate_baseline(self, value):
-        """Replace one gated key's baseline value with an unusable one.
-
-        The threshold is deliberately left alone. The numeric guard runs before
-        every rule, so no bound arrangement is needed to reach it -- and on the
-        pre-fix checker this same seeding still reached the crash, because rule C
-        appends its failure and falls through to rule D's division.
-        """
-        key = self.DEGENERATE_KEY
-        self.assertNotIn(
-            key,
-            self.read_json(METRICS).get("excluded_keys", {}),
-            "DEGENERATE_KEY must be gated, not excluded",
-        )
-        self.edit_json(
-            BASELINE,
-            lambda d: d["metrics"].update({key: {"unit": "ms", "value": value}}),
-        )
-
-    def test_degenerate_baseline_is_reported_not_crashed(self):
-        """A zero, negative or non-numeric baseline must NAME the key, not raise.
-
-        Rule D computes ``100 * bound / value``, so a 0.0 baseline used to exit
-        via ZeroDivisionError and a traceback, and a negative one used to emit a
-        rule-D failure blaming ``max_pct_increase`` when the fault was the
-        baseline. Rule E does not cover the zero case: its test reduces to
-        ``quantile <= 1e-9`` there, false for every quantile captured.
-        """
-        # Asserting the guard's OWN wording, not merely "exit 1 with no
-        # traceback": the negative and bool cases already exited 1 without a
-        # traceback before the fix, by emitting a rule-D failure that blamed the
-        # wrong file. A looser assertion passes on that and proves nothing.
-        cases = (
-            (0.0, "strictly positive"),
-            (-1.0, "strictly positive"),
-            (float("nan"), "strictly positive"),
-            (float("inf"), "strictly positive"),
-            ("0.006", "is not a number"),
-            (True, "is not a number"),
-        )
-        for value, expected in cases:
-            with self.subTest(value=value):
-                self.setUp()  # a clean scratch tree per value
-                self._seed_degenerate_baseline(value)
-                code, out = self.run_checker()
-                self.assertEqual(code, 1, out)
-                self.assertNotIn("Traceback", out)
-                self.assertIn(self.DEGENERATE_KEY, out)
-                self.assertIn(expected, out)
-                # The old rule-D message told the maintainer to lower the
-                # percentage bound; the baseline is what is wrong.
-                self.assertNotIn("(rule D)", out)
-
-    def test_rule_e_flags_ladder_floor_signature(self):
-        """ledger.store's quantiles were the ladder floor times the quantile."""
-        store = {"p50": 0.005, "p95": 0.0095, "p99": 0.0099}
-        self.edit_json(METRICS, lambda d: d["spans"]["names"].append("ledger.store"))
-        self.edit_json(
-            BASELINE,
-            lambda d: d["metrics"].update(
-                {
-                    f"span.ledger.store.{q}": {"unit": "ms", "value": v}
-                    for q, v in store.items()
-                }
-            ),
-        )
-        self.edit_json(
-            THRESHOLDS,
-            lambda d: d["overrides"].update(
-                {
-                    "span.ledger.store": {
-                        q: {"max_pct_increase": 50.0, "max_abs_increase_ms": 0.05 - v}
-                        for q, v in store.items()
-                    }
-                }
-            ),
-        )
-        code, out = self.run_checker()
-        self.assertEqual(code, 1, out)
-        self.assertIn("(rule E)", out)
-
-
-if __name__ == "__main__":
-    unittest.main()

.github/workflows/build-nix-images.yml

@@ -5,13 +5,14 @@ on:
     branches:
       - develop
     paths:
+      - ".github/workflows/build-nix-images.yml"
       - "flake.nix"
       - "flake.lock"
       - "rust-toolchain.toml"
       - "nix/**"
       - "!nix/docker/README.md"
       - "!nix/devshell.nix"
-      - "!nix/check-tools/**"
+      - "bin/check-tools.sh"
       - "bin/default-loader-path.sh"
       - "bin/install-sanitizer-libs.sh"
   pull_request:
@@ -23,7 +24,6 @@ on:
       - "nix/**"
       - "!nix/docker/README.md"
       - "!nix/devshell.nix"
-      - "!nix/check-tools/**"
       - "bin/check-tools.sh"
       - "bin/default-loader-path.sh"
       - "bin/install-sanitizer-libs.sh"
@@ -58,7 +58,7 @@ jobs:
             base_image: debian:bookworm
           - name: rhel
             base_image: registry.access.redhat.com/ubi9/ubi:latest
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@034e87065fcd0100214cf0672923bd38d193cf78
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/nix-${{ matrix.distro.name }}
       dockerfile: nix/docker/Dockerfile

.github/workflows/build-packaging-images.yml

@@ -6,13 +6,13 @@ on:
       - develop
     paths:
       - ".github/workflows/build-packaging-images.yml"
-      - "bin/install-packaging-tools.sh"
-      - "package/docker/**"
+      - "package/Dockerfile"
+      - "package/install-packaging-tools.sh"
   pull_request:
     paths:
       - ".github/workflows/build-packaging-images.yml"
-      - "bin/install-packaging-tools.sh"
-      - "package/docker/**"
+      - "package/Dockerfile"
+      - "package/install-packaging-tools.sh"
   workflow_dispatch:
 
 concurrency:
@@ -33,17 +33,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Newest of each distro: these images only wrap pre-built binaries, so
-        # they set no floor for consumers. build_pkg.py pins the RPM dist tag.
         distro:
           - name: debian
-            base_image: debian:trixie
-          # AlmaLinux rather than UBI, which does not ship rpm-sign.
+            base_image: debian:bookworm
           - name: rhel
-            base_image: almalinux:10
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@034e87065fcd0100214cf0672923bd38d193cf78
+            base_image: registry.access.redhat.com/ubi9/ubi:latest
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/packaging-${{ matrix.distro.name }}
-      dockerfile: package/docker/Dockerfile
+      dockerfile: package/Dockerfile
       base_image: ${{ matrix.distro.base_image }}
       push: ${{ github.event_name == 'push' }}

.github/workflows/build-pre-commit-image.yml

@@ -30,7 +30,7 @@ jobs:
     permissions:
       contents: read
       packages: write
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@034e87065fcd0100214cf0672923bd38d193cf78
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/pre-commit
       dockerfile: bin/pre-commit/Dockerfile

.github/workflows/cargo-audit.yml

@@ -1,80 +0,0 @@
-name: Cargo audit
-
-on:
-  schedule:
-    # 06:32 UTC every Monday.
-    - cron: "32 6 * * 1"
-  push:
-    branches:
-      - "develop"
-      - "release/*"
-    paths:
-      - "crates/**/Cargo.toml"
-      - "crates/Cargo.lock"
-      - ".github/workflows/cargo-audit.yml"
-  pull_request:
-    paths:
-      - "crates/**/Cargo.toml"
-      - "crates/Cargo.lock"
-      - ".github/workflows/cargo-audit.yml"
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-    working-directory: crates
-
-permissions:
-  contents: read
-
-jobs:
-  audit:
-    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
-    permissions:
-      contents: read
-      # Needed to open an issue on scheduled failures.
-      issues: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Run cargo audit
-        id: audit
-        continue-on-error: true
-        run: |
-          set -o pipefail
-          cargo audit | tee /tmp/cargo-audit.txt
-
-      - name: Prepare issue body
-        if: ${{ steps.audit.outcome != 'success' && github.event_name == 'schedule' }}
-        run: |
-          {
-              echo "## \`cargo audit\` found advisories"
-              echo
-              echo '```'
-              cat /tmp/cargo-audit.txt
-              echo '```'
-              echo
-              echo "---"
-              echo "*This issue was automatically created by the cargo-audit workflow.*"
-          } >/tmp/cargo-audit-issue.md
-
-      - name: Create issue
-        if: ${{ steps.audit.outcome != 'success' && github.event_name == 'schedule' }}
-        uses: XRPLF/actions/create-issue@2b8bc36af85b88bca0dd7bfac2e2dc05f94ad712
-        with:
-          title: "cargo audit found vulnerabilities"
-          body_file: /tmp/cargo-audit-issue.md
-          labels: "Bug,Security"
-
-      - name: Fail if advisories were found
-        if: ${{ steps.audit.outcome != 'success' }}
-        run: |
-          echo "cargo audit found advisories!"
-          cat /tmp/cargo-audit.txt
-          exit 1

.github/workflows/check-tools.yml

@@ -79,7 +79,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 

.github/workflows/on-pr.yml

@@ -70,49 +70,30 @@ jobs:
           files: |
             # These paths are unique to `on-pr.yml`.
             .github/scripts/levelization/**
-            .github/scripts/otel-naming/**
             .github/scripts/rename/**
-            .github/scripts/telemetry/**
             .github/workflows/reusable-check-levelization.yml
-            .github/workflows/reusable-check-otel-naming.yml
             .github/workflows/reusable-check-rename.yml
             .github/workflows/on-pr.yml
 
-            # The non-code layers the OTel naming check validates: the docs that
-            # publish attribute tables (Rule E) and the telemetry stack config —
-            # collector, Tempo, dashboards (Rules B, C, D). Without these paths a
-            # docs-only or dashboard-only pull request sets `go=false`, so the
-            # very layers those rules exist to police would never be checked.
-            # As with `README.md` below, matching one of these also switches on
-            # the rest of the workflow; there is a single `go` gate.
-            docs/**
-            docker/telemetry/**
-
             # Keep the paths below in sync with those in `on-trigger.yml`.
             .github/actions/build-deps/**
-            .github/actions/release-info/**
+            .github/actions/generate-version/**
             .github/actions/setup-conan/**
-            .github/actions/setup-nix-env/**
             .github/scripts/strategy-matrix/**
             .github/workflows/reusable-build-test-config.yml
             .github/workflows/reusable-build-test.yml
-            .github/workflows/reusable-check-autogen.yml
             .github/workflows/reusable-clang-tidy.yml
-            .github/workflows/reusable-package-test-install.yml
             .github/workflows/reusable-package.yml
-            .github/workflows/reusable-rust.yml
             .github/workflows/reusable-strategy-matrix.yml
             .github/workflows/reusable-test.yml
             .github/workflows/reusable-upload-recipe.yml
             .clang-tidy
             .codecov.yml
-            bin/check-nix-store-refs.sh
             bin/check-tools.sh
             bin/default-loader-path.sh
             cfg/**
             cmake/**
             conan/**
-            crates/**
             external/**
             include/**
             src/**
@@ -120,67 +101,10 @@ jobs:
             CMakeLists.txt
             conanfile.py
             conan.lock
-            flake.lock
-            flake.nix
-            nix/**
             LICENSE.md
             package/**
             README.md
 
-      - name: Determine changed telemetry files
-        # A separate list from the one above, because the telemetry validation
-        # builds xrpld on the self-hosted runner and then runs a multi-node
-        # cluster for up to 30 minutes. The `go` gate above is true for almost
-        # any pull request, so gating this one on `go` alone would run that cost
-        # on every pull request in the repository.
-        #
-        # Keep these globs pointing at paths that exist -- two earlier entries
-        # matched zero tracked files, so C++ telemetry changes never triggered.
-        id: telemetry-changes
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            # This workflow, the one it calls, and the harness that runs.
-            .github/workflows/on-pr.yml
-            .github/workflows/reusable-telemetry-validation.yml
-            docker/telemetry/**
-
-            # The telemetry modules themselves.
-            include/xrpl/telemetry/**
-            src/libxrpl/telemetry/**
-            src/xrpld/telemetry/**
-
-            # beast::insight, whose gauges and counters the validation asserts
-            # on. Both halves: the interface headers decide what the OTel
-            # collector can publish, so editing one moves the metric surface as
-            # surely as editing the implementation does.
-            include/xrpl/beast/insight/**
-            src/libxrpl/beast/insight/**
-
-            # The span-name and metric-name constants. These are the wire
-            # contract the harness asserts against by literal string, so a
-            # rename here compiles cleanly and silently empties the assertions.
-            # Matched by filename rather than directory because the convention
-            # colocates each header with the class it serves: they live under
-            # consensus/, overlay/, app/ledger/, app/main/, app/misc/, rpc/ and
-            # tx/, not under a telemetry/ directory.
-            **/*SpanNames.h
-            **/*MetricNames.h
-
-            # The GTests that pin those same constants.
-            src/tests/libxrpl/telemetry/**
-
-            # The checkers that gate this surface. otel-naming derives the legal
-            # attribute and metric names from the headers above; the telemetry
-            # scripts enforce the histogram-bucket parity and regression-bound
-            # rules the harness depends on.
-            .github/scripts/otel-naming/**
-            .github/scripts/telemetry/**
-
-            # The recipe, because it carries the telemetry option this decides
-            # the validation on.
-            conanfile.py
-
       - name: Check whether to run
         # This step determines whether the rest of the workflow should
         # run. The rest of the workflow will run if this job runs AND at
@@ -201,23 +125,12 @@ jobs:
           cat "${GITHUB_OUTPUT}"
     outputs:
       go: ${{ steps.go.outputs.go == 'true' }}
-      telemetry_changed: ${{ steps.telemetry-changes.outputs.any_changed == 'true' }}
-
-  check-autogen:
-    needs: should-run
-    if: ${{ needs.should-run.outputs.go == 'true' }}
-    uses: ./.github/workflows/reusable-check-autogen.yml
 
   check-levelization:
     needs: should-run
     if: ${{ needs.should-run.outputs.go == 'true' }}
     uses: ./.github/workflows/reusable-check-levelization.yml
 
-  check-otel-naming:
-    needs: should-run
-    if: ${{ needs.should-run.outputs.go == 'true' }}
-    uses: ./.github/workflows/reusable-check-otel-naming.yml
-
   check-rename:
     needs: should-run
     if: ${{ needs.should-run.outputs.go == 'true' }}
@@ -249,13 +162,6 @@ jobs:
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-  rust:
-    needs: should-run
-    if: ${{ needs.should-run.outputs.go == 'true' }}
-    uses: ./.github/workflows/reusable-rust.yml
-    secrets:
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
   package:
     needs: [should-run, build-test]
     # Packaging consumes the debian/rhel release binaries, which are only built
@@ -263,12 +169,6 @@ jobs:
     # matrix (i.e. not yet labeled "Ready to merge" or "Full CI build").
     if: ${{ needs.should-run.outputs.go == 'true' && (github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'Ready to merge') || contains(github.event.pull_request.labels.*.name, 'Full CI build')) }}
     uses: ./.github/workflows/reusable-package.yml
-    with:
-      # A pull request builds packages to prove they still build, and publishes
-      # nothing. Stated rather than left to the input's default, so that changing
-      # that default cannot start publishing from pull requests. No secrets are
-      # passed either, which is the second reason a publish here cannot succeed.
-      publish: false
 
   upload-recipe:
     needs:
@@ -281,11 +181,6 @@ jobs:
       remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
       remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
 
-  telemetry-validation:
-    needs: should-run
-    if: ${{ needs.should-run.outputs.go == 'true' && needs.should-run.outputs.telemetry_changed == 'true' }}
-    uses: ./.github/workflows/reusable-telemetry-validation.yml
-
   notify-clio:
     needs: upload-recipe
     runs-on: ubuntu-latest
@@ -305,17 +200,13 @@ jobs:
   passed:
     if: failure() || cancelled()
     needs:
-      - check-autogen
       - check-levelization
-      - check-otel-naming
       - check-rename
       - clang-tidy
       - build-test
-      - rust
       - package
       - upload-recipe
       - notify-clio
-      - telemetry-validation
     runs-on: ubuntu-latest
     steps:
       - name: Fail

.github/workflows/on-tag.yml

@@ -1,9 +1,5 @@
-# When a versioned tag is pushed, this workflow:
-#
-#   - uploads the libxrpl recipe to the Conan remote
-#   - builds and tests the release binaries
-#   - builds the DEB and RPM packages
-#   - publishes those packages to the XRPLF package repositories
+# This workflow uploads the libxrpl recipe to the Conan remote and builds
+# release packages when a versioned tag is pushed.
 name: Tag
 
 on:
@@ -28,7 +24,7 @@ jobs:
       remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
 
   build-test:
-    if: ${{ github.repository_owner == 'XRPLF' }}
+    if: ${{ github.repository == 'XRPLF/rippled' }}
     uses: ./.github/workflows/reusable-build-test.yml
     strategy:
       fail-fast: true
@@ -41,12 +37,6 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   package:
-    if: ${{ github.repository_owner == 'XRPLF' }}
+    if: ${{ github.repository == 'XRPLF/rippled' }}
     needs: build-test
     uses: ./.github/workflows/reusable-package.yml
-    with:
-      publish: true
-    secrets:
-      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
-      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}

.github/workflows/on-trigger.yml

@@ -15,29 +15,23 @@ on:
 
       # Keep the paths below in sync with those in `on-pr.yml`.
       - ".github/actions/build-deps/**"
-      - ".github/actions/release-info/**"
+      - ".github/actions/generate-version/**"
       - ".github/actions/setup-conan/**"
-      - ".github/actions/setup-nix-env/**"
       - ".github/scripts/strategy-matrix/**"
       - ".github/workflows/reusable-build-test-config.yml"
       - ".github/workflows/reusable-build-test.yml"
-      - ".github/workflows/reusable-check-autogen.yml"
       - ".github/workflows/reusable-clang-tidy.yml"
-      - ".github/workflows/reusable-package-test-install.yml"
       - ".github/workflows/reusable-package.yml"
-      - ".github/workflows/reusable-rust.yml"
       - ".github/workflows/reusable-strategy-matrix.yml"
       - ".github/workflows/reusable-test.yml"
       - ".github/workflows/reusable-upload-recipe.yml"
       - ".clang-tidy"
       - ".codecov.yml"
-      - "bin/check-nix-store-refs.sh"
       - "bin/check-tools.sh"
       - "bin/default-loader-path.sh"
       - "cfg/**"
       - "cmake/**"
       - "conan/**"
-      - "crates/**"
       - "external/**"
       - "include/**"
       - "src/**"
@@ -45,9 +39,6 @@ on:
       - "CMakeLists.txt"
       - "conanfile.py"
       - "conan.lock"
-      - "flake.lock"
-      - "flake.nix"
-      - "nix/**"
       - "LICENSE.md"
       - "package/**"
       - "README.md"
@@ -76,9 +67,6 @@ defaults:
     shell: bash
 
 jobs:
-  check-autogen:
-    uses: ./.github/workflows/reusable-check-autogen.yml
-
   clang-tidy:
     uses: ./.github/workflows/reusable-clang-tidy.yml
     permissions:
@@ -104,11 +92,6 @@ jobs:
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-  rust:
-    uses: ./.github/workflows/reusable-rust.yml
-    secrets:
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
   upload-recipe:
     needs: build-test
     # Only run when pushing to the develop branch.
@@ -121,11 +104,3 @@ jobs:
   package:
     needs: build-test
     uses: ./.github/workflows/reusable-package.yml
-    with:
-      # Packages are built on every trigger; only develop pushes in XRPLF/rippled
-      # publish them, matching upload-recipe above.
-      publish: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
-    secrets:
-      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
-      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}

.github/workflows/pre-commit.yml

@@ -14,7 +14,7 @@ on:
 jobs:
   # Call the workflow in the XRPLF/actions repo that runs the pre-commit hooks.
   run-hooks:
-    uses: XRPLF/actions/.github/workflows/pre-commit.yml@279ec358f4a1be4088be3e024b07916fa97c75b6
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@3ba08d6ddf114092891d48491fc2e26c3ba15552
     with:
       runs_on: ubuntu-latest
-      container: '{ "image": "ghcr.io/xrplf/xrpld/pre-commit:sha-473fe44" }'
+      container: '{ "image": "ghcr.io/xrplf/xrpld/pre-commit:sha-f56b79f" }'

.github/workflows/publish-docs.yml

@@ -41,13 +41,13 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 
@@ -91,4 +91,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deploy
-        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.github/workflows/reusable-build-test-config.yml

@@ -3,12 +3,6 @@ name: Build and test configuration
 on:
   workflow_call:
     inputs:
-      benchmark:
-        description: "Whether to smoke-run the benchmarks after testing."
-        required: false
-        type: boolean
-        default: false
-
       build_only:
         description: 'Whether to only build or to build and test the code ("true", "false").'
         required: true
@@ -69,12 +63,6 @@ on:
         type: string
         default: ""
 
-      toolchain:
-        description: 'Where the toolchain comes from ("nix" to build the flake CI environment on the runner, empty for the system one). macOS only: Linux always builds in a Nix image, and Nix has no Windows support.'
-        required: false
-        type: string
-        default: ""
-
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
@@ -112,14 +100,10 @@ jobs:
       # header files are copied into separate directories by CMake, which will
       # otherwise result in cache misses.
       CCACHE_SLOPPINESS: include_file_ctime,include_file_mtime
-      # Determine if coverage, voidstar and validator-keys should be enabled.
+      # Determine if coverage and voidstar should be enabled.
       COVERAGE_ENABLED: ${{ contains(inputs.cmake_args, '-Dcoverage=ON') }}
       VOIDSTAR_ENABLED: ${{ contains(inputs.cmake_args, '-Dvoidstar=ON') }}
-      VALIDATOR_KEYS_ENABLED: ${{ contains(inputs.cmake_args, '-Dvalidator_keys=ON') }}
       SANITIZERS_ENABLED: ${{ inputs.sanitizers != '' }}
-      # The binaries reusable-package.yml consumes. A private repository skips
-      # them except on a tag push, which is what produces its release packages.
-      PACKAGING_ARTIFACTS_ENABLED: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: Cleanup workspace (macOS and Windows)
         if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
@@ -129,15 +113,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: ${{ inputs.ccache_enabled }}
 
-      # Before any step that uses a build tool, composite actions included.
-      - name: Setup Nix environment
-        if: ${{ inputs.toolchain == 'nix' }}
-        uses: ./.github/actions/setup-nix-env
-
       - name: Set ccache log file
         if: ${{ inputs.ccache_enabled && runner.debug == '1' }}
         run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >>"${GITHUB_ENV}"
@@ -162,21 +141,7 @@ jobs:
         with:
           compiler: ${{ inputs.compiler }}
 
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
-        with:
-          cache-directories: ${{ env.BUILD_DIR }}/corrosion
-          key: ${{ inputs.config_name }}
-          # two workspaces here because build artifacts are located in 2 places:
-          # - crates/target when cargo is called directly
-          # - build/cargo when cargo is called by cmake
-          workspaces: |
-            crates
-            crates -> ${{ runner.os == 'Windows' && format('../{0}/x64/{1}/cargo', env.BUILD_DIR, inputs.build_type) || format('../{0}/cargo', env.BUILD_DIR) }}
-
-      # `setup-nix-env` already did this for the Nix toolchain.
       - name: Setup Conan
-        if: ${{ inputs.toolchain != 'nix' }}
         env:
           SANITIZERS: ${{ inputs.sanitizers }}
         uses: ./.github/actions/setup-conan
@@ -205,9 +170,9 @@ jobs:
               ..
 
       # Export the sanitizer options before any instrumented binary runs. The
-      # build step below invokes instrumented dependency tools (protoc, grpc),
-      # so setting UBSAN_OPTIONS here lets the UBSan suppression list silence
-      # their diagnostics too, not just at test time.
+      # protocol code-gen and build steps below invoke instrumented dependency
+      # tools (protoc, grpc), so setting UBSAN_OPTIONS here lets the UBSan
+      # suppression list silence their diagnostics too, not just at test time.
       # GITHUB_WORKSPACE (not the github.workspace context) is used so the path
       # resolves correctly inside the container job.
       - name: Set sanitizer options
@@ -225,6 +190,32 @@ jobs:
           echo "UBSAN_OPTIONS=include=${SUPP}/runtime-ubsan-options.txt:suppressions=${SUPP}/ubsan.supp" >>${GITHUB_ENV}
           echo "LSAN_OPTIONS=include=${SUPP}/runtime-lsan-options.txt:suppressions=${SUPP}/lsan.supp" >>${GITHUB_ENV}
 
+      - name: Check protocol autogen files are up-to-date
+        working-directory: ${{ env.BUILD_DIR }}
+        env:
+          MESSAGE: |
+
+            The generated protocol wrapper classes are out of date.
+
+            This typically happens when the macro files or generator scripts
+            have changed but the generated files were not regenerated.
+
+            To fix this:
+              1. Run: cmake --build . --target setup_code_gen
+              2. Run: cmake --build . --target code_gen
+              3. Commit and push the regenerated files
+        run: |
+          set -e
+          cmake --build . --target setup_code_gen
+          cmake --build . --target code_gen
+          DIFF=$(git -C .. status --porcelain -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen)
+          if [ -n "${DIFF}" ]; then
+              echo "::error::Generated protocol files are out of date"
+              git -C .. diff -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen
+              echo "${MESSAGE}"
+              exit 1
+          fi
+
       - name: Build the binary
         working-directory: ${{ env.BUILD_DIR }}
         env:
@@ -240,24 +231,6 @@ jobs:
               --target "${CMAKE_TARGET}" \
               2>&1 | tee "${GITHUB_WORKSPACE}/build.log"
 
-      # Nothing may reference the store, so whole trees are checked - the Conan
-      # cache included, since what it holds is what gets uploaded and reused.
-      - name: Check the build output for Nix store references (Nix toolchain)
-        if: ${{ inputs.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${BUILD_DIR}"
-
-      - name: Check the Conan cache for Nix store references (Nix toolchain)
-        if: ${{ inputs.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${CONAN_HOME}"
-
-      # Only what PatchNixBinary.cmake retargets: the toolchain in the Linux
-      # images always references the store. Same condition it uses.
-      - name: Check for Nix store references (Linux)
-        if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
-        run: |
-          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpld"
-          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpl_tests"
-
       - name: Show ccache statistics
         if: ${{ inputs.ccache_enabled }}
         run: |
@@ -268,7 +241,7 @@ jobs:
           fi
 
       - name: Upload the binary (Linux)
-        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && runner.os == 'Linux' }}
+        if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: xrpld-${{ inputs.config_name }}
@@ -276,22 +249,6 @@ jobs:
           retention-days: 3
           if-no-files-found: error
 
-      - name: Run the validator-keys tests
-        if: ${{ env.VALIDATOR_KEYS_ENABLED == 'true' }}
-        working-directory: ${{ env.BUILD_DIR }}
-        run: ./validator-keys --unittest
-
-      - name: Upload the validator-keys binary
-        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && env.VALIDATOR_KEYS_ENABLED == 'true' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: validator-keys-${{ inputs.config_name }}
-          path: |
-            ${{ env.BUILD_DIR }}/validator-keys
-            ${{ env.BUILD_DIR }}/validator-keys-LICENSE
-          retention-days: 3
-          if-no-files-found: error
-
       - name: Upload the test binary (Linux)
         if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -369,21 +326,13 @@ jobs:
 
           LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee "${GITHUB_WORKSPACE}/unittest.log"
 
-      - name: Run Rust tests
-        if: ${{ !inputs.build_only }}
-        working-directory: crates
-        run: cargo nextest run --workspace --all-features --locked --no-tests=warn
-
       # Smoke-run every benchmark module with a single repetition to confirm the
       # benchmarks still build and execute. This is a correctness check, not a
-      # performance measurement, so there is nothing to gain from repeating it
-      # across configurations: it is opted into by a single config in the
-      # strategy matrix (see the 'benchmark' flag in the JSON files), which
-      # keeps it off instrumented builds (sanitizers/coverage/voidstar), where
-      # it would be slow and meaningless, off Debug builds, where it is much
-      # slower, and off Windows, where the `install` target does not build them.
+      # performance measurement, so it is skipped for instrumented builds
+      # (sanitizers/coverage/voidstar), where it would be slow and meaningless,
+      # and on Windows, where the `install` target does not build them.
       - name: Run the benchmarks
-        if: ${{ inputs.benchmark }}
+        if: ${{ !inputs.build_only && runner.os != 'Windows' && env.SANITIZERS_ENABLED == 'false' && env.COVERAGE_ENABLED != 'true' && env.VOIDSTAR_ENABLED != 'true' }}
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           rc=0
@@ -438,14 +387,13 @@ jobs:
               --target coverage
 
       - name: Upload coverage report
-        if: ${{ github.repository_owner == 'XRPLF' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
-        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        if: ${{ github.repository == 'XRPLF/rippled' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           disable_search: true
           disable_telem: true
           fail_ci_if_error: true
           files: ${{ env.BUILD_DIR }}/coverage.xml
-          flags: cpp
           plugins: noop
           token: ${{ secrets.CODECOV_TOKEN }}
           verbose: true

.github/workflows/reusable-build-test.yml

@@ -40,7 +40,6 @@ jobs:
       fail-fast: ${{ github.event_name == 'merge_group' }}
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
     with:
-      benchmark: ${{ matrix.benchmark }}
       build_only: ${{ matrix.build_only }}
       build_type: ${{ matrix.build_type }}
       ccache_enabled: ${{ inputs.ccache_enabled }}
@@ -51,6 +50,5 @@ jobs:
       config_name: ${{ matrix.config_name }}
       sanitizers: ${{ matrix.sanitizers }}
       compiler: ${{ matrix.compiler || '' }}
-      toolchain: ${{ matrix.toolchain || '' }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/reusable-check-autogen.yml

@@ -1,76 +0,0 @@
-# This workflow checks that the generated protocol wrapper classes are
-# up-to-date with the macro files and generator scripts they are produced from,
-# see more info in include/xrpl/protocol_autogen/README.md.
-name: Check autogen
-
-# This workflow can only be triggered by other workflows.
-on: workflow_call
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}-autogen
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  BUILD_DIR: build/codegen
-
-jobs:
-  autogen:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
-        with:
-          python-version: "3.13"
-
-      # Code generation is pure Python, so the standalone project below offers
-      # the same targets as the main build without needing its dependencies or
-      # a compiler, which keeps this job down to a few seconds.
-      - name: Configure CMake
-        run: cmake -S cmake/codegen -B "${BUILD_DIR}"
-
-      - name: Install code generation dependencies
-        run: cmake --build "${BUILD_DIR}" --target setup_code_gen
-
-      - name: Generate code
-        run: cmake --build "${BUILD_DIR}" --target code_gen
-
-      - name: Check for differences
-        env:
-          MESSAGE: |
-
-            The generated protocol wrapper classes are out of date.
-
-            This typically happens when the macro files or generator scripts
-            have changed but the generated files were not regenerated.
-
-            Run the following from the repository root, then commit and push
-            the regenerated files. This needs neither the dependencies nor a
-            compiler. See include/xrpl/protocol_autogen/README.md for more info.
-
-              cmake -S cmake/codegen -B build/codegen
-              cmake --build build/codegen --target setup_code_gen
-              cmake --build build/codegen --target code_gen
-
-            In an already configured build directory, the 'setup_code_gen' and
-            'code_gen' targets do the same thing.
-        run: |
-          # Record untracked files in the index without staging their contents,
-          # so that classes generated for a newly added transaction or ledger
-          # entry type show up in the diff below rather than silently as an
-          # empty one.
-          git add --intent-to-add .
-          DIFF=$(git status --porcelain)
-          if [ -n "${DIFF}" ]; then
-              # Print the differences to give the contributor a hint about what to
-              # expect when running code generation on their own machine.
-              git diff
-              echo "${MESSAGE}"
-              exit 1
-          fi

.github/workflows/reusable-check-otel-naming.yml

@@ -1,78 +0,0 @@
-# This workflow checks that OpenTelemetry span-attribute names stay consistent
-# across the code (*SpanNames.h), collector, Tempo, dashboards, and docs.
-# See .github/scripts/otel-naming/check_otel_naming.py and the
-# "Telemetry span attribute naming" section in CONTRIBUTING.md.
-name: Check OTel naming
-
-# This workflow can only be triggered by other workflows.
-on: workflow_call
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}-otel-naming
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  otel-naming:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - name: Test the OTel naming checker
-        # The checker's own unit tests, run before the check itself so a broken
-        # rule is reported as a broken rule rather than as a naming violation
-        # (or, worse, as a rule that silently stops flagging anything).
-        # stdlib `unittest` only: the repo installs no third-party test runner
-        # for CI, and the checker itself is deliberately dependency-free.
-        run: python -m unittest discover -s .github/scripts/otel-naming -p 'test_*.py' --verbose
-      - name: Check OTel naming
-        # The script is stdlib-only and reads only files already in the tree;
-        # it enforces each rule only when the layer it needs is present, so it
-        # works whether telemetry changes land in one PR or several.
-        run: python .github/scripts/otel-naming/check_otel_naming.py
-      - name: Check histogram bucket parity
-        # The C++ millisecond ladder and the collector's spanmetrics ladder are
-        # specified to agree over their shared range. They were identical when
-        # first shipped, then the collector side alone was extended and nothing
-        # noticed for eleven phases: native histograms stayed capped at 5s while
-        # spans reached 30s, so every quantile above 5s reported a flat 5000.
-        # Nothing but a check keeps two lists in step.
-        run: python .github/scripts/telemetry/check_bucket_parity.py
-      - name: Test the workload regression-bounds checker
-        # Its own tests, run before the check itself so a broken rule is
-        # reported as a broken rule rather than as a threshold violation. They
-        # also pin the input-handling contract: a placeholder baseline passes
-        # (that is the documented bootstrap state) while a missing, unreadable
-        # or malformed input fails, so deleting an input cannot silence the
-        # check. stdlib unittest only, as with the naming checker.
-        run: python -m unittest discover -s .github/scripts/telemetry -p 'test_*.py' --verbose
-      - name: Check workload regression bounds
-        # The workload gate's absolute bounds are derived from the committed
-        # baseline plus the two ladders, and nothing tied the three together.
-        # That let the gate break three times the same way -- the microsecond
-        # floor moved, the span floor moved, then the bounds stayed calibrated
-        # for a band the spans had left, so a 100x regression reported zero
-        # regressions and exit 0. Every failure looked like a green build.
-        # This asserts each bound is still the one its own baseline implies.
-        run: python .github/scripts/telemetry/check_regression_bounds.py
-      - name: Install the workload harness dependencies
-        # Its own step so a PyPI outage is reported as an install failure rather
-        # than as a failing harness. Last in the job, because every check above
-        # is stdlib-only and stays reachable if this fails.
-        run: pip3 install -r docker/telemetry/workload/requirements.txt
-      - name: Test the telemetry workload harness
-        # Run here rather than in the telemetry validation so a broken harness is
-        # reported in seconds instead of after a full xrpld build, and on every
-        # PR rather than only when that workflow's paths match.
-        #
-        # Plain scripts, not `unittest discover`: these files hold bare test
-        # functions, not TestCase subclasses, so discover would collect nothing
-        # and exit 0. Each file fails when it collects no tests, which is what
-        # makes running them this way safe.
-        run: |
-          python3 docker/telemetry/workload/test_validate_telemetry.py
-          python3 docker/telemetry/workload/test_capture_timings.py
-          python3 docker/telemetry/workload/test_tx_submitter.py

.github/workflows/reusable-clang-tidy.yml

@@ -27,14 +27,14 @@ jobs:
   determine-files:
     permissions:
       contents: read
-    uses: XRPLF/actions/.github/workflows/determine-tidy-files.yml@70145243b905dc3e040a61d39c00e178cfb96f71
+    uses: XRPLF/actions/.github/workflows/determine-tidy-files.yml@d041ac9f1fa9f07a4ba335eb4c1c82233fb3fef6
 
   run-clang-tidy:
     name: Run clang tidy
     needs: [determine-files]
     if: ${{ needs.determine-files.outputs.cpp_changed_files != '' || needs.determine-files.outputs.need_full_run == 'true' }}
     runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-060957e"
+    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-fecfc0c"
     permissions:
       contents: read
       issues: write
@@ -43,7 +43,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 
@@ -59,12 +59,6 @@ jobs:
         with:
           compiler: ${{ env.COMPILER }}
 
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
-        with:
-          cache-directories: ${{ env.BUILD_DIR }}/corrosion
-          workspaces: crates -> ../${{ env.BUILD_DIR }}/cargo
-
       - name: Setup Conan
         uses: ./.github/actions/setup-conan
 
@@ -86,13 +80,13 @@ jobs:
               -Dwerr=ON \
               -Dxrpld=ON \
               -Dverify_headers=ON \
-              -Drust=ON \
               ..
 
-      - name: Build clang-tidy prerequisites
+      # clang-tidy needs headers generated from proto files
+      - name: Build libxrpl.libpb
         working-directory: ${{ env.BUILD_DIR }}
         run: |
-          ninja -j ${{ steps.nproc.outputs.nproc }} tidy_prerequisites
+          ninja -j ${{ steps.nproc.outputs.nproc }} xrpl.libpb
 
       - name: Run clang tidy
         id: run_clang_tidy

.github/workflows/reusable-package-test-install.yml

@@ -1,120 +0,0 @@
-# Install one package format on every distro family it targets, one job per
-# package name and image, and run the binaries there. Called once per format by
-# reusable-package.yml, which owns the names and the image lists.
-name: Install packages
-
-on:
-  workflow_call:
-    inputs:
-      package_type:
-        description: 'The package format to install ("deb" or "rpm").'
-        required: true
-        type: string
-      package_names:
-        description: "JSON array of package names built for this format."
-        required: true
-        type: string
-      images:
-        description: "JSON array of container images to install in."
-        required: true
-        type: string
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  PACKAGE_DIR: packages
-
-jobs:
-  install:
-    strategy:
-      fail-fast: false
-      matrix:
-        package_name: ${{ fromJson(inputs.package_names) }}
-        image: ${{ fromJson(inputs.images) }}
-    name: "${{ matrix.package_name }} on ${{ matrix.image }}"
-    permissions:
-      contents: read
-    runs-on: ubuntu-latest
-    container: ${{ matrix.image }}
-    timeout-minutes: 5
-
-    steps:
-      # Every package lands in one directory; the step below picks its own,
-      # which keeps this independent of the artifact names.
-      - name: Download package artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          pattern: "*-pkg"
-          merge-multiple: true
-          path: ${{ env.PACKAGE_DIR }}
-
-      - name: Find the package
-        id: find
-        env:
-          PACKAGE_NAME: ${{ matrix.package_name }}
-          PACKAGE_TYPE: ${{ inputs.package_type }}
-        run: |
-          # The version follows the name, separated by '_' in a DEB and '-' in an
-          # RPM. Requiring a digit after it is what keeps 'xrpld' from picking up
-          # another package, such as 'xrpld-assert'.
-          pattern="${PACKAGE_NAME}[_-][0-9]*.${PACKAGE_TYPE}"
-          package="$(find "${PACKAGE_DIR}" -type f -name "${pattern}" -print -quit)"
-          test -n "${package}" || {
-              echo "no ${pattern} found in ${PACKAGE_DIR}" >&2
-              exit 1
-          }
-          echo "package=${package}" >>"${GITHUB_OUTPUT}"
-
-      # Debian 11 went end-of-life on 2026-08-31
-      # (https://www.debian.org/News/2026/20260831) and its packages are
-      # already partly gone from deb.debian.org, so switch to the
-      # snapshot.debian.org entries the image ships commented out in its
-      # sources.list: they are pinned to the snapshot the image was built
-      # from, so they serve every version it needs and never go away.
-      # Snapshots keep their original, long-passed Valid-Until, hence the
-      # disabled check; the retries absorb snapshot.debian.org's throttling.
-      - name: Switch Debian 11 to snapshot.debian.org
-        if: ${{ matrix.image == 'debian:11' }}
-        run: |
-          sed -i 's|^deb |# deb |; s|^# deb http://snapshot|deb http://snapshot|' /etc/apt/sources.list
-          printf '%s\n' \
-              'Acquire::Check-Valid-Until "false";' \
-              'Acquire::Retries "3";' \
-              >/etc/apt/apt.conf.d/99snapshot
-
-      - name: Install the DEB
-        if: ${{ inputs.package_type == 'deb' }}
-        env:
-          DEBIAN_FRONTEND: noninteractive
-          PACKAGE: ${{ steps.find.outputs.package }}
-        run: |
-          # Stock Debian and Ubuntu images carry no package lists, so apt has
-          # nothing to resolve the systemd dependency from until it fetches them.
-          apt-get update -qq
-          apt-get install -y "./${PACKAGE}"
-
-      - name: Install the RPM
-        if: ${{ inputs.package_type == 'rpm' }}
-        env:
-          PACKAGE: ${{ steps.find.outputs.package }}
-        run: dnf install -y "./${PACKAGE}"
-
-      - name: Run xrpld
-        run: xrpld --version
-
-      - name: Run validator-keys
-        run: validator-keys --version
-
-      - name: Run rippled, the legacy compatibility symlink
-        run: rippled --version
-
-      - name: Check the service account
-        run: id xrpld
-
-      - name: Check the state directory
-        run: test -d /var/lib/xrpld
-
-      - name: Check the log directory
-        run: test -d /var/log/xrpld

.github/workflows/reusable-package.yml

@@ -1,42 +1,17 @@
-# Build, verify and publish Linux packages from the pre-built xrpld and
-# validator-keys artifacts, in three stages:
-#
-#   - 'package' builds and signs one format per config that carries a "package"
-#     map in linux.json; that map names the container image and the format
-#   - 'test-install-deb' and 'test-install-rpm' call
-#     reusable-package-test-install.yml to install what was built on a range of
-#     distros and run the binaries there, so a package that cannot be installed
-#     never reaches Nexus
-#   - 'publish' uploads with the image's publish_pkg.py, doing a --dry-run
-#     unless 'publish: true'
-#
-# Only linux/amd64 is supported; the runner is hardcoded in the jobs below.
+# Build Linux packages (DEB and RPM) from pre-built binary artifacts.
+# Discovers which configurations to package from linux.json (configs in
+# "package_configs") and fans out one job per distro. Only linux/amd64 is
+# supported; the runner is hardcoded in the job below.
 name: Package
 
 on:
   workflow_call:
     inputs:
-      publish:
-        description: "Whether to publish the packages after building them."
-        required: false
-        type: boolean
-        default: false
-      nexus_url:
-        description: "The base URL of the Nexus instance hosting the deb and rpm repositories."
+      pkg_release:
+        description: "Package release number. Increment when repackaging the same executable."
         required: false
         type: string
-        default: https://packages-upload.xrplf.org
-
-    secrets:
-      remote_username:
-        description: "The username of a Nexus account with write access to the repositories."
-        required: false
-      remote_password:
-        description: "The password or token for that Nexus account."
-        required: false
-      signing_key:
-        description: "Armoured PGP private key used to sign the RPMs. Required when publishing."
-        required: false
+        default: "1"
 
 defaults:
   run:
@@ -44,15 +19,12 @@ defaults:
 
 env:
   BUILD_DIR: build
-  PACKAGE_DIR: packages
 
 jobs:
   generate-matrix:
     runs-on: ubuntu-latest
     outputs:
       matrix: ${{ steps.generate.outputs.matrix }}
-      deb_package_names: ${{ steps.generate.outputs.deb_package_names }}
-      rpm_package_names: ${{ steps.generate.outputs.rpm_package_names }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -69,139 +41,11 @@ jobs:
 
   package:
     needs: [generate-matrix]
-    if: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
+    if: ${{ github.event.repository.visibility == 'public' }}
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
-    name: "${{ matrix.xrpld_artifact_name }}"
-    permissions:
-      contents: read
-    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: ${{ matrix.image }}
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
-        with:
-          enable_ccache: false
-
-      - name: Download pre-built xrpld binary
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: ${{ matrix.xrpld_artifact_name }}
-          path: ${{ env.BUILD_DIR }}
-
-      - name: Download pre-built validator-keys binary
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: ${{ matrix.validator_keys_artifact_name }}
-          path: ${{ env.BUILD_DIR }}
-
-      - name: Make binaries executable
-        run: chmod +x "${BUILD_DIR}/xrpld" "${BUILD_DIR}/validator-keys"
-
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
-
-      - name: Build package
-        env:
-          PACKAGE_TYPE: ${{ matrix.package_type }}
-          PACKAGE_VARIANT: ${{ matrix.package_variant }}
-          PKG_RELEASE: ${{ steps.release_info.outputs.pkg_release }}
-          CHANNEL: ${{ steps.release_info.outputs.channel }}
-        run: |
-          ./package/build_pkg.py \
-              --package-type "${PACKAGE_TYPE}" \
-              --build-dir "${BUILD_DIR}" \
-              --pkg-release "${PKG_RELEASE}" \
-              --variant "${PACKAGE_VARIANT}" \
-              --channel "${CHANNEL}"
-
-      # Before the upload, so the artifact, the tested package and the published
-      # package are the same bytes.
-      - name: Sign RPM
-        if: ${{ inputs.publish && matrix.package_type == 'rpm' }}
-        env:
-          PKG_SIGNING_KEY: ${{ secrets.signing_key }}
-        run: ./package/sign_rpm.py --package-dir "${BUILD_DIR}"
-
-      # Split from the debug symbols, which are an order of magnitude larger, so
-      # that test-install downloads only what it installs. In the globs below the
-      # version follows the name, separated by '_' in a DEB and '-' in an RPM. A
-      # version starts with a digit and a longer name does not, so that one digit
-      # is what tells 'xrpld-3.4.1-...' from 'xrpld-assert-3.4.1-...'.
-      - name: Upload package artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: ${{ matrix.xrpld_artifact_name }}-pkg
-          path: |
-            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}_[0-9]*.deb
-            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/${{ matrix.package_name }}-[0-9]*.rpm
-          if-no-files-found: error
-
-      - name: Upload debug symbol artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: ${{ matrix.xrpld_artifact_name }}-pkg-debug
-          path: |
-            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}-dbgsym_[0-9]*.deb
-            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}-dbgsym_[0-9]*.ddeb
-            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/${{ matrix.package_name }}-debuginfo-[0-9]*.rpm
-          if-no-files-found: error
-
-  # One call per format, so a variant packaged for one format is installed for
-  # that format alone. The images are every distro family that format targets,
-  # oldest release first, so both ends of the dependency range the packages
-  # declare are exercised.
-  test-install-deb:
-    needs: [generate-matrix, package]
-    name: install deb
-    uses: ./.github/workflows/reusable-package-test-install.yml
-    with:
-      package_type: deb
-      package_names: ${{ needs.generate-matrix.outputs.deb_package_names }}
-      images: |
-        [
-          "debian:11",
-          "debian:12",
-          "debian:13",
-          "ubuntu:20.04",
-          "ubuntu:22.04",
-          "ubuntu:24.04",
-          "ubuntu:26.04"
-        ]
-
-  test-install-rpm:
-    needs: [generate-matrix, package]
-    name: install rpm
-    uses: ./.github/workflows/reusable-package-test-install.yml
-    with:
-      package_type: rpm
-      package_names: ${{ needs.generate-matrix.outputs.rpm_package_names }}
-      images: |
-        [
-          "almalinux:9",
-          "almalinux:10",
-          "rockylinux/rockylinux:9",
-          "rockylinux/rockylinux:10",
-          "registry.access.redhat.com/ubi9/ubi",
-          "registry.access.redhat.com/ubi10/ubi"
-        ]
-
-  publish:
-    needs: [generate-matrix, package, test-install-deb, test-install-rpm]
-    strategy:
-      fail-fast: false
-      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
-    # The name says which of the two this is, because the job runs either way:
-    # with publish false it passes --dry-run and uploads nothing, and a job
-    # called "publish ..." succeeding on a pull request reads like a release.
-    name: "publish ${{ matrix.xrpld_artifact_name }}${{ !inputs.publish && ' (dry run)' || '' }}"
+    name: "${{ matrix.artifact_name }}"
     permissions:
       contents: read
     runs-on: ["self-hosted", "Linux", "X64", "heavy"]
@@ -212,33 +56,26 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
-        with:
-          enable_ccache: false
-
-      # Both artifacts, so the debug symbols are published alongside the package.
-      - name: Download package artifacts
+      - name: Download pre-built binary
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          pattern: ${{ matrix.xrpld_artifact_name }}-pkg*
-          merge-multiple: true
-          path: ${{ env.PACKAGE_DIR }}
+          name: ${{ matrix.artifact_name }}
+          path: ${{ env.BUILD_DIR }}
 
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
+      - name: Make binary executable
+        run: chmod +x "${BUILD_DIR}/xrpld"
 
-      - name: Publish package
+      - name: Build package
         env:
-          CHANNEL: ${{ steps.release_info.outputs.channel }}
-          DRY_RUN_OPTION: ${{ !inputs.publish && '--dry-run' || '' }}
-          NEXUS_URL: ${{ inputs.nexus_url }}
-          NEXUS_USERNAME: ${{ inputs.publish && secrets.remote_username || '' }}
-          NEXUS_PASSWORD: ${{ inputs.publish && secrets.remote_password || '' }}
-        run: |
-          publish_pkg.py \
-              --channel "${CHANNEL}" \
-              --package-dir "${PACKAGE_DIR}" \
-              --nexus-url "${NEXUS_URL}" \
-              ${DRY_RUN_OPTION}
+          PKG_RELEASE: ${{ inputs.pkg_release }}
+        run: ./package/build_pkg.sh
+
+      - name: Upload package artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ${{ matrix.artifact_name }}-pkg
+          path: |
+            ${{ env.BUILD_DIR }}/debbuild/*.deb
+            ${{ env.BUILD_DIR }}/debbuild/*.ddeb
+            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/*.rpm
+          if-no-files-found: error

.github/workflows/reusable-rust.yml

@@ -1,84 +0,0 @@
-# Clippy, coverage and documentation for the Rust crates in crates/. Each runs
-# as an independent job on a GitHub-hosted runner, but inside the same container
-# image used to build the crates in the C++/Corrosion path, so the toolchain
-# (and therefore the lints and the cargo cache) matches what production builds
-# use. Coverage is the exception: it needs the nightly rustc that honours
-# #[coverage(off)], which the image carries alongside the pinned stable.
-#
-# Rust unit tests are deliberately NOT run here. They run as part of the C++
-# build (reusable-build-test-config.yml), which already compiles the crates on a
-# self-hosted runner, so there is no need to provision a toolchain again.
-name: Rust
-
-on:
-  workflow_call:
-    secrets:
-      CODECOV_TOKEN:
-        description: "The Codecov token to use for uploading coverage reports."
-        required: true
-
-defaults:
-  run:
-    shell: bash
-    working-directory: crates
-
-permissions:
-  contents: read
-
-jobs:
-  clippy:
-    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
-
-      - name: Run clippy
-        run: cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
-
-  coverage:
-    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Use the nightly Rust toolchain
-        run: rust-nightly path >>"${GITHUB_PATH}"
-
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
-
-      - name: Generate coverage report
-        run: cargo llvm-cov nextest --workspace --all-features --locked --no-tests=warn --lcov --output-path lcov.info
-
-      - name: Upload coverage report
-        if: ${{ github.repository == 'XRPLF/rippled' }}
-        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
-        with:
-          disable_search: true
-          disable_telem: true
-          fail_ci_if_error: true
-          files: crates/lcov.info
-          flags: rust
-          plugins: noop
-          token: ${{ secrets.CODECOV_TOKEN }}
-          verbose: true
-
-  doc:
-    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
-
-      - name: Build documentation
-        env:
-          RUSTDOCFLAGS: "-D warnings"
-        run: cargo doc --workspace --no-deps --all-features --locked

.github/workflows/reusable-telemetry-validation.yml

@@ -1,446 +0,0 @@
-# Telemetry Validation CI Workflow
-#
-# Builds rippled, runs the multi-node workload harness, validates all telemetry
-# data, and runs performance benchmarks.
-#
-# The build runs whatever the caller's tree configures, so a telemetry-off tree
-# is compiled here too. Only the validation is gated: a build with the tracing
-# compiled out emits no spans and no metrics to assert on.
-#
-# The caller decides only whether to start this at all. on-pr.yml runs it when
-# telemetry-relevant paths changed.
-#
-# The workflow is intentionally heavyweight (builds rippled, starts Docker
-# services, runs a multi-node cluster) — it validates the full telemetry
-# stack end-to-end rather than individual unit tests.
-#
-# Architecture: three jobs to leverage cached dependencies:
-#   0. linux-image-tag — reads the CI image tag from the build matrix so this
-#      workflow cannot drift onto a different compiler than the main CI.
-#   1. build-xrpld — runs on a self-hosted runner inside the same container
-#      image the main CI uses. This ensures Conan packages are fetched from
-#      the XRPLF remote instead of built from source, and ccache hits the
-#      remote cache. It also reports whether the configured build has telemetry
-#      compiled in.
-#   2. validate-telemetry — runs on ubuntu-latest (which has Docker) to
-#      launch the telemetry stack (OTel collector, Prometheus, Tempo, etc.)
-#      and validate the full pipeline end-to-end, against the binary job 1
-#      uploaded. Skipped when job 1 reports telemetry off.
-
-name: Telemetry Validation
-
-on:
-  workflow_call:
-    inputs:
-      run_benchmark:
-        description: "Run performance benchmarks."
-        required: false
-        type: boolean
-        default: false
-
-concurrency:
-  group: telemetry-validation-${{ github.ref }}
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  BUILD_DIR: build
-
-jobs:
-  # ── Job 0: Resolve the CI image tag ────────────────────────────────
-  # The tag is pinned once, alongside the build matrix, in linux.json. Reading
-  # it here rather than hardcoding a second copy means this workflow always
-  # builds in the same image (and therefore the same compiler) as the main CI.
-  # A hardcoded copy silently went stale and left this job on gcc 13 after the
-  # rest of CI moved to gcc 15, which broke the build on code the main CI
-  # compiled fine.
-  linux-image-tag:
-    runs-on: ubuntu-latest
-    outputs:
-      tag: ${{ steps.tag.outputs.tag }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Read nix image tag
-        id: tag
-        run: echo "tag=$(jq -r .image_tag .github/scripts/strategy-matrix/linux.json)" >>"${GITHUB_OUTPUT}"
-
-  # ── Job 1: Build xrpld in the same container the main CI uses ──────
-  # This ensures Conan binary packages are fetched from the XRPLF remote
-  # (matching package IDs) and ccache hits the remote compilation cache.
-  build-xrpld:
-    name: Build xrpld
-    needs: linux-image-tag
-    outputs:
-      telemetry: ${{ steps.telemetry.outputs.enabled }}
-    runs-on: [self-hosted, Linux, X64, heavy]
-    container: ghcr.io/xrplf/xrpld/nix-debian:${{ needs.linux-image-tag.outputs.tag }}
-    timeout-minutes: 60
-    env:
-      CCACHE_NAMESPACE: telemetry-validation
-      CCACHE_REMOTE_ONLY: true
-      CCACHE_REMOTE_STORAGE: http://cache.dev.ripplex.io:8080|layout=bazel
-      CCACHE_SLOPPINESS: include_file_ctime,include_file_mtime
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
-        with:
-          enable_ccache: ${{ github.repository_owner == 'XRPLF' }}
-
-      - name: Print build environment
-        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
-
-      - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
-        id: nproc
-        with:
-          subtract: 2
-
-      # The nix image ships several toolchains, so CC/CXX must be set
-      # explicitly for Conan to detect the intended one. gcc matches the
-      # debian gcc-release config the main CI builds.
-      - name: Set compiler environment
-        uses: ./.github/actions/set-compiler-env
-        with:
-          compiler: gcc
-
-      - name: Setup Conan
-        uses: ./.github/actions/setup-conan
-
-      - name: Build dependencies
-        uses: ./.github/actions/build-deps
-        with:
-          build_nproc: ${{ steps.nproc.outputs.nproc }}
-          build_type: Release
-          log_verbosity: verbose
-
-      # The telemetry option is deliberately not repeated here. Conan owns it and
-      # the generated toolchain hands its value to CMake. A command-line define
-      # is written to the cache before the toolchain runs and wins over it, so it
-      # could turn telemetry on with the package never fetched.
-      - name: Configure CMake
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          cmake \
-              -G Ninja \
-              -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-              -DCMAKE_BUILD_TYPE=Release \
-              ..
-
-      # A build with tracing compiled out emits nothing to assert on, so the
-      # validation job below gates on this. Read from the configured build, so
-      # this file holds no copy of the setting.
-      #
-      # Every value CMake does not accept as a boolean fails the job, including a
-      # missing entry. A gate that guessed would skip the validation silently,
-      # which is the one failure it must not have.
-      - name: Read whether telemetry is compiled in
-        id: telemetry
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          value=$(sed -n 's/^telemetry:[^=]*=//p' CMakeCache.txt)
-          case "${value}" in
-              True | TRUE | true | ON | on | YES | yes | Y | y | 1) enabled=true ;;
-              False | FALSE | false | OFF | off | NO | no | N | n | 0) enabled=false ;;
-              *)
-                  echo "telemetry reads '${value}' in CMakeCache.txt, which is not" >&2
-                  echo "a boolean. conan install sets it through the toolchain." >&2
-                  exit 1
-                  ;;
-          esac
-          echo "telemetry compiled in: ${enabled}"
-          echo "enabled=${enabled}" >>"${GITHUB_OUTPUT}"
-
-      - name: Build xrpld
-        working-directory: ${{ env.BUILD_DIR }}
-        env:
-          BUILD_NPROC: ${{ steps.nproc.outputs.nproc }}
-        run: |
-          cmake \
-              --build . \
-              --config Release \
-              --parallel "${BUILD_NPROC}" \
-              --target xrpld
-
-      - name: Show ccache statistics
-        if: ${{ github.repository_owner == 'XRPLF' }}
-        run: ccache --show-stats -vv
-
-      - name: Upload xrpld binary
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: xrpld-telemetry
-          path: ${{ env.BUILD_DIR }}/xrpld
-          retention-days: 1
-          if-no-files-found: error
-
-  # ── Job 2: Run telemetry validation on ubuntu-latest (has Docker) ──
-  validate-telemetry:
-    name: Telemetry Stack Validation
-    needs: build-xrpld
-    # Reuses the binary job 1 built and uploaded, so a skip here costs no build.
-    if: needs.build-xrpld.outputs.telemetry == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Install Python dependencies
-        run: pip3 install -r docker/telemetry/workload/requirements.txt
-
-      - name: Download xrpld binary
-        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
-        with:
-          name: xrpld-telemetry
-          path: ${{ env.BUILD_DIR }}
-
-      - name: Make binaries and scripts executable
-        run: |
-          chmod +x ${{ env.BUILD_DIR }}/xrpld
-          chmod +x docker/telemetry/workload/*.sh
-
-      - name: Run full telemetry validation
-        id: validation
-        env:
-          RPC_RATE: "50"
-          RPC_DURATION: "120"
-          TX_TPS: "5"
-          TX_DURATION: "120"
-          RUN_BENCHMARK: ${{ inputs.run_benchmark }}
-        run: |
-          # The four rate/duration flags below are inert:
-          # run-full-validation.sh parses them and never reads them. Load shape
-          # comes from the default --profile full-validation. They are still
-          # passed so the flags stay exercised if they are ever wired up.
-          ARGS="--xrpld ${{ env.BUILD_DIR }}/xrpld"
-          ARGS="$ARGS --rpc-rate $RPC_RATE"
-          ARGS="$ARGS --rpc-duration $RPC_DURATION"
-          ARGS="$ARGS --tx-tps $TX_TPS"
-          ARGS="$ARGS --tx-duration $TX_DURATION"
-          if [ "$RUN_BENCHMARK" = "true" ]; then
-              ARGS="$ARGS --with-benchmark"
-          fi
-          docker/telemetry/workload/run-full-validation.sh $ARGS
-        # continue-on-error allows subsequent steps (artifact upload,
-        # summary printing) to run even if validation fails. The final
-        # "Check validation result" step re-checks steps.validation.outcome
-        # (the pre-continue-on-error result) and fails the job properly.
-        continue-on-error: true
-
-      - name: Upload validation reports
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: telemetry-validation-reports
-          path: /tmp/xrpld-validation/reports/
-          retention-days: 30
-
-      # Keyed on the validation step's own outcome, not job status. The step
-      # above sets continue-on-error, so the job is not failing at this point
-      # and `if: failure()` never fires -- which silently skipped these logs on
-      # every failed run, and they are the only record of why a node did not
-      # reach consensus.
-      #
-      # stdout.log matters as much as debug.log: a node that dies before its
-      # log sink opens writes no debug.log at all, so stdout is the only place
-      # its reason survives. A run that timed out at 4/5 nodes was left
-      # undiagnosable because that file was not collected.
-      - name: Upload node logs
-        if: always() && steps.validation.outcome != 'success'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: xrpld-node-logs
-          path: |
-            /tmp/xrpld-validation/node*/debug.log
-            /tmp/xrpld-validation/node*/stdout.log
-            /tmp/xrpld-validation/*.log
-          retention-days: 7
-          if-no-files-found: warn
-
-      - name: Print validation summary
-        if: always()
-        run: |
-          REPORT="/tmp/xrpld-validation/reports/validation-report.json"
-          if [ -f "$REPORT" ]; then
-              echo "## Telemetry Validation Results" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              TOTAL=$(jq '.summary.total' "$REPORT")
-              PASSED=$(jq '.summary.passed' "$REPORT")
-              FAILED=$(jq '.summary.failed' "$REPORT")
-              echo "| Metric | Value |" >>"$GITHUB_STEP_SUMMARY"
-              echo "|--------|-------|" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Total Checks | $TOTAL |" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Passed | $PASSED |" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Failed | $FAILED |" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              if [ "$FAILED" -gt 0 ]; then
-                  echo "### Failed Checks" >>"$GITHUB_STEP_SUMMARY"
-                  echo "" >>"$GITHUB_STEP_SUMMARY"
-                  jq -r '.checks[] | select(.passed == false) | "- **\(.name)**: \(.message)"' "$REPORT" >>"$GITHUB_STEP_SUMMARY"
-              fi
-          fi
-
-      # Publishes captured OTel timings + regression report to the Step Summary.
-      # When the committed baseline is a placeholder AND the capture is
-      # complete, emits a fenced JSON block that can be copy-pasted directly
-      # into baselines/baseline-timings.json. An incomplete capture is named as
-      # such and its JSON withheld — see the comment on that branch below.
-      # When the baseline is populated, summarises the top regressions so the
-      # PR author sees the failure reason without downloading artifacts.
-      - name: Print regression summary
-        if: always()
-        run: |
-          set -euo pipefail
-          TIMINGS="/tmp/xrpld-validation/reports/timings.json"
-          REGRESSION="/tmp/xrpld-validation/reports/regression-report.json"
-          BASELINE="docker/telemetry/workload/baselines/baseline-timings.json"
-
-          if [ ! -f "$TIMINGS" ]; then
-              echo "## Regression Gate: no timings captured" >>"$GITHUB_STEP_SUMMARY"
-              echo "::warning::capture_timings.py did not produce timings.json — regression gate was not evaluated."
-              exit 0
-          fi
-
-          if [ ! -f "$BASELINE" ]; then
-              echo "## Regression Gate: baseline file missing" >>"$GITHUB_STEP_SUMMARY"
-              echo "::error::baselines/baseline-timings.json not found in checkout"
-              exit 1
-          fi
-
-          # NOTE: do NOT use `jq -e` here. With -e, jq exits non-zero when the
-          # filter's result is boolean false — which is the normal case for a
-          # populated (non-placeholder) baseline — and that would be
-          # misreported as a parse failure. Plain `jq -r` exits 0 on any valid
-          # JSON, so a real non-zero exit genuinely means malformed JSON.
-          IS_PLACEHOLDER=$(jq -r '.placeholder == true or (.metrics | length == 0)' "$BASELINE") || {
-              echo "::error::Failed to parse baseline JSON"
-              exit 1
-          }
-
-          # Whether the capture is usable as baseline material is the capture's
-          # own verdict, carried in the artifact by capture_timings.py, which
-          # computes it against --min-capture-ratio. It is READ here, never
-          # re-derived: a second copy of the ratio rule in shell would be a
-          # second source of truth and would drift from the producer.
-          #
-          # `// false` covers both an artifact written before the block existed
-          # and a truncated one. Neither can prove it is complete, so neither is
-          # offered — the whole point is that a degraded capture must not look
-          # like a good one. Same `jq -r` reasoning as the baseline parse above.
-          CAPTURE_COMPLETE=$(jq -r '.capture.complete // false' "$TIMINGS") || {
-              echo "::error::Failed to parse timings JSON"
-              exit 1
-          }
-          if [ "$(jq -r 'has("capture")' "$TIMINGS")" = "true" ]; then
-              CAPTURE_COUNTS=$(jq -r '"\(.capture.captured)/\(.capture.declared)"' "$TIMINGS")
-              CAPTURE_SHORTFALL="only **$CAPTURE_COUNTS** declared metrics came back, below the capture's own minimum ratio"
-          else
-              CAPTURE_COUNTS="unknown"
-              CAPTURE_SHORTFALL="the artifact carries no \`capture\` block, so it predates completeness reporting and cannot state what it captured"
-          fi
-
-          echo "## OTel Timings Regression Gate" >>"$GITHUB_STEP_SUMMARY"
-          echo "" >>"$GITHUB_STEP_SUMMARY"
-
-          if [ "$IS_PLACEHOLDER" = "true" ] && [ "$CAPTURE_COMPLETE" != "true" ]; then
-              # The placeholder path is the ONLY route to a committed baseline,
-              # which makes it the one place an incomplete capture does lasting
-              # damage: pasted in, it silently narrows the gate to the keys that
-              # happened to come back. So the JSON is withheld rather than
-              # printed with a caveat — a warning above a copyable block is
-              # still a copyable block. The counts are shown so the reader knows
-              # how thin it was, and the artifact is still uploaded for anyone
-              # who needs to inspect it deliberately.
-              echo "### Baseline NOT refreshable from this run" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              echo "The committed baseline is a placeholder, so this run would" \
-                  "normally print a block to paste into" \
-                  "\`baselines/baseline-timings.json\`. It is withheld because" \
-                  "$CAPTURE_SHORTFALL, so the JSON may describe metrics that" \
-                  "were never measured. Pasting it would narrow the gate to" \
-                  "whichever keys were captured, with nothing reporting that" \
-                  "it had narrowed." >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              echo "Fix the capture first — the usual cause is Prometheus not" \
-                  "being scraped for long enough, or nodes not reaching" \
-                  "consensus — then re-run. See the \`timings.json\` artifact's" \
-                  "\`capture\` block for the exact counts." >>"$GITHUB_STEP_SUMMARY"
-              echo "::error::Timing capture is incomplete ($CAPTURE_COUNTS metrics) — no baseline block printed. Do not refresh the baseline from this run."
-          elif [ "$IS_PLACEHOLDER" = "true" ]; then
-              echo "### Paste into \`baselines/baseline-timings.json\`" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              echo "The committed baseline is a placeholder. Open a PR replacing" \
-                  "its contents with the JSON block below to activate the" \
-                  "regression gate. The capture is complete" \
-                  "($CAPTURE_COUNTS declared metrics)." >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              echo '```json' >>"$GITHUB_STEP_SUMMARY"
-              cat "$TIMINGS" >>"$GITHUB_STEP_SUMMARY"
-              echo '```' >>"$GITHUB_STEP_SUMMARY"
-          elif [ -f "$REGRESSION" ]; then
-              # Existence is not readability: a truncated report satisfies -f,
-              # and the `|| =0` fallbacks below would then render a clean table
-              # of zeros for a run that compared nothing. Same trap the note
-              # above the baseline parse warns about, so check the shape first.
-              SUMMARY_OK=$(jq -r 'if (.summary | type) == "object" then "yes" else "no" end' \
-                  "$REGRESSION" 2>/dev/null) || SUMMARY_OK=no
-              if [ "$SUMMARY_OK" != "yes" ]; then
-                  echo "## Regression Gate: report unreadable" >>"$GITHUB_STEP_SUMMARY"
-                  echo "" >>"$GITHUB_STEP_SUMMARY"
-                  echo "\`$REGRESSION\` exists but carries no \`summary\` object, so no" \
-                      "table can be rendered. The pass/fail above still comes from the" \
-                      "comparator's exit code." >>"$GITHUB_STEP_SUMMARY"
-                  echo "::error::Regression report is present but has no summary object"
-              else
-                  # No `jq -e`: it exits non-zero when a field is legitimately 0 or
-                  # false, which the fallbacks would silently turn into 0 as well.
-                  REGR_COUNT=$(jq -r '.summary.regressions // 0' "$REGRESSION")
-                  IMPR_COUNT=$(jq -r '.summary.improvements // 0' "$REGRESSION")
-                  TOTAL=$(jq -r '.summary.total // 0' "$REGRESSION")
-                  MISSING_COUNT=$(jq -r '.summary.missing_in_current // 0' "$REGRESSION")
-                  COMPARED=$(jq -r '.summary.compared // 0' "$REGRESSION")
-                  # `total` is every key in the report, i.e. the union of the
-                  # baseline and this run, so it is not what was gated. The
-                  # comparator reports `compared` for that; do not derive it from
-                  # total minus missing, because a key can also be skipped for
-                  # being new or for having no data on either side.
-                  echo "| Stat | Count |" >>"$GITHUB_STEP_SUMMARY"
-                  echo "|------|-------|" >>"$GITHUB_STEP_SUMMARY"
-                  echo "| Metrics in report | $TOTAL |" >>"$GITHUB_STEP_SUMMARY"
-                  echo "| Metrics compared | $COMPARED |" >>"$GITHUB_STEP_SUMMARY"
-                  echo "| Not captured this run | $MISSING_COUNT |" >>"$GITHUB_STEP_SUMMARY"
-                  echo "| Regressions | $REGR_COUNT |" >>"$GITHUB_STEP_SUMMARY"
-                  echo "| Improvements | $IMPR_COUNT |" >>"$GITHUB_STEP_SUMMARY"
-                  echo "" >>"$GITHUB_STEP_SUMMARY"
-                  if [ "$MISSING_COUNT" -gt 0 ]; then
-                      echo "::warning::$MISSING_COUNT baseline metric(s) were not captured this run, so they were not gated"
-                  fi
-                  if [ "$REGR_COUNT" -gt 0 ]; then
-                      echo "### Regressions" >>"$GITHUB_STEP_SUMMARY"
-                      echo "" >>"$GITHUB_STEP_SUMMARY"
-                      echo "| Metric | Baseline | Current | Δ | % | Unit |" >>"$GITHUB_STEP_SUMMARY"
-                      echo "|--------|---------:|--------:|--:|--:|------|" >>"$GITHUB_STEP_SUMMARY"
-                      jq -r '.metrics[] | select(.regressed) | "| \(.key) | \(.baseline) | \(.current) | \(.delta) | \(.pct_change)% | \(.unit) |"' \
-                          "$REGRESSION" >>"$GITHUB_STEP_SUMMARY"
-                  fi
-              fi
-          fi
-
-      - name: Cleanup
-        if: always()
-        run: |
-          docker/telemetry/workload/run-full-validation.sh --cleanup 2>/dev/null || true
-
-      - name: Check validation result
-        if: steps.validation.outcome == 'failure'
-        run: |
-          echo "Telemetry validation failed. Check the uploaded reports for details."
-          exit 1

.github/workflows/reusable-upload-recipe.yml

@@ -40,7 +40,7 @@ defaults:
 jobs:
   upload:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     env:
       REMOTE_NAME: ${{ inputs.remote_name }}
       CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.remote_username }}
@@ -49,14 +49,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
-        with:
-          enable_ccache: false
-
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
+      - name: Generate build version number
+        id: version
+        uses: ./.github/actions/generate-version
 
       - name: Set up Conan
         uses: ./.github/actions/setup-conan
@@ -69,8 +64,8 @@ jobs:
 
       - name: Upload Conan recipe (version)
         run: |
-          conan export . --version=${{ steps.release_info.outputs.version }}
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/${{ steps.release_info.outputs.version }}
+          conan export . --version=${{ steps.version.outputs.version }}
+          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/${{ steps.version.outputs.version }}
 
       # When this workflow is triggered by a push event, it will always be when merging into the
       # 'develop' branch, see on-trigger.yml.
@@ -97,4 +92,4 @@ jobs:
           conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/release
 
     outputs:
-      ref: xrpl/${{ steps.release_info.outputs.version }}
+      ref: xrpl/${{ steps.version.outputs.version }}

.github/workflows/upload-conan-deps.yml

@@ -68,15 +68,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 
-      # Before any step that uses a build tool, composite actions included.
-      - name: Setup Nix environment
-        if: ${{ matrix.toolchain == 'nix' }}
-        uses: ./.github/actions/setup-nix-env
-
       - name: Print build environment
         uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
 
@@ -92,9 +87,7 @@ jobs:
         with:
           compiler: ${{ matrix.compiler }}
 
-      # `setup-nix-env` already did this for the Nix toolchain.
       - name: Setup Conan
-        if: ${{ matrix.toolchain != 'nix' }}
         env:
           SANITIZERS: ${{ matrix.sanitizers }}
         uses: ./.github/actions/setup-conan
@@ -113,10 +106,6 @@ jobs:
           log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
           sanitizers: ${{ matrix.sanitizers }}
 
-      - name: Check the Conan cache for Nix store references (Nix toolchain)
-        if: ${{ matrix.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${CONAN_HOME}"
-
       - name: Log into Conan remote
         if: ${{ github.repository == 'XRPLF/rippled' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
         run: conan remote login "${CONAN_REMOTE_NAME}" "${{ secrets.NEXUS_REMOTE_USERNAME }}" --password "${{ secrets.NEXUS_REMOTE_PASSWORD }}"

.gitignore

@@ -72,16 +72,11 @@ DerivedData
 /.zed/
 
 # AI tools.
-# Shared/committable AI agent config (AGENTS.md, CLAUDE.md, GEMINI.md, .claude/settings.json,
-# tool-specific rules files, etc.) should be checked in — see CONTRIBUTING.md. Only the
-# personal/local variants below are ignored.
 /.agent
 /.agents
 /.augment
-/.claude/settings.local.json
-AGENTS.override.md
-CLAUDE.local.md
-GEMINI.local.md
+/.claude
+/CLAUDE.md
 
 # Python
 __pycache__
@@ -94,9 +89,3 @@ target/
 
 # clangd cache
 /.cache
-
-# Rust build directory
-crates/target
-
-# Env. file carrying environmental setup data for local or cloud runs.
-.env.*

.pre-commit-config.yaml

@@ -53,11 +53,6 @@ repos:
         entry: ./bin/pre-commit/check_doxygen_style.py
         language: python
         types_or: [c++, c]
-      - id: fix-gtest-names
-        name: "fix gtest names: CamelCase suite, snake_case test case"
-        entry: ./bin/pre-commit/fix_gtest_names.py
-        language: python
-        types_or: [c++, c]
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
     rev: f4d7745e17a28aad7eed2f4874ca8d1568c11c4c # frozen: v22.1.8
@@ -67,20 +62,6 @@ repos:
         types_or: [c++, c, proto]
         exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/
 
-  - repo: local
-    hooks:
-      - id: cargo-fmt
-        name: cargo fmt
-        entry: cargo fmt --manifest-path crates/Cargo.toml --all
-        language: system
-        types: [rust]
-        pass_filenames: false # rustfmt formats the whole workspace
-      - id: check-coverage-attrs
-        name: check Rust coverage attributes
-        entry: ./bin/pre-commit/check_rust_coverage_attrs.py
-        language: python
-        files: ^crates/.*\.rs$
-
   - repo: https://github.com/BlankSpruce/gersemi-pre-commit
     rev: e98930bdc210d3387007f9252d8c1694ea7e410f # frozen: 0.27.7
     hooks:
@@ -92,27 +73,11 @@ repos:
       - id: prettier
         args: [--end-of-line=auto]
 
-  # Scoped to package/: the rest of the repo's Python has pre-existing findings,
-  # so widening these is its own change.
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 7c55798a78262d14b2074abf623d8a992ebb70d4 # frozen: v0.16.2
-    hooks:
-      - id: ruff-check
-        args: [--fix]
-        files: ^package/.*\.py$
-
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 4160603246a6b365d4a2af661c6d71b0a0f50478 # frozen: 26.5.1
     hooks:
       - id: black
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 41e691678310dfd3833f7ab4e180ddb014310356 # frozen: v2.3.0
-    hooks:
-      - id: mypy
-        args: [--strict]
-        files: ^package/.*\.py$
-
   - repo: https://github.com/scop/pre-commit-shfmt
     rev: 05c1426671b9237fb5e1444dd63aa5731bec0dfb # frozen: v3.13.1-1
     hooks:

AGENTS.md

@@ -1,42 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to AI coding agents (Claude Code, and other AGENTS.md-compatible tools) when working with code in this repository.
-
-## Build
-
-Required on Linux/macOS: use the Nix devshell, which sets up the compiler, Conan, ccache, and (optionally) Rust automatically.
-
-```bash
-nix develop
-```
-
-For alternate devshell variants (specific compiler, no-compiler, coverage), see [docs/build/nix.md](./docs/build/nix.md). For the manual build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`).
-
-Rust crate tests (independent of the CMake build): `cargo test --manifest-path crates/Cargo.toml --workspace` (CI uses `cargo nextest`).
-
-## Testing
-
-Unit tests are a custom framework built into the `xrpld` binary itself (not Boost.Test/GTest/Catch); see [CONTRIBUTING.md](./CONTRIBUTING.md#unit-tests) for the basic invocation. Notes not covered there:
-
-- A suite's `--unittest` name is built from the arguments to its `BEAST_DEFINE_TESTSUITE`/`BEAST_DEFINE_TESTSUITE_PRIO` macro (usually at the bottom of the test file), in reverse order and joined with `.`: `BEAST_DEFINE_TESTSUITE(Credentials, app, xrpl)` → `xrpl.app.Credentials`.
-- `--unittest-arg` does nothing — don't use it.
-- Tests that run offline in under a minute should be automatic `--unittest` suites; anything else is a manual/integration test.
-- New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/`. `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.
-
-## Lint/Format
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md#pre-commit-hooks) for `pre-commit` setup and [CONTRIBUTING.md](./CONTRIBUTING.md#clang-tidy) for `clang-tidy` (opt-in, needs local `clang-tidy` and generated headers).
-
-## Code Style
-
-New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages).
-
-## Architecture
-
-Paths below reflect the current layout; update this section if modularization moves a subsystem to a different directory.
-
-- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`. Any change to transaction-processing behavior must be gated behind an Amendment.
-- `src/xrpld/` — the server application built on top of `libxrpl`: `app`, `core`, `overlay` (P2P networking), `peerfinder`, `perflog`, `rpc`, `shamap`. `main` builds an `ApplicationImp` implementing `Application`; most components hold a reference to it (`app_`), giving broad cross-component access — expect to trace call chains through `Application&`.
-- `src/test/` — unit tests mirroring the subsystems above, plus `jtx/` (the transaction-building test DSL — e.g. `jtx/escrow.h`, `jtx/vault.h`, `jtx/sponsor.h`, `jtx/permissioned_dex.h`) and `unit_test/` (the custom test framework itself, derived from Beast).
-- `src/tests/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
-- `crates/` — a Rust workspace (only built with `-Dxrpld -Drust=ON`) bridged into C++ via `cxxbridge`/the `cxx` crate; currently just a `hello_world` interop scaffold. Requires the Rust toolchain pinned in `rust-toolchain.toml` (the Nix devshell provides it automatically).

API-CHANGELOG.md

@@ -22,48 +22,17 @@ API version 2 is available in `xrpld` version 2.0.0 and later. See [API-VERSION-
 
 This version is supported by all `xrpld` versions. For WebSocket and HTTP JSON-RPC requests, it is currently the default API version used when no `api_version` is specified.
 
-## XRP Ledger server version 3.4.0
+## Unreleased
 
-Version 3.4.0 is not yet released. These changes are available in the 3.4.0 beta releases.
+This section contains changes targeting a future version.
 
-### Additions in 3.4.0
+### Additions
 
-- `ledger`: `nftoken_id`, `nftoken_ids`, and `offer_id` are now included in transaction metadata when transactions are expanded (`expand`, or admin-only `full`), matching the `tx`, `account_tx`, and `subscribe` (`transactions` stream) responses. ([#5706](https://github.com/XRPLF/rippled/pull/5706))
-
-### Bugfixes in 3.4.0
-
-- `sign`, `sign_for`, `submit`: `signature_target` now returns `invalidParams` unless it names `CounterpartySignature` or `SponsorSignature`. It previously accepted any inner object field, such as `Book` or `NFToken`, and signed into it.
-- `sign`, `sign_for`, `submit`, `submit_multisigned`: With `fixCleanup3_4_0` enabled, a signature in `CounterpartySignature` or `SponsorSignature` covers a different prefix than the transaction's own signature, so a signature can no longer be moved from one of those roles into another. Clients that build these signatures themselves must use the new prefixes: `CPT` and `CPM` (single- and multi-signing) for `CounterpartySignature`, and `SPN` and `SPM` for `SponsorSignature`.
-- `get_aggregate_price`: Duplicate entries in the `oracles` request array are now ignored. [#6586](https://github.com/XRPLF/rippled/pull/6586)
-- `vault_info`: Errors now identify what the request got wrong instead of reporting every failure as the unregistered token `malformedRequest`, and the `error`, `error_code` and `error_message` fields now agree with each other. An invalid `vault_id` or `seq` returns `invalidParams`, an invalid `owner` returns `actMalformed`, and a request that mixes `vault_id` with `owner`/`seq` or supplies neither returns `invalidParams` with a message naming the accepted combinations. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `vault_info`: A well-formed all-zero `vault_id` now returns `entryNotFound` instead of being rejected as malformed, and `entryNotFound` responses now include `error_code` and `error_message`. Clients that request `ripplerpc` 3.0 or above therefore receive HTTP 400 with that error rather than HTTP 200. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `vault_info`: `vault_id` and `owner` must now be strings, matching how `ledger_entry` reads the same fields. An object or an array in either field previously produced an internal error, and a number was silently converted to its decimal text; `vault_id` now returns `invalidParams` and `owner` returns `actMalformed`. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `gateway_balances`: The `account` and `ident` fields now return an `invalidParams` error if the value is not a string, instead of an `internal` error. [#7655](https://github.com/XRPLF/rippled/pull/7655)
-- `account_lines`: The `peer` field now returns an error if the value is not a string. [#7728](https://github.com/XRPLF/rippled/pull/7728)
-- `ledger`: `delivered_amount` is now included in the metadata of successful `AccountDelete` transactions when transactions are expanded (`expand`, or admin-only `full`). Previously it was only added for `Payment` and `CheckCash`, which made `ledger` inconsistent with `tx` and `account_tx`. [#5706](https://github.com/XRPLF/rippled/pull/5706)
-- `noripple_check`: The `transactions` field is no longer included in error responses; it is still returned (possibly as an empty array) whenever `transactions` is `true` and the request succeeds. A malformed `account` is now rejected before the ledger is looked up, so that error response no longer carries the `ledger_hash`, `ledger_index`, and `validated` fields ([#6303](https://github.com/XRPLF/rippled/pull/6303)).
-
-## XRP Ledger server version 3.3.0
-
-[Version 3.3.0](https://github.com/XRPLF/rippled/releases/tag/3.3.0) was released on Aug 6, 2026.
-
-### Additions in 3.3.0
-
-- `account_tx`: Added an optional `delegate` request object to filter delegated transactions. The object requires `delegate_filter`, which must be either `actor` for transactions owned by the requested account but signed by another account, or `authorizer` for transactions signed by the requested account on behalf of another account. The optional `counter_party` account narrows the results to a specific signer/delegate for `actor` or a specific owner/delegator for `authorizer`. Malformed `delegate`, `delegate_filter`, and `counter_party` values return standard invalid field errors, and invalid account IDs return `actMalformed`. When paginating delegate-filtered queries, a marker from a delegate-filtered query includes a `delegate` flag and is only valid for follow-up requests that also supply `delegate` (mixing marker conventions returns `invalidParams`). Because filtering is applied after the ledger scan, a page may contain fewer results than `limit` (possibly zero) while still returning a marker, so callers must continue until no marker is present. ([#6126](https://github.com/XRPLF/rippled/pull/6126))
-
-## XRP Ledger server version 3.2.1
-
-[Version 3.2.1](https://github.com/XRPLF/rippled/releases/tag/3.2.1) was released on Aug 1, 2026.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 3.2.0
-
-[Version 3.2.0](https://github.com/XRPLF/rippled/releases/tag/3.2.0) was released on Jun 16, 2026.
-
-### Additions in 3.2.0
+- `account_tx`: Added an optional `delegate` request object to filter delegated transactions. The object requires `delegate_filter`, which must be either `actor` for transactions owned by the requested account but signed by another account, or `authorizer` for transactions signed by the requested account on behalf of another account. The optional `counter_party` account narrows the results to a specific signer/delegate for `actor` or a specific owner/delegator for `authorizer`. Malformed `delegate`, `delegate_filter`, and `counter_party` values return standard invalid field errors, and invalid account IDs return `actMalformed`.
+  When paginating delegate-filtered queries, a marker from a delegate-filtered query includes a `delegate` flag and is only valid for follow-up requests that also supply `delegate` (mixing marker conventions returns `invalidParams`). Because filtering is applied after the ledger scan, a page may contain fewer results than `limit` (possibly zero) while still returning a marker, so callers must continue until no marker is present.
 
 - `ledger_entry`, `account_objects`: The `Delegate` ledger entry now includes an optional `DestinationNode` field, which stores the index into the authorized account's owner directory. This field is present on entries created after bidirectional directory tracking was introduced and may appear in RPC responses for those entries. ([#6681](https://github.com/XRPLF/rippled/pull/6681))
+
 - `server_definitions`: Added the following new sections to the response ([#6321](https://github.com/XRPLF/rippled/pull/6321)):
   - `TRANSACTION_FORMATS`: Describes the fields and their optionality for each transaction type, including common fields shared across all transactions.
   - `LEDGER_ENTRY_FORMATS`: Describes the fields and their optionality for each ledger entry type, including common fields shared across all ledger entries.
@@ -71,7 +40,7 @@ This release contains bug fixes only and no API changes.
   - `LEDGER_ENTRY_FLAGS`: Maps ledger entry type names to their flags and flag values.
   - `ACCOUNT_SET_FLAGS`: Maps AccountSet flag names (asf flags) to their numeric values.
 
-### Bugfixes in 3.2.0
+### Bugfixes
 
 - Peer Crawler: The `port` field in `overlay.active[]` now consistently returns an integer instead of a string for outbound peers. [#6318](https://github.com/XRPLF/rippled/pull/6318)
 - `ping`: The `ip` field is no longer returned as an empty string for proxied connections without a forwarded-for header. It is now omitted, consistent with the behavior for identified connections. [#6730](https://github.com/XRPLF/rippled/pull/6730)
@@ -85,24 +54,6 @@ This release contains bug fixes only and no API changes.
 - `subscribe`: The `taker` field in the `books` array now returns `actMalformed` instead of `badIssuer` if the value is not a valid account. [#6529](https://github.com/XRPLF/rippled/pull/6529)
 - Fixed a bug in `Forwarded` HTTP header parsing where the extracted IP address could be incorrect when no comma or semicolon delimiter follows the address. This could cause the server to misidentify a client's IP address when operating behind a reverse proxy. [#6529](https://github.com/XRPLF/rippled/pull/6529)
 
-## XRP Ledger server version 3.1.3
-
-[Version 3.1.3](https://github.com/XRPLF/rippled/releases/tag/3.1.3) was released on May 8, 2026.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 3.1.2
-
-[Version 3.1.2](https://github.com/XRPLF/rippled/releases/tag/3.1.2) was released on Mar 12, 2026.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 3.1.1
-
-[Version 3.1.1](https://github.com/XRPLF/rippled/releases/tag/3.1.1) was released on Feb 23, 2026.
-
-This release contains bug fixes only and no API changes.
-
 ## XRP Ledger server version 3.1.0
 
 [Version 3.1.0](https://github.com/XRPLF/rippled/releases/tag/3.1.0) was released on Jan 27, 2026.

BUILD.md

@@ -4,14 +4,34 @@
 
 ## Minimum Requirements
 
-For the hardware needed to run a node, see
-[System Requirements](https://xrpl.org/system-requirements.html).
+See [System Requirements](https://xrpl.org/system-requirements.html).
 
-For the software needed to build xrpld, see the
-[environment setup guide](./docs/build/environment.md).
+Building xrpld generally requires Git, Python, Conan, CMake, and a C++
+compiler.
+
+- [Python](https://www.python.org/downloads/)
+- [Conan](https://conan.io/downloads.html)
+- [CMake](https://cmake.org/download/)
+
+You can verify that the required tools are installed and runnable with:
+
+```bash
+./bin/check-tools.sh
+```
+
+`xrpld` is written in the C++23 dialect. The [tested compiler versions][cpp23-support] are:
+
+| Compiler    | Version         |
+| ----------- | --------------- |
+| GCC         | 15.2            |
+| Clang       | 22              |
+| Apple Clang | 21              |
+| MSVC        | 19.44[^windows] |
 
 ## Operating Systems
 
+Please see the [environment setup guide](./docs/build/environment.md) for detailed instructions for all platforms.
+
 ### Linux
 
 The Ubuntu Linux distribution has received the highest level of quality
@@ -27,8 +47,9 @@ CI testing is done in macOS 26 (Tahoe), but the build defaults `CMAKE_OSX_DEPLOY
 
 ### Windows
 
-Windows is used by some engineers for development only, and is not recommended
-for production use.
+Windows is used by some engineers for development only.
+
+[^windows]: Windows is not recommended for production use.
 
 ## Steps
 
@@ -53,25 +74,37 @@ releases](https://github.com/XRPLF/rippled/releases).
 
 ### Set Up Conan
 
-Once your [development environment](./docs/build/environment.md) is ready, set
-Conan up for this repository:
+After you have a [C++ development environment](./docs/build/environment.md) ready with Git, Python,
+Conan, CMake, and a C++ compiler, you may need to set up your Conan profile.
+
+These instructions assume a basic familiarity with Conan and CMake. If you are
+unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official
+[Getting Started][conan-getting-started] walkthrough.
+
+#### Profiles
+
+We recommend that you install our Conan profiles:
 
 ```bash
-./conan/init.sh
+conan config install conan/profiles/ -tf $(conan config home)/profiles/
 ```
 
-That installs our [`global.conf`](./conan/global.conf), our Conan
-[profiles](./conan/profiles), and the `xrplf` remote that hosts some of our
-dependencies. It honours `CONAN_HOME` and never deletes an existing Conan home,
-so it is safe to re-run — it only overwrites the files it manages.
+You can check your Conan profile by running:
 
-> [!TIP]
-> In the [Nix development shell](./docs/build/nix.md#conan-configuration) this is
-> already done for you: the script runs on entry.
+```bash
+conan profile show
+```
 
-You can inspect the resulting profile with `conan profile show`. If it is not
-suitable for your environment, create a custom profile and pass it to Conan — see
-[Advanced Conan configuration](./docs/build/advanced_conan.md).
+If the default profile is not suitable for your environment, you can create a custom profile and pass it to Conan.
+More information on customizing Conan can be found in the [Advanced Conan configuration](./docs/build/advanced_conan.md).
+
+#### Add xrplf remote
+
+Run the following command to add the `xrplf` remote, which hosts some of our dependencies:
+
+```bash
+conan remote add --index 0 --force xrplf https://conan.xrplf.org/repository/conan/
+```
 
 ### Set Up Ccache
 
@@ -214,17 +247,7 @@ cmake --build . --target setup_code_gen  # create venv and install dependencies
 cmake --build . --target code_gen        # regenerate code
 ```
 
-The same targets are also available as a standalone project, which does not
-need the dependencies to be configured first:
-
-```
-cmake -S cmake/codegen -B build/codegen
-cmake --build build/codegen --target setup_code_gen
-cmake --build build/codegen --target code_gen
-```
-
-The regenerated files should be committed alongside your changes. CI verifies
-that they are up-to-date.
+The regenerated files should be committed alongside your changes.
 
 ## Coverage report
 
@@ -236,14 +259,10 @@ which is only enabled when the `coverage` option is set, e.g. with
 Prerequisites for the coverage report:
 
 - [gcovr tool][gcovr] (can be installed e.g. with [pip][python-pip])
-- `gcov` for GCC or `llvm-cov` for Clang, usually installed with the compiler
+- `gcov` for GCC (installed with the compiler by default) or
+- `llvm-cov` for Clang (installed with the compiler by default)
 - `Debug` build type
 
-> [!NOTE]
-> Clang coverage is not available in the [Nix development shell](./docs/build/nix.md#building-xrpld-in-the-nix-shell):
-> its `clang` shells do not ship `llvm-cov`. Use a `gcc` shell instead (`.#gcc`,
-> or `.#gcc-plain` on Linux), which provides a `gcov` matching its compiler.
-
 A coverage report is created when the following steps are completed, in order:
 
 1. `xrpld` binary built with instrumentation data, enabled by the `coverage`
@@ -304,7 +323,6 @@ See [Sanitizers docs](./docs/build/sanitizers.md) for more details.
 | ---------------- | ------------- | ----------------------------------------------------------------------------- |
 | `assert`         | OFF           | Force enabling assertions.                                                    |
 | `coverage`       | OFF           | Prepare the coverage report.                                                  |
-| `rust`           | OFF           | Build the Rust crates and the C++ code that depends on them.                  |
 | `tests`          | OFF           | Build tests.                                                                  |
 | `unity`          | OFF           | Configure a unity build.                                                      |
 | `verify_headers` | ON            | Make the `verify-headers` target available to compile each header on its own. |
@@ -317,30 +335,6 @@ memory) since they concatenate sources into fewer translation units. Non-unity
 builds may be faster for incremental builds, and can be helpful for detecting
 `#include` omissions.
 
-### Rust crates
-
-The Rust crates in `crates/` are only part of the build when `rust` is ON. With
-`-Drust=OFF` (the default) the `crates` directory is not added to the build, no
-cxxbridge bindings are generated, and the C++ tests that exercise the Rust
-interop are not compiled — so no Rust toolchain is needed. CI builds always pass
-`-Drust=ON`.
-
-With `-Drust=ON` you need one extra dependency: a Rust toolchain (`cargo`,
-`rustc`) matching the channel pinned in
-[`rust-toolchain.toml`](./rust-toolchain.toml), which compiles the crates and
-generates the cxxbridge bindings. It is provided by the
-[Nix development shell](./docs/build/nix.md), so `-Drust=ON` works there without
-any extra setup; otherwise install it as described in
-[Rust](./docs/build/environment.md#rust).
-
-The crates also have their own Rust unit tests. Those are run with `cargo` and
-need only the Rust toolchain, independently of CMake and of the `rust` option
-(CI runs them with `cargo nextest`):
-
-```bash
-cargo test --manifest-path crates/Cargo.toml --workspace
-```
-
 ### Verifying headers
 
 The regular build only compiles `.cpp` files, so a header is only ever checked
@@ -385,14 +379,10 @@ After any updates or changes to dependencies, you may need to do the following:
 4. [Regenerate lockfile](./docs/build/advanced_conan.md#conan-lockfile).
 5. Re-run [conan install](#build-and-test).
 
-If you are using the Nix development shell, whether prebuilt Conan binaries apply
-depends on your platform — see
-[Prebuilt packages](./docs/build/nix.md#prebuilt-packages).
-
 #### ERROR: Package not resolved
 
 If you're seeing an error like `ERROR: Package 'snappy/1.1.10' not resolved: Unable to find 'snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1756234314.246' in remotes.`,
-please [set Conan up](#set-up-conan) so the `xrplf` remote is configured, or re-run `conan export` for [patched recipes](./docs/build/advanced_conan.md#patched-recipes).
+please [add `xrplf` remote](#add-xrplf-remote) or re-run `conan export` for [patched recipes](./docs/build/advanced_conan.md#patched-recipes).
 
 ### `protobuf/port_def.inc` file not found
 
@@ -412,6 +402,7 @@ For example, if you want to build Debug:
 1. For conan install, pass `--settings build_type=Debug`
 2. For cmake, pass `-DCMAKE_BUILD_TYPE=Debug`
 
+[cpp23-support]: https://en.cppreference.com/w/cpp/compiler_support/23
 [conan-getting-started]: https://docs.conan.io/en/latest/getting_started.html
 [unity-build]: https://en.wikipedia.org/wiki/Unity_build
 [gcovr]: https://gcovr.com/en/stable/getting-started.html

CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

CMakeLists.txt

@@ -140,25 +140,6 @@ if(rocksdb)
     target_link_libraries(xrpl_libs INTERFACE RocksDB::rocksdb)
 endif()
 
-# OpenTelemetry distributed tracing (optional).
-# When on, links against opentelemetry-cpp and defines XRPL_ENABLE_TELEMETRY so
-# that SpanGuard factory methods produce real OTel spans.
-# When off, all tracing code compiles to no-ops with zero overhead and
-# opentelemetry-cpp is not needed at all.
-#
-# There is no CMake option. The one switch is `conan install -o telemetry=`,
-# which decides whether opentelemetry-cpp is fetched and sets the variable read
-# below through the generated toolchain.
-#
-# -DXRPL_ENABLE_TELEMETRY=OFF turns nothing off: that name is only a compile
-# definition added below, so CMake lists it as an unused variable at the end of
-# configuration.
-if(telemetry)
-    find_package(opentelemetry-cpp CONFIG REQUIRED)
-    add_compile_definitions(XRPL_ENABLE_TELEMETRY)
-    message(STATUS "OpenTelemetry tracing enabled")
-endif()
-
 # Work around changes to Conan recipe for now.
 if(TARGET nudb::core)
     set(nudb nudb::core)
@@ -177,19 +158,11 @@ if(coverage)
     include(XrplCov)
 endif()
 
-add_custom_target(tidy_prerequisites)
-
-if(rust)
-    add_subdirectory(crates)
-endif()
 include(XrplCore)
-
 include(XrplProtocolAutogen)
 include(XrplInstall)
-include(XrplValidatorKeys)
-# Must come after XrplValidatorKeys: the 'package' target depends on the
-# validator-keys target existing.
 include(XrplPackaging)
+include(XrplValidatorKeys)
 
 if(tests)
     include(CTest)

CONTRIBUTING.md

@@ -59,17 +59,6 @@ to an existing XLS. Neither change will be released (in an amendment's
 case, marked as `Supported::yes`) until the corresponding XLS's status
 is `Final`.
 
-## AI coding agents
-
-[`AGENTS.md`](./AGENTS.md) (and its `CLAUDE.md` symlink, for Claude Code) holds shared, checked-in guidance for AI coding agents working in this repository — build/test/lint commands and architecture notes. Additional `AGENTS.md` files may exist in subdirectories to give agents context specific to that part of the codebase; whenever you add one, also add a `CLAUDE.md` symlink pointing to it (`ln -s AGENTS.md CLAUDE.md`) so Claude Code picks it up too.
-
-If you want to give an agent personal instructions that shouldn't be shared with other contributors (e.g. your own workflow preferences), those are gitignored, not checked in:
-
-- `CLAUDE.local.md` — read by Claude Code alongside `CLAUDE.md`.
-- `AGENTS.override.md` — read by AGENTS.md-compatible tools that support a personal override file layered on top of `AGENTS.md`.
-
-Likewise, `.claude/settings.local.json` is for personal, untracked Claude Code settings, while `.claude/settings.json` is shared.
-
 ## Before making a pull request
 
 (Or marking a draft pull request as ready.)
@@ -93,7 +82,7 @@ If you create new source files, they must be organized as follows:
   under `include/xrpl`, and source (`.cpp`) files must go under
   `src/libxrpl`.
 - All other non-test files must go under `src/xrpld`.
-- New test source files should use `gtest` and go under `src/tests`, unless that isn't possible, in which case they should use our legacy test framework and go under `src/test`.
+- All test source files must go under `src/test`.
 - All benchmark source files must go under `src/benchmarks`.
 
 The source must be formatted according to the style guide below. The easiest
@@ -236,9 +225,8 @@ environment, so you don't need to install most of the individual tools
 yourself. The version of each hook sourced from an external repository
 (`clang-format`, `gersemi`, etc.) is pinned in that file, so running the hooks
 locally uses exactly the same versions as CI. A few `local` hooks — most notably
-`clang-tidy` and `cargo fmt` — run tools from your own environment; see
-[Installing clang-tidy](#installing-clang-tidy) and
-[Rust](./docs/build/environment.md#rust) for how to get those.
+`clang-tidy` — run tools from your own environment; see
+[Installing clang-tidy](#installing-clang-tidy) for how to get those.
 
 To get started, install `pre-commit` and enable the git hook scripts:
 
@@ -267,7 +255,6 @@ The hooks configured in this repository include, among others:
 - `clang-tidy` — C++ static analysis (see [Clang-tidy](#clang-tidy)); opt in with `TIDY=1`
 - `fix-include-style`, `fix-pragma-once`, `check-doxygen-style` — C++ hygiene
 - `gersemi` — CMake formatting
-- `cargo fmt` — Rust formatting for the crates in `crates/`
 - `prettier`, `black`, `shfmt` — formatting for JavaScript/JSON/Markdown, Python, and shell
 - `cspell` — spell checking
 
@@ -332,11 +319,7 @@ See the [environment setup guide](./docs/build/environment.md#clang-tidy) for ho
 
 ### Running clang-tidy locally
 
-Before running clang-tidy, you must generate the files it depends on (protobuf headers, and, when the project is configured with `-Drust=ON`, the cxxbridge headers from the Rust crates). Configure the project as described in [`BUILD.md`](./BUILD.md), then build the `tidy_prerequisites` target, which generates all of them:
-
-```bash
-cmake --build build --target tidy_prerequisites
-```
+Before running clang-tidy, you must build the project to generate required files (particularly protobuf headers). Refer to [`BUILD.md`](./BUILD.md) for build instructions.
 
 #### Via pre-commit (recommended)
 
@@ -373,97 +356,6 @@ run-clang-tidy -p build -quiet -fix -format -allow-no-checks src tests
 
 `-format` reformats the fixed code with [`.clang-format`](./.clang-format); without it the fixes are inserted in LLVM style and the `clang-format` hook rewrites them afterwards.
 
-## Telemetry span attribute naming
-
-OpenTelemetry span attribute keys follow these rules so they stay consistent
-across the code, the OTel collector, Tempo, Grafana dashboards, and docs. The
-constants in the `*SpanNames.h` headers are the single source of truth; every
-other layer must match them. A CI check enforces this end to end.
-
-1. Per-span unique attribute: bare field name — allowed when the field is
-   recorded by a single span/workflow, so the span name already supplies the
-   domain (e.g. `command`, `local`, `version` on `rpc.command` / `tx.process`).
-2. Shared attribute (same concept on more than one span): ONE key, reused
-   verbatim on every span that records it — the span name tells the occurrences
-   apart, so no per-emitter prefix is added. Pick the name by the field's
-   meaning: a property of a domain object keeps that object's bare field name
-   (`ledger_hash`, `ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a
-   field already qualified by a sub-kind keeps that qualifier on every emitter
-   (`proposal_trusted` on both `consensus.proposal.receive` and
-   `peer.proposal.receive`; `validation_trusted` likewise). Define it once in
-   the base `SpanNames.h` `namespace attr` block and re-export (`using`) it from
-   each domain header, so all emitters share the exact string.
-3. Collision qualifier: `<domain>_<field>` — only when a bare name would collide
-   with a DIFFERENT concept in the shared spanmetrics label space, or with the
-   OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
-   `consensus_phase`, `consensus_round`). This disambiguates distinct concepts
-   that share a word; it is NOT used to tag the same concept with the workflow
-   that emitted it — that is rule 2 (one shared name).
-4. Resource attribute: dotted `xrpl.<subsystem>.<field>` — reserved ONLY for
-   process/network identity set once at startup (`xrpl.network.id`,
-   `xrpl.network.type`). Never use the dotted `xrpl.` form for span attributes.
-5. Span names use `<subsystem>[.<component>]` (dotted). Only attribute _keys_
-   follow rules 1–4.
-
-All attribute keys are `lower_snake_case` (lowercase letters, digits, and
-underscores; each dot-separated segment of a resource key likewise). No
-camelCase, uppercase, or spaces.
-
-Standard OpenTelemetry semantic-convention keys keep their canonical dotted
-form (e.g. `service.*` resource attributes, `http.*` span attributes); the
-"no dotted form" rule above applies to xrpl-custom keys, not to OTel-standard
-conventions.
-
-Always reference the `*SpanNames.h` constants for attribute keys and span
-names — never pass a string literal as a key or as a `span`/`childSpan` name
-argument. (Attribute _values_ may be runtime data.)
-
-These rules are enforced by `.github/scripts/otel-naming/check_otel_naming.py`,
-run in CI on every pull request. The check derives the set of valid keys
-directly from the `*SpanNames.h` constants and the resource attributes the code
-registers, so there is no separate list to keep in sync. It cross-validates the
-collector, Tempo, dashboards, and docs against those keys, and each rule runs
-only when the file it needs is present — so it works whether telemetry changes
-land in one pull request or several. Run it locally with:
-
-```
-python .github/scripts/otel-naming/check_otel_naming.py
-```
-
-### Naming a wrong form in prose (`otel-naming:allow-dotted`)
-
-The doc rule (E) flags any dotted `` `xrpl.<domain>.<field>` `` key in the
-telemetry docs, because a reader copies those keys straight into a TraceQL or
-PromQL query. A doc that _teaches_ the convention, or records a rename, has to be
-able to name the wrong form as a counter-example. That mention is opted out with
-a marker naming exactly the keys the line is allowed to mention:
-
-```markdown
-Use `tx_hash`, not `xrpl.tx.hash`.
-<!-- otel-naming:allow-dotted: xrpl.tx.hash -->
-```
-
-- The marker applies to **its own line only**, and exempts **only the keys it
-  lists** (comma- and/or space-separated, backticks optional). A dotted key on a
-  marked line that the marker does not name still fails, so an exemption cannot
-  quietly widen when someone edits the line later.
-- A marker with no key list exempts nothing and reports a warning; so does a
-  marker naming a key the line no longer mentions (a stale exemption).
-- Never use it to keep a real attribute table dotted. If the doc publishes a key
-  an operator is meant to query, fix the key — the marker is for mentions, not
-  for published attributes.
-
-See [.github/scripts/otel-naming/README.md](.github/scripts/otel-naming/README.md)
-for the full rule list.
-
-## Adding a new OTel metric
-
-See `include/xrpl/telemetry/MetricMacros.h` for the call-site macros covering every
-OTel instrument kind (Counter, UpDownCounter, Histogram, Gauge, and their
-Observable/async counterparts) and the "Adding a New Metric" section in
-[docs/telemetry-runbook.md](docs/telemetry-runbook.md) for the walkthrough and a
-need-to-macro lookup table.
-
 ## Contracts and instrumentation
 
 We are using [Antithesis](https://antithesis.com/) for continuous fuzzing,

OpenTelemetryPlan/00-tracing-fundamentals.md

@@ -1,569 +0,0 @@
-# Distributed Tracing Fundamentals
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Next**: [Architecture Analysis](./01-architecture-analysis.md)
-
----
-
-## What is Distributed Tracing?
-
-Distributed tracing is a method for tracking data objects as they flow through distributed systems. In a network like XRP Ledger, a single transaction touches multiple independent nodes—each with no shared memory or logging. Distributed tracing connects these dots.
-
-**Without tracing:** You see isolated logs on each node with no way to correlate them.
-
-**With tracing:** You see the complete journey of a transaction or an event across all nodes it touched.
-
----
-
-## Actors and Actions at a Glance
-
-### Actors
-
-| Who (Plain English)                            | Technical Term  |
-| ---------------------------------------------- | --------------- |
-| A single unit of work being tracked            | Span            |
-| The complete journey of a request              | Trace           |
-| Data that links spans across services          | Trace Context   |
-| Code that creates spans and propagates context | Instrumentation |
-| Service that receives and processes traces     | Collector       |
-| Storage and visualization system               | Backend (Tempo) |
-| Decision logic for which traces to keep        | Sampler         |
-
-### Actions
-
-| What Happens (Plain English)            | Technical Term          |
-| --------------------------------------- | ----------------------- |
-| Start tracking a new operation          | Create a Span           |
-| Connect a child operation to its parent | Set `parent_span_id`    |
-| Group all related operations together   | Share a `trace_id`      |
-| Pass tracking data between services     | Context Propagation     |
-| Decide whether to record a trace        | Sampling (Head or Tail) |
-| Send completed traces to storage        | Export (OTLP)           |
-
----
-
-## Core Concepts
-
-### 1. Trace
-
-A **trace** represents the entire journey of a request through the system. It has a unique `trace_id` that stays constant across all nodes.
-
-```
-Trace ID: abc123
-├── Node A: received transaction
-├── Node B: relayed transaction
-├── Node C: included in consensus
-└── Node D: applied to ledger
-```
-
-### 2. Span
-
-A **span** represents a single unit of work within a trace. Each span has:
-
-| Attribute        | Description                      | Example                    |
-| ---------------- | -------------------------------- | -------------------------- |
-| `trace_id`       | Identifies the trace             | `event123`                 |
-| `span_id`        | Unique identifier                | `span456`                  |
-| `parent_span_id` | Parent span (if any)             | `p_span123`                |
-| `name`           | Operation name                   | `rpc.submit`               |
-| `start_time`     | When work began (local time)     | `2024-01-15T10:30:00Z`     |
-| `end_time`       | When work completed (local time) | `2024-01-15T10:30:00.050Z` |
-| `attributes`     | Key-value metadata               | `tx_hash=ABC...`           |
-| `status`         | OK, ERROR MSG                    | `OK`                       |
-
-### 3. Trace Context
-
-**Trace context** is the data that propagates between services to link spans together. It contains:
-
-- `trace_id` - The trace this span belongs to
-- `span_id` - The current span (becomes parent for child spans)
-- `trace_flags` - Sampling decisions
-
----
-
-## How Spans Form a Trace
-
-Spans have parent-child relationships forming a tree structure:
-
-```mermaid
-flowchart TB
-    subgraph trace["Trace: abc123"]
-        A["tx.submit<br/>span_id: 001<br/>50ms"] --> B["tx.validate<br/>span_id: 002<br/>5ms"]
-        A --> C["tx.relay<br/>span_id: 003<br/>10ms"]
-        A --> D["tx.apply<br/>span_id: 004<br/>30ms"]
-        D --> E["ledger.update<br/>span_id: 005<br/>20ms"]
-    end
-
-    style A fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style B fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style D fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style E fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **tx.submit (blue, root)**: The top-level span representing the entire transaction submission; all other spans are its descendants.
-- **tx.validate, tx.relay, tx.apply (green)**: Direct children of tx.submit, representing the three main stages -- validation, relay to peers, and application to the ledger.
-- **ledger.update (red)**: A grandchild span nested under tx.apply, representing the actual ledger state mutation triggered by applying the transaction.
-- **Arrows (parent to child)**: Each arrow indicates a parent-child span relationship where the parent's completion depends on the child finishing.
-
-The same trace visualized as a **timeline (Gantt chart)**:
-
-```
-Time →   0ms    10ms    20ms    30ms    40ms    50ms
-         ├───────────────────────────────────────────┤
-tx.submit│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-         ├─────┤
-tx.valid │▓▓▓▓▓│
-         │     ├──────────┤
-tx.relay │     │▓▓▓▓▓▓▓▓▓▓│
-         │               ├────────────────────────────┤
-tx.apply │               │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-         │                         ├──────────────────┤
-ledger   │                         │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-```
-
----
-
-## Span Relationships
-
-Spans don't always form simple parent-child trees. Distributed tracing defines several relationship types to capture different causal patterns:
-
-### 1. Parent-Child (ChildOf)
-
-The default relationship. The parent span **depends on** or **contains** the child span. The child runs within the scope of the parent.
-
-```
-tx.submit (parent)
-├── tx.validate (child)     ← parent waits for this
-├── tx.relay (child)        ← parent waits for this
-└── tx.apply (child)        ← parent waits for this
-```
-
-**When to use:** Synchronous calls, nested operations, any case where the parent's completion depends on the child.
-
-### 2. Follows-From
-
-A causal relationship where the first span **triggers** the second, but does **not wait** for it. The originator fires and moves on.
-
-```
-Time →
-
-tx.receive [=======]
-                     ↓ triggers (follows-from)
-              tx.relay   [===========]   ← runs independently
-```
-
-**When to use:** Asynchronous jobs, queued work, fire-and-forget patterns. For example, a node receives a transaction and queues it for relay — the relay span _follows from_ the receive span but the receiver doesn't wait for relaying to complete.
-
-> **OpenTracing** defined `FollowsFrom` as a first-class reference type alongside `ChildOf`.
-> **OpenTelemetry** represents this using **Span Links** with descriptive attributes instead (see below).
-
-### 3. Span Links (Cross-Trace and Non-Hierarchical)
-
-Links connect spans that are **causally related but not in a parent-child hierarchy**. Unlike parent-child, links can cross trace boundaries.
-
-```
-Trace A                          Trace B
-──────                           ──────
-batch.schedule                   batch.execute
-├─ item.enqueue (span X)    ┌──► process.item
-├─ item.enqueue (span Y) ───┤    (links to X, Y, Z)
-├─ item.enqueue (span Z)    └──►
-```
-
-**Use cases:**
-
-| Pattern              | Description                                                                 |
-| -------------------- | --------------------------------------------------------------------------- |
-| **Batch processing** | A batch span links back to all individual spans that contributed to it      |
-| **Fan-in**           | An aggregation span links to the multiple producer spans it merges          |
-| **Fan-out**          | Multiple downstream spans link back to the single span that triggered them  |
-| **Async handoff**    | A deferred job links back to the request that queued it (follows-from)      |
-| **Cross-trace**      | Correlating spans across independent traces (e.g., retries, related events) |
-
-**Link structure:** Each link carries the target span's context plus optional attributes:
-
-```
-Link {
-    trace_id:   <target trace>
-    span_id:    <target span>
-    attributes: { "link.description": "triggered by batch scheduler" }
-}
-```
-
-### Relationship Summary
-
-```mermaid
-flowchart LR
-    subgraph parent_child["Parent-Child"]
-        direction TB
-        P["Parent"] --> C["Child"]
-    end
-
-    subgraph follows_from["Follows-From"]
-        direction TB
-        A["Span A"] -.->|triggers| B["Span B"]
-    end
-
-    subgraph links["Span Links"]
-        direction TB
-        X["`Span X
-(Trace 1)`"] -.-|link| Y["`Span Y
-(Trace 2)`"]
-    end
-
-    parent_child ~~~ follows_from ~~~ links
-
-    style P fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style C fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style A fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style B fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style X fill:#4a148c,stroke:#38006b,color:#ffffff
-    style Y fill:#4a148c,stroke:#38006b,color:#ffffff
-```
-
-| Relationship     | Same Trace? | Dependency?                | OTel Mechanism    |
-| ---------------- | ----------- | -------------------------- | ----------------- |
-| **Parent-Child** | Yes         | Parent depends on child    | `parent_span_id`  |
-| **Follows-From** | Usually     | Causal but no dependency   | Link + attributes |
-| **Span Link**    | Either      | Correlation, no dependency | Link + attributes |
-
----
-
-## Trace ID Generation
-
-A `trace_id` is a 128-bit (16-byte) identifier that groups all spans belonging to one logical operation. How it's generated determines how easily you can find and correlate traces later.
-
-### General Approaches
-
-#### 1. Random (W3C Default)
-
-Generate a random 128-bit ID when a trace starts. Standard approach for most services.
-
-```
-trace_id = random_128_bits()
-```
-
-| Pros                        | Cons                                          |
-| --------------------------- | --------------------------------------------- |
-| Simple, standard            | No natural correlation to domain events       |
-| Guaranteed unique per trace | If propagation is lost, trace is broken       |
-| Works with all OTel tooling | "Find trace for TX abc" requires index lookup |
-
-#### 2. Deterministic (Derived from Domain Data)
-
-Compute the trace_id from a hash of a natural identifier. Every node independently derives the **same** trace_id for the same event.
-
-```
-trace_id = SHA-256(domain_identifier)[0:16]   // truncate to 128 bits
-```
-
-| Pros                                                | Cons                                                       |
-| --------------------------------------------------- | ---------------------------------------------------------- |
-| Propagation-resilient — same ID computed everywhere | Same event processed twice (retry) shares trace_id         |
-| Natural search — domain ID maps directly to trace   | Non-standard (tooling assumes random)                      |
-| No coordination needed between nodes                | 256→128 bit truncation (collision risk negligible at ~2⁶⁴) |
-
-#### 3. Hybrid (Deterministic Prefix + Random Suffix)
-
-First 8 bytes derived from domain data, last 8 bytes random.
-
-```
-trace_id = SHA-256(domain_identifier)[0:8] || random_64_bits()
-```
-
-| Pros                                        | Cons                                     |
-| ------------------------------------------- | ---------------------------------------- |
-| Prefix search: "find all traces for TX abc" | Must propagate to maintain full trace_id |
-| Unique per processing instance              | More complex generation logic            |
-| Retries get distinct trace_ids              | Partial correlation only (prefix match)  |
-
-### XRPL Workflow Analysis
-
-XRPL has a unique advantage: its core workflows produce **globally unique 256-bit hashes** that are known on every node. This makes deterministic trace_id generation practical in ways most systems can't achieve.
-
-#### Natural Identifiers by Workflow
-
-| Workflow            | Natural Identifier                | Size       | Known at Start?               | Same on All Nodes?               |
-| ------------------- | --------------------------------- | ---------- | ----------------------------- | -------------------------------- |
-| **Transaction**     | Transaction hash (`tid_`)         | 256-bit    | Yes — computed before signing | Yes — hash of canonical tx data  |
-| **Consensus round** | Previous ledger hash + ledger seq | 256+32 bit | Yes — known when round opens  | Yes — all validators agree       |
-| **Validation**      | Ledger hash being validated       | 256-bit    | Yes — from consensus result   | Yes — same closed ledger         |
-| **Ledger catch-up** | Target ledger hash                | 256-bit    | Yes — we know what to fetch   | Yes — identifies ledger globally |
-
-#### Where These Identifiers Live in Code
-
-```
-Transaction:     STTx::getTransactionID()     → uint256 tid_
-                 TMTransaction::rawTransaction → recompute hash from bytes
-
-Consensus:       ConsensusProposal::previousLedger_ → uint256 (previous ledger hash)
-                 ConsensusProposal::position_       → uint256 (TxSet hash)
-                 LedgerHeader::seq                  → uint32_t (ledger sequence)
-
-Validation:      STValidation::getLedgerHash()  → uint256
-                 STValidation::getNodeID()      → NodeID (160-bit)
-
-Ledger fetch:    InboundLedger constructor      → uint256 hash, uint32_t seq
-                 TMGetLedger::ledgerHash        → bytes (uint256)
-```
-
-### Recommended Strategy: Workflow-Scoped Deterministic
-
-Each workflow type derives its trace_id from its natural domain identifier:
-
-```
-Transaction trace:   trace_id = SHA-256("tx"    || tx_hash)[0:16]
-Consensus trace:     trace_id = SHA-256("cons"  || prev_ledger_hash || ledger_seq)[0:16]
-Ledger catch-up:     trace_id = SHA-256("fetch" || target_ledger_hash)[0:16]
-```
-
-The string prefix (`"tx"`, `"cons"`, `"fetch"`) prevents collisions between workflows that might share underlying hashes.
-
-**Why this works for XRPL:**
-
-1. **Propagation-resilient** — Even if a P2P message drops trace context, every node independently computes the same trace_id from the same tx_hash or ledger_hash. Spans still correlate.
-
-2. **Zero-cost search** — "Show me the trace for transaction ABC" becomes a direct lookup: compute `SHA-256("tx" || ABC)[0:16]` and query. No secondary index needed.
-
-3. **Cross-workflow linking via Span Links** — A consensus trace links to individual transaction traces. A validation span links to the consensus trace. This connects the full picture without forcing everything into one giant trace.
-
-### Cross-Workflow Correlation
-
-Each workflow gets its own trace. Span Links tie them together:
-
-```mermaid
-flowchart TB
-    subgraph tx_trace["Transaction Trace"]
-        direction LR
-        Tn["trace_id = f(tx_hash)"]:::note --> T1["tx.receive"] --> T2["tx.validate"] --> T3["tx.relay"]
-    end
-
-    subgraph cons_trace["Consensus Trace"]
-        direction LR
-        Cn["trace_id = f(prev_ledger, seq)"]:::note --> C1["cons.open"] --> C2["cons.propose"] --> C3["cons.accept"]
-    end
-
-    subgraph val_trace["Validation"]
-        direction LR
-        Vn["spans within consensus trace"]:::note --> V1["val.create"] --> V2["val.broadcast"]
-    end
-
-    subgraph fetch_trace["Catch-Up Trace"]
-        direction LR
-        Fn["trace_id = f(ledger_hash)"]:::note --> F1["fetch.request"] --> F2["fetch.receive"] --> F3["fetch.apply"]
-    end
-
-    C1 -.-|"`span link
-(tx traces)`"| T3
-    C3 --> V1
-    F1 -.-|"`span link
-(target ledger)`"| C3
-
-    classDef note fill:none,stroke:#888,stroke-dasharray:5 5,color:#333,font-style:italic
-    style T1 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style T2 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style T3 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style C1 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C2 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C3 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style V1 fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style V2 fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style F1 fill:#4a148c,stroke:#38006b,color:#ffffff
-    style F2 fill:#4a148c,stroke:#38006b,color:#ffffff
-    style F3 fill:#4a148c,stroke:#38006b,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **Transaction Trace (blue)**: An independent trace whose `trace_id` is deterministically derived from the transaction hash. Contains receive, validate, and relay spans.
-- **Consensus Trace (green)**: An independent trace whose `trace_id` is derived from the previous ledger hash and sequence number. Covers the open, propose, and accept phases.
-- **Validation (red)**: Validation spans live within the consensus trace (not a separate trace). They are created after the accept phase completes.
-- **Catch-Up Trace (purple)**: An independent trace for ledger acquisition, derived from the target ledger hash. Used when a node is behind and fetching missing ledgers.
-- **Dotted arrows (span links)**: Cross-trace correlations. Consensus links to transaction traces it included; catch-up links to the consensus trace that produced the target ledger.
-- **Solid arrow (C3 to V1)**: A parent-child relationship -- validation spans are direct children of the consensus accept span within the same trace.
-
-**How a query flows:**
-
-```
-"Why was TX abc slow?"
-  1. Compute trace_id = SHA-256("tx" || abc)[0:16]
-  2. Find transaction trace → see it was included in consensus round N
-  3. Follow span link → consensus trace for round N
-  4. See which phase was slow (propose? accept?)
-  5. If a node was catching up, follow link → catch-up trace
-```
-
-### Trade-offs to Consider
-
-| Concern                       | Mitigation                                                                                                                    |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| **Retries get same trace_id** | Add `attempt` attribute to root span; spans have unique span_ids and timestamps                                               |
-| **256→128 bit truncation**    | Birthday-bound collision at ~2⁶⁴ operations — negligible for XRPL's throughput                                                |
-| **Non-standard generation**   | OTel spec allows any 16-byte non-zero value; tooling works on the hex string                                                  |
-| **Hash computation cost**     | SHA-256 is ~0.3μs per call; XRPL already computes these hashes for other purposes                                             |
-| **Late-binding identifiers**  | Ledger hash isn't known until after consensus — validation spans use ledger_seq as fallback, then link to the consensus trace |
-
----
-
-## Distributed Traces Across Nodes
-
-In distributed systems like xrpld, traces span **multiple independent nodes**. The trace context must be propagated in network messages:
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant NodeA as Node A
-    participant NodeB as Node B
-    participant NodeC as Node C
-
-    Client->>NodeA: Submit TX<br/>(no trace context)
-
-    Note over NodeA: Creates new trace<br/>trace_id: abc123<br/>span: tx.receive
-
-    NodeA->>NodeB: Relay TX<br/>(trace_id: abc123, parent: 001)
-
-    Note over NodeB: Creates child span<br/>span: tx.relay<br/>parent_span_id: 001
-
-    NodeA->>NodeC: Relay TX<br/>(trace_id: abc123, parent: 001)
-
-    Note over NodeC: Creates child span<br/>span: tx.relay<br/>parent_span_id: 001
-
-    Note over NodeA,NodeC: All spans share trace_id: abc123<br/>enabling correlation across nodes
-```
-
-**Reading the diagram:**
-
-- **Client**: The external entity that submits a transaction. It does not carry trace context -- the trace originates at the first node.
-- **Node A**: The entry point that creates a new trace (trace_id: abc123) and the root span `tx.receive`. It relays the transaction to peers with trace context attached.
-- **Node B and Node C**: Peer nodes that receive the relayed transaction along with the propagated trace context. Each creates a child span under Node A's span, preserving the same `trace_id`.
-- **Arrows with trace context**: The relay messages carry `trace_id` and `parent_span_id`, allowing each downstream node to link its spans back to the originating span on Node A.
-
----
-
-## Context Propagation
-
-For traces to work across nodes, **trace context must be propagated** in messages.
-
-### What's in the Context (~26 bytes)
-
-| Field         | Size     | Description                                             |
-| ------------- | -------- | ------------------------------------------------------- |
-| `trace_id`    | 16 bytes | Identifies the entire trace (constant across all nodes) |
-| `span_id`     | 8 bytes  | The sender's current span (becomes parent on receiver)  |
-| `trace_flags` | 1 byte   | Sampling decision (bit 0 = sampled; bits 1-7 reserved)  |
-| `trace_state` | variable | Optional vendor-specific data (typically omitted)       |
-
-### How span_id Changes at Each Hop
-
-Only **one** `span_id` travels in the context - the sender's current span. Each node:
-
-1. Extracts the received `span_id` and uses it as the `parent_span_id`
-2. Creates a **new** `span_id` for its own span
-3. Sends its own `span_id` as the parent when forwarding
-
-```
-Node A                      Node B                      Node C
-──────                      ──────                      ──────
-
-Span AAA                    Span BBB                    Span CCC
-   │                           │                           │
-   ▼                           ▼                           ▼
-Context out:                Context out:                Context out:
-├─ trace_id: abc123         ├─ trace_id: abc123         ├─ trace_id: abc123
-├─ span_id: AAA ──────────► ├─ span_id: BBB ──────────► ├─ span_id: CCC ──────►
-└─ flags: 01                └─ flags: 01                └─ flags: 01
-                               │                           │
-                          parent = AAA               parent = BBB
-```
-
-The `trace_id` stays constant, but `span_id` **changes at every hop** to maintain the parent-child chain.
-
-### Propagation Formats
-
-There are two patterns:
-
-### HTTP/RPC Headers (W3C Trace Context)
-
-```
-traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
-             │  │                                │                │
-             │  │                                │                └── Flags (sampled)
-             │  │                                └── Parent span ID (16 hex)
-             │  └── Trace ID (32 hex)
-             └── Version
-```
-
-### Protocol Buffers (xrpld P2P messages)
-
-xrpld P2P messages such as `TMTransaction` carry the trace context in two added byte fields alongside the existing payload: `trace_parent` holds the W3C traceparent (`trace_id`, `span_id`, and `trace_flags`), and `trace_state` holds the optional W3C tracestate. Together they propagate the trace across the P2P boundary so a receiving node can attach its spans to the sender's span.
-
----
-
-## Sampling
-
-Not every trace needs to be recorded. **Sampling** reduces overhead:
-
-### Head Sampling (at trace start)
-
-```
-Request arrives → Random N% chance → Record or skip entire trace
-```
-
-- ✅ Low overhead
-- ❌ May miss interesting traces
-
-> **xrpld note**: xrpld intentionally fixes head sampling at 100% (sample
-> everything) and does not expose a configurable ratio. A per-node ratio
-> would let different nodes make divergent keep/drop decisions for the same
-> distributed trace, producing broken/partial traces. xrpld uses a
-> `ParentBased` sampler so spans with a remote parent honor the upstream
-> decision. Volume reduction is delegated to collector-side tail sampling.
-
-### Tail Sampling (after trace completes)
-
-```
-Trace completes → Collector evaluates:
-                  - Error? → KEEP
-                  - Slow? → KEEP
-                  - Normal? → Sample 10%
-```
-
-- ✅ Never loses important traces
-- ❌ Higher memory usage at collector
-
----
-
-## Key Benefits for xrpld
-
-| Challenge                          | How Tracing Helps                        |
-| ---------------------------------- | ---------------------------------------- |
-| "Where is my transaction?"         | Follow trace across all nodes it touched |
-| "Why was consensus slow?"          | See timing breakdown of each phase       |
-| "Which node is the bottleneck?"    | Compare span durations across nodes      |
-| "What happened during the outage?" | Correlate errors across the network      |
-
----
-
-## Glossary
-
-| Term                 | Definition                                                          |
-| -------------------- | ------------------------------------------------------------------- |
-| **Trace**            | Complete journey of a request, identified by `trace_id`             |
-| **Span**             | Single operation within a trace                                     |
-| **Parent-Child**     | Span relationship where the parent depends on the child             |
-| **Follows-From**     | Causal relationship where originator doesn't wait for the result    |
-| **Span Link**        | Non-hierarchical connection between spans, possibly across traces   |
-| **Deterministic ID** | Trace ID derived from domain data (e.g., tx_hash) instead of random |
-| **Context**          | Data propagated between services (`trace_id`, `span_id`, flags)     |
-| **Instrumentation**  | Code that creates spans and propagates context                      |
-| **Collector**        | Service that receives, processes, and exports traces                |
-| **Backend**          | Storage/visualization system (Tempo)                                |
-| **Head Sampling**    | Sampling decision at trace start                                    |
-| **Tail Sampling**    | Sampling decision after trace completes                             |
-
----
-
-_Next: [Architecture Analysis](./01-architecture-analysis.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/01-architecture-analysis.md

@@ -1,467 +0,0 @@
-# Architecture Analysis
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Design Decisions](./02-design-decisions.md) | [Implementation Strategy](./03-implementation-strategy.md)
-
----
-
-## 1.1 Current xrpld Architecture Overview
-
-> **WS** = WebSocket | **UNL** = Unique Node List | **TxQ** = Transaction Queue | **StatsD** = Statistics Daemon
-
-The xrpld node software consists of several interconnected components that need instrumentation for distributed tracing:
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Node"]
-        subgraph services["Core Services"]
-            RPC["RPC Server<br/>(HTTP/WS/gRPC)"]
-            Overlay["Overlay<br/>(P2P Network)"]
-            Consensus["Consensus<br/>(RCLConsensus)"]
-            ValidatorList["ValidatorList<br/>(UNL Mgmt)"]
-        end
-
-        JobQueue["JobQueue<br/>(Thread Pool)"]
-
-        subgraph processing["Processing Layer"]
-            NetworkOPs["NetworkOPs<br/>(Tx Processing)"]
-            LedgerMaster["LedgerMaster<br/>(Ledger Mgmt)"]
-            NodeStore["NodeStore<br/>(Database)"]
-            InboundLedgers["InboundLedgers<br/>(Ledger Sync)"]
-        end
-
-        subgraph appservices["Application Services"]
-            PathFind["PathFinding<br/>(Payment Paths)"]
-            TxQ["TxQ<br/>(Fee Escalation)"]
-            LoadMgr["LoadManager<br/>(Fee/Load)"]
-        end
-
-        subgraph observability["Existing Observability"]
-            PerfLog["PerfLog<br/>(JSON)"]
-            Insight["Insight<br/>(StatsD)"]
-            Logging["Logging<br/>(Journal)"]
-        end
-
-        services --> JobQueue
-        JobQueue --> processing
-        JobQueue --> appservices
-    end
-
-    style xrpld fill:#424242,stroke:#212121,color:#ffffff
-    style services fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style processing fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style appservices fill:#6a1b9a,stroke:#4a148c,color:#ffffff
-    style observability fill:#e65100,stroke:#bf360c,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **Core Services (blue)**: The entry points into xrpld -- RPC Server handles client requests, Overlay manages peer-to-peer networking, Consensus drives agreement, and ValidatorList manages trusted validators.
-- **JobQueue (center)**: The asynchronous thread pool that decouples Core Services from the Processing and Application layers. All work flows through it.
-- **Processing Layer (green)**: Core business logic -- NetworkOPs processes transactions, LedgerMaster manages ledger state, NodeStore handles persistence, and InboundLedgers synchronizes missing data.
-- **Application Services (purple)**: Higher-level features -- PathFinding computes payment routes, TxQ manages fee-based queuing, and LoadManager tracks server load.
-- **Existing Observability (orange)**: The current monitoring stack (PerfLog, Insight, Journal logging) that OpenTelemetry will complement, not replace.
-- **Arrows (Services to JobQueue to layers)**: Work originates at Core Services, is enqueued onto the JobQueue, and dispatched to Processing or Application layers for execution.
-
----
-
-## 1.1.1 Actors and Actions
-
-### Actors
-
-| Who (Plain English)                       | Technical Term             |
-| ----------------------------------------- | -------------------------- |
-| Network node running XRPL software        | xrpld node                 |
-| External client submitting requests       | RPC Client                 |
-| Network neighbor sharing data             | Peer (PeerImp)             |
-| Request handler for client queries        | RPC Server (ServerHandler) |
-| Command executor for specific RPC methods | RPCHandler                 |
-| Agreement process between nodes           | Consensus (RCLConsensus)   |
-| Transaction processing coordinator        | NetworkOPs                 |
-| Background task scheduler                 | JobQueue                   |
-| Ledger state manager                      | LedgerMaster               |
-| Payment route calculator                  | PathFinding (Pathfinder)   |
-| Transaction waiting room                  | TxQ (Transaction Queue)    |
-| Fee adjustment system                     | LoadManager                |
-| Trusted validator list manager            | ValidatorList              |
-| Protocol upgrade tracker                  | AmendmentTable             |
-| Ledger state hash tree                    | SHAMap                     |
-| Persistent key-value storage              | NodeStore                  |
-
-### Actions
-
-| What Happens (Plain English)                   | Technical Term         |
-| ---------------------------------------------- | ---------------------- |
-| Client sends a request to a node               | `rpc.request`          |
-| Node executes a specific RPC command           | `rpc.command.*`        |
-| Node receives a transaction from a peer        | `tx.receive`           |
-| Node checks if a transaction is valid          | `tx.validate`          |
-| Node forwards a transaction to neighbors       | `tx.relay`             |
-| Nodes agree on which transactions to include   | `consensus.round`      |
-| Consensus progresses through phases            | `consensus.phase.*`    |
-| Node builds a new confirmed ledger             | `ledger.build`         |
-| Node fetches missing ledger data from peers    | `ledger.acquire`       |
-| Node computes payment routes                   | `pathfind.compute`     |
-| Node queues a transaction for later processing | `txq.enqueue`          |
-| Node increases fees due to high load           | `fee.escalate`         |
-| Node fetches the latest trusted validator list | `validator.list.fetch` |
-| Node votes on a protocol amendment             | `amendment.vote`       |
-| Node synchronizes state tree data              | `shamap.sync`          |
-
----
-
-## 1.2 Key Components for Instrumentation
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List
-
-| Component          | Location                                   | Purpose                  | Trace Value                      |
-| ------------------ | ------------------------------------------ | ------------------------ | -------------------------------- |
-| **Overlay**        | `src/xrpld/overlay/`                       | P2P communication        | Message propagation timing       |
-| **PeerImp**        | `src/xrpld/overlay/detail/PeerImp.cpp`     | Individual peer handling | Per-peer latency                 |
-| **RCLConsensus**   | `src/xrpld/app/consensus/RCLConsensus.cpp` | Consensus algorithm      | Round timing, phase analysis     |
-| **NetworkOPs**     | `src/xrpld/app/misc/NetworkOPs.cpp`        | Transaction processing   | Tx lifecycle tracking            |
-| **ServerHandler**  | `src/xrpld/rpc/detail/ServerHandler.cpp`   | RPC entry point          | Request latency                  |
-| **RPCHandler**     | `src/xrpld/rpc/detail/RPCHandler.cpp`      | Command execution        | Per-command timing               |
-| **JobQueue**       | `src/xrpl/core/JobQueue.h`                 | Async task execution     | Queue wait times                 |
-| **PathFinding**    | `src/xrpld/app/paths/`                     | Payment path computation | Path latency, cache hits         |
-| **TxQ**            | `src/xrpld/app/misc/TxQ.cpp`               | Transaction queue/fees   | Queue depth, eviction rates      |
-| **LoadManager**    | `src/xrpld/app/main/LoadManager.cpp`       | Fee escalation/load      | Fee levels, load factors         |
-| **InboundLedgers** | `src/xrpld/app/ledger/InboundLedgers.cpp`  | Ledger acquisition       | Sync time, peer reliability      |
-| **ValidatorList**  | `src/xrpld/app/misc/ValidatorList.cpp`     | UNL management           | List freshness, fetch failures   |
-| **AmendmentTable** | `src/xrpld/app/misc/AmendmentTable.cpp`    | Protocol amendments      | Voting status, activation events |
-| **SHAMap**         | `src/xrpld/shamap/`                        | State hash tree          | Sync speed, missing nodes        |
-
----
-
-## 1.3 Transaction Flow Diagram
-
-Transaction flow spans multiple nodes in the network. Each node creates linked spans to form a distributed trace:
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant PeerA as Peer A (Receive)
-    participant PeerB as Peer B (Relay)
-    participant PeerC as Peer C (Validate)
-
-    Client->>PeerA: 1. Submit TX
-
-    rect rgb(230, 245, 255)
-        Note over PeerA: tx.receive SPAN START
-        PeerA->>PeerA: HashRouter Deduplication
-        PeerA->>PeerA: tx.validate (child span)
-    end
-
-    PeerA->>PeerB: 2. Relay TX (with trace ctx)
-
-    rect rgb(230, 245, 255)
-        Note over PeerB: tx.receive (linked span)
-    end
-
-    PeerB->>PeerC: 3. Relay TX
-
-    rect rgb(230, 245, 255)
-        Note over PeerC: tx.receive (linked span)
-        PeerC->>PeerC: tx.process
-    end
-
-    Note over Client,PeerC: DISTRIBUTED TRACE (same trace_id: abc123)
-```
-
-**Reading the diagram:**
-
-- **Client**: The external entity that submits a transaction to Peer A. It has no trace context -- the trace starts at the first node.
-- **Peer A (Receive)**: The entry node that creates the root span `tx.receive`, runs HashRouter deduplication to avoid processing duplicates, and creates a child `tx.validate` span.
-- **Peer A to Peer B arrow**: The relay message carries trace context (trace_id + parent span_id), enabling Peer B to create a linked span under the same trace.
-- **Peer B (Relay)**: Receives the transaction and trace context, creates a `tx.receive` span linked to Peer A's trace, then relays onward.
-- **Peer C (Validate)**: Final hop in this example. Creates a linked `tx.receive` span and runs `tx.process` to fully process the transaction.
-- **Blue rectangles**: Highlight the span boundaries on each node, showing where instrumentation creates and closes spans.
-
-### Trace Structure
-
-```
-trace_id: abc123
-├── span: tx.receive (Peer A)
-│   ├── span: tx.validate
-│   └── span: tx.relay
-├── span: tx.receive (Peer B) [parent: Peer A]
-│   └── span: tx.relay
-└── span: tx.receive (Peer C) [parent: Peer B]
-    └── span: tx.process
-```
-
----
-
-## 1.4 Consensus Round Flow
-
-Consensus rounds are multi-phase operations that benefit significantly from tracing:
-
-```mermaid
-flowchart TB
-    subgraph round["consensus.round (root span)"]
-        attrs["Attributes:<br/>ledger_seq = 12345678<br/>consensus_mode = proposing<br/>proposers = 35"]
-
-        subgraph open["consensus.phase.open"]
-            open_desc["Duration: ~3s<br/>Waiting for transactions"]
-        end
-
-        subgraph establish["consensus.phase.establish"]
-            est_attrs["proposals_received = 28<br/>disputes_resolved = 3"]
-            est_children["├── consensus.proposal.receive (×28)<br/>├── consensus.proposal.send (×1)<br/>└── consensus.dispute.resolve (×3)"]
-        end
-
-        subgraph accept["consensus.phase.accept"]
-            acc_attrs["transactions_applied = 150<br/>ledger_hash = DEF456..."]
-            acc_children["├── ledger.build<br/>└── ledger.validate"]
-        end
-
-        attrs --> open
-        open --> establish
-        establish --> accept
-    end
-
-    style round fill:#f57f17,stroke:#e65100,color:#ffffff
-    style open fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style establish fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style accept fill:#c2185b,stroke:#880e4f,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **consensus.round (orange, root span)**: The top-level span encompassing the entire consensus round, with attributes like ledger sequence, mode, and proposer count.
-- **consensus.phase.open (blue)**: The first phase where the node waits (~3s) to collect incoming transactions before proposing.
-- **consensus.phase.establish (green)**: The negotiation phase where validators exchange proposals, resolve disputes, and converge on a transaction set. Child spans track each proposal received/sent and each dispute resolved.
-- **consensus.phase.accept (pink)**: The final phase where the agreed transaction set is applied, a new ledger is built, and the ledger is validated. Child spans cover `ledger.build` and `ledger.validate`.
-- **Arrows (open to establish to accept)**: The sequential flow through the three consensus phases. Each phase must complete before the next begins.
-
----
-
-## 1.5 RPC Request Flow
-
-> **WS** = WebSocket
-
-RPC requests support W3C Trace Context headers for distributed tracing across services:
-
-```mermaid
-flowchart TB
-    subgraph request["rpc.request (root span)"]
-        http["HTTP Request — POST /<br/>traceparent:<br/>00-abc123...-def456...-01"]
-
-        attrs["Attributes:<br/>http.method = POST<br/>net.peer.ip = 192.168.1.100<br/>command = submit"]
-
-        subgraph enqueue["jobqueue.enqueue"]
-            job_attr["job_type = jtCLIENT_RPC"]
-        end
-
-        subgraph command["rpc.command.submit"]
-            cmd_attrs["version = 2<br/>rpc_role = user"]
-            cmd_children["├── tx.deserialize<br/>├── tx.validate_local<br/>└── tx.submit_to_network"]
-        end
-
-        response["Response: 200 OK<br/>Duration: 45ms"]
-
-        http --> attrs
-        attrs --> enqueue
-        enqueue --> command
-        command --> response
-    end
-
-    style request fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style enqueue fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style command fill:#e65100,stroke:#bf360c,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **rpc.request (green, root span)**: The outermost span representing the full RPC request lifecycle, from HTTP receipt to response. Carries the W3C `traceparent` header for distributed tracing.
-- **HTTP Request node**: Shows the incoming POST request with its `traceparent` header and extracted attributes (method, peer IP, command name).
-- **jobqueue.enqueue (blue)**: The span covering the asynchronous handoff from the RPC thread to the JobQueue worker thread. The trace context is preserved across this async boundary.
-- **rpc.command.submit (orange)**: The span for the actual command execution, with child spans for deserialization, local validation, and network submission.
-- **Response node**: The final output with HTTP status and total duration, marking the end of the root span.
-- **Arrows (top to bottom)**: The sequential processing pipeline -- receive request, extract attributes, enqueue job, execute command, return response.
-
----
-
-## 1.6 Key Trace Points
-
-> **TxQ** = Transaction Queue
-
-The following table identifies priority instrumentation points across the codebase:
-
-| Category        | Span Name              | File                   | Method                  | Priority |
-| --------------- | ---------------------- | ---------------------- | ----------------------- | -------- |
-| **Transaction** | `tx.receive`           | `PeerImp.cpp`          | `handleTransaction()`   | High     |
-| **Transaction** | `tx.validate`          | `NetworkOPs.cpp`       | `processTransaction()`  | High     |
-| **Transaction** | `tx.process`           | `NetworkOPs.cpp`       | `doTransactionSync()`   | High     |
-| **Transaction** | `tx.relay`             | `OverlayImpl.cpp`      | `relay()`               | Medium   |
-| **Consensus**   | `consensus.round`      | `RCLConsensus.cpp`     | `startRound()`          | High     |
-| **Consensus**   | `consensus.phase.*`    | `Consensus.h`          | `timerEntry()`          | High     |
-| **Consensus**   | `consensus.proposal.*` | `RCLConsensus.cpp`     | `peerProposal()`        | Medium   |
-| **RPC**         | `rpc.request`          | `ServerHandler.cpp`    | `onRequest()`           | High     |
-| **RPC**         | `rpc.command.*`        | `RPCHandler.cpp`       | `doCommand()`           | High     |
-| **Peer**        | `peer.connect`         | `OverlayImpl.cpp`      | `onHandoff()`           | Low      |
-| **Peer**        | `peer.message.*`       | `PeerImp.cpp`          | `onMessage()`           | Low      |
-| **Ledger**      | `ledger.acquire`       | `InboundLedgers.cpp`   | `acquire()`             | Medium   |
-| **Ledger**      | `ledger.build`         | `RCLConsensus.cpp`     | `buildLCL()`            | High     |
-| **PathFinding** | `pathfind.request`     | `PathRequest.cpp`      | `doUpdate()`            | High     |
-| **PathFinding** | `pathfind.compute`     | `Pathfinder.cpp`       | `findPaths()`           | High     |
-| **TxQ**         | `txq.enqueue`          | `TxQ.cpp`              | `apply()`               | High     |
-| **TxQ**         | `txq.apply`            | `TxQ.cpp`              | `processClosedLedger()` | High     |
-| **Fee**         | `fee.escalate`         | `LoadManager.cpp`      | `raiseLocalFee()`       | Medium   |
-| **Ledger**      | `ledger.replay`        | `LedgerReplayer.h`     | `replay()`              | Medium   |
-| **Ledger**      | `ledger.delta`         | `LedgerDeltaAcquire.h` | `processData()`         | Medium   |
-| **Validator**   | `validator.list.fetch` | `ValidatorList.cpp`    | `verify()`              | Medium   |
-| **Validator**   | `validator.manifest`   | `Manifest.cpp`         | `applyManifest()`       | Low      |
-| **Amendment**   | `amendment.vote`       | `AmendmentTable.cpp`   | `doVoting()`            | Low      |
-| **SHAMap**      | `shamap.sync`          | `SHAMap.cpp`           | `fetchRoot()`           | Medium   |
-
----
-
-## 1.7 Instrumentation Priority
-
-> **TxQ** = Transaction Queue
-
-```mermaid
-quadrantChart
-    title Instrumentation Priority Matrix
-    x-axis Low Complexity --> High Complexity
-    y-axis Low Value --> High Value
-    quadrant-1 Implement First
-    quadrant-2 Plan Carefully
-    quadrant-3 Quick Wins
-    quadrant-4 Consider Later
-
-    RPC Tracing: [0.2, 0.92]
-    Transaction Tracing: [0.55, 0.88]
-    Consensus Tracing: [0.78, 0.82]
-    PathFinding: [0.38, 0.75]
-    TxQ and Fees: [0.25, 0.65]
-    Ledger Sync: [0.62, 0.58]
-    Peer Message Tracing: [0.35, 0.25]
-    JobQueue Tracing: [0.2, 0.48]
-    Validator Mgmt: [0.48, 0.42]
-    Amendment Tracking: [0.15, 0.32]
-    SHAMap Operations: [0.72, 0.45]
-```
-
----
-
-## 1.8 Observable Outcomes
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List
-
-After implementing OpenTelemetry, operators and developers will gain visibility into the following:
-
-### 1.8.1 What You Will See: Traces
-
-| Trace Type                 | Description                                                                                 | Example Query in Grafana/Tempo                  |
-| -------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| **Transaction Lifecycle**  | Full journey from RPC submission through validation, relay, consensus, and ledger inclusion | `{service.name="xrpld" && tx_hash="ABC123..."}` |
-| **Cross-Node Propagation** | Transaction path across multiple xrpld nodes with timing                                    | `{relay_count > 0}`                             |
-| **Consensus Rounds**       | Complete round with all phases (open, establish, accept)                                    | `{span.name=~"consensus.round.*"}`              |
-| **RPC Request Processing** | Individual command execution with timing breakdown                                          | `{command="account_info"}`                      |
-| **Ledger Acquisition**     | Peer-to-peer ledger data requests and responses                                             | `{span.name="ledger.acquire"}`                  |
-| **PathFinding Latency**    | Path computation time and cache effectiveness for payment RPCs                              | `{span.name="pathfind.compute"}`                |
-| **TxQ Behavior**           | Queue depth, eviction patterns, fee escalation during congestion                            | `{span.name=~"txq.*"}`                          |
-| **Ledger Sync**            | Full acquisition timeline including delta and transaction fetches                           | `{span.name=~"ledger.acquire.*"}`               |
-| **Validator Health**       | UNL fetch success, manifest updates, stale list detection                                   | `{span.name=~"validator.*"}`                    |
-
-### 1.8.2 What You Will See: Metrics (Derived from Traces)
-
-| Metric                        | Description                             | Dashboard Panel             |
-| ----------------------------- | --------------------------------------- | --------------------------- |
-| **RPC Latency (p50/p95/p99)** | Response time distribution per command  | Heatmap by command          |
-| **Transaction Throughput**    | Transactions processed per second       | Time series graph           |
-| **Consensus Round Duration**  | Time to complete consensus phases       | Histogram                   |
-| **Cross-Node Latency**        | Time for transaction to reach N nodes   | Line chart with percentiles |
-| **Error Rate**                | Failed transactions/RPC calls by type   | Stacked bar chart           |
-| **PathFinding Latency**       | Path computation time per currency pair | Heatmap by currency         |
-| **TxQ Depth**                 | Queued transactions over time           | Time series with thresholds |
-| **Fee Escalation Level**      | Current fee multiplier                  | Gauge with alert thresholds |
-| **Ledger Sync Duration**      | Time to acquire missing ledgers         | Histogram                   |
-
-### 1.8.3 Concrete Dashboard Examples
-
-**Transaction Trace View (Tempo):**
-
-```
-┌────────────────────────────────────────────────────────────────────────────────┐
-│ Trace: abc123... (Transaction Submission)                    Duration: 847ms   │
-├────────────────────────────────────────────────────────────────────────────────┤
-│ ├── rpc.request [ServerHandler]                              ████░░░░░░  45ms  │
-│ │   └── rpc.command.submit [RPCHandler]                      ████░░░░░░  42ms  │
-│ │       └── tx.receive [NetworkOPs]                          ███░░░░░░░  35ms  │
-│ │           ├── tx.validate [TxQ]                            █░░░░░░░░░   8ms  │
-│ │           └── tx.relay [Overlay]                           ██░░░░░░░░  15ms  │
-│ │               ├── tx.receive [Node-B]                      █████░░░░░  52ms  │
-│ │               │   └── tx.relay [Node-B]                    ██░░░░░░░░  18ms  │
-│ │               └── tx.receive [Node-C]                      ██████░░░░  65ms  │
-│ └── consensus.round [RCLConsensus]                           ████████░░ 720ms  │
-│     ├── consensus.phase.open                                 ██░░░░░░░░ 180ms  │
-│     ├── consensus.phase.establish                            █████░░░░░ 480ms  │
-│     └── consensus.phase.accept                               █░░░░░░░░░  60ms  │
-└────────────────────────────────────────────────────────────────────────────────┘
-```
-
-**RPC Performance Dashboard Panel:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ RPC Command Latency (Last 1 Hour)                           │
-├─────────────────────────────────────────────────────────────┤
-│ Command          │ p50    │ p95    │ p99    │ Errors │ Rate │
-│──────────────────┼────────┼────────┼────────┼────────┼──────│
-│ account_info     │  12ms  │  45ms  │  89ms  │  0.1%  │ 150/s│
-│ submit           │  35ms  │ 120ms  │ 250ms  │  2.3%  │  45/s│
-│ ledger           │   8ms  │  25ms  │  55ms  │  0.0%  │  80/s│
-│ tx               │  15ms  │  50ms  │ 100ms  │  0.5%  │  60/s│
-│ server_info      │   5ms  │  12ms  │  20ms  │  0.0%  │ 200/s│
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Consensus Health Dashboard Panel:**
-
-```mermaid
----
-config:
-    xyChart:
-        width: 1200
-        height: 400
-        plotReservedSpacePercent: 50
-        chartOrientation: vertical
-    themeVariables:
-        xyChart:
-            plotColorPalette: "#3498db"
----
-xychart-beta
-    title "Consensus Round Duration (Last 24 Hours)"
-    x-axis "Time of Day (Hours)" [0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24]
-    y-axis "Duration (seconds)" 1 --> 5
-    line [2.1, 2.4, 2.8, 3.2, 3.8, 4.3, 4.5, 5.0, 4.7, 4.0, 3.2, 2.6, 2.0]
-```
-
-### 1.8.4 Operator Actionable Insights
-
-| Scenario                  | What You'll See                                                              | Action                                           |
-| ------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------ |
-| **Slow RPC**              | Span showing which phase is slow (parsing, execution, serialization)         | Optimize specific code path                      |
-| **Transaction Stuck**     | Trace stops at validation; error attribute shows reason                      | Fix transaction parameters                       |
-| **Consensus Delay**       | Phase.establish taking too long; proposer attribute shows missing validators | Investigate network connectivity                 |
-| **Memory Spike**          | Large batch of spans correlating with memory increase                        | Tune batch_size or sampling                      |
-| **Network Partition**     | Traces missing cross-node links for specific peer                            | Check peer connectivity                          |
-| **Path Computation Slow** | pathfind.compute span shows high latency; cache miss rate in attributes      | Warm the RippleLineCache, check order book depth |
-| **TxQ Full**              | txq.enqueue spans show evictions; fee.escalate spans increasing              | Monitor fee levels, alert operators              |
-| **Ledger Sync Stalled**   | ledger.acquire spans timing out; peer reliability attributes show issues     | Check peer connectivity, add trusted peers       |
-| **UNL Stale**             | validator.list.fetch spans failing; last_update attribute aging              | Verify validator site URLs, check DNS            |
-
-### 1.8.5 Developer Debugging Workflow
-
-1. **Find Transaction**: Query by `tx_hash` to get full trace
-2. **Identify Bottleneck**: Look at span durations to find slowest component
-3. **Check Attributes**: Review `validity`, `rpc_status` for errors
-4. **Correlate Logs**: Use `trace_id` to find related PerfLog entries
-5. **Compare Nodes**: Filter by `service.instance.id` to compare behavior across nodes
-
----
-
-_Next: [Design Decisions](./02-design-decisions.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/02-design-decisions.md

@@ -1,886 +0,0 @@
-# Design Decisions
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Architecture Analysis](./01-architecture-analysis.md)
-
----
-
-## 2.1 OpenTelemetry Components
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 2.1.1 SDK Selection
-
-**Primary Choice**: OpenTelemetry C++ SDK (`opentelemetry-cpp`)
-
-| Component                               | Purpose                | Required                  |
-| --------------------------------------- | ---------------------- | ------------------------- |
-| `opentelemetry-cpp::api`                | Tracing API headers    | Yes                       |
-| `opentelemetry-cpp::sdk`                | SDK implementation     | Yes                       |
-| `opentelemetry-cpp::ext`                | Extensions (exporters) | Yes                       |
-| `opentelemetry-cpp::otlp_http_exporter` | OTLP/HTTP export       | Yes (shipped in Phase 1b) |
-| `opentelemetry-cpp::otlp_grpc_exporter` | OTLP/gRPC export       | Future (not yet wired up) |
-
-### 2.1.2 Instrumentation Strategy
-
-**Manual Instrumentation** (recommended):
-
-| Approach   | Pros                                                            | Cons                                                    |
-| ---------- | --------------------------------------------------------------- | ------------------------------------------------------- |
-| **Manual** | Precise control, optimized placement, xrpld-specific attributes | More development effort                                 |
-| **Auto**   | Less code, automatic coverage                                   | Less control, potential overhead, limited customization |
-
----
-
-## 2.2 Exporter Configuration
-
-> **OTLP** = OpenTelemetry Protocol
-
-```mermaid
-flowchart TB
-    subgraph nodes["xrpld Nodes"]
-        node1["xrpld<br/>Node 1"]
-        node2["xrpld<br/>Node 2"]
-        node3["xrpld<br/>Node 3"]
-    end
-
-    collector["OpenTelemetry<br/>Collector<br/>(sidecar or standalone)"]
-
-    subgraph backends["Observability Backends"]
-        tempo["Tempo"]
-        elastic["Elastic<br/>APM"]
-    end
-
-    node1 -->|"OTLP/HTTP<br/>:4318"| collector
-    node2 -->|"OTLP/HTTP<br/>:4318"| collector
-    node3 -->|"OTLP/HTTP<br/>:4318"| collector
-
-    collector --> tempo
-    collector --> elastic
-
-    style nodes fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style backends fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style collector fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **xrpld Nodes (blue)**: The source of telemetry data. Each xrpld node exports spans via OTLP/HTTP on port 4318 (the only exporter shipped in Phase 1b).
-- **OpenTelemetry Collector (red)**: The central aggregation point that receives spans from all nodes. Can run as a sidecar (per-node) or standalone (shared). Handles batching, filtering, and routing.
-- **Observability Backends (green)**: The storage and visualization destinations. Tempo is the recommended backend for both development and production, and Elastic APM is an alternative. The Collector routes to one or more backends.
-- **Arrows (nodes to collector to backends)**: The data pipeline -- spans flow from nodes to the Collector over HTTP, then the Collector fans out to the configured backends.
-
-### 2.2.1 OTLP/HTTP (Shipped in Phase 1b)
-
-OTLP/HTTP is the only exporter wired up in Phase 1b. It is configured via
-`OtlpHttpExporterOptions` with the collector traces endpoint
-(`http://localhost:4318/v1/traces` by default) and a JSON content type
-(binary protobuf is also available).
-
-### 2.2.2 OTLP/gRPC (Future Work — Planned Upgrade)
-
-OTLP/gRPC is planned as a future upgrade from the HTTP exporter. The gRPC
-transport offers lower per-span overhead and tighter back-pressure semantics
-than HTTP/JSON, making it attractive for production deployments once the HTTP
-path is validated in earlier phases.
-
-Required to land this upgrade:
-
-1. Add `opentelemetry-cpp::otlp_grpc_exporter` to the Conan recipe (the
-   dependency already exists but is not linked in Phase 1b builds).
-2. Extend `TelemetryConfig.cpp` to parse an `exporter` key (`otlp_http`
-   default, `otlp_grpc` opt-in) and a gRPC endpoint override.
-3. In `Telemetry::start()` branch on the parsed exporter type and construct
-   either `OtlpHttpExporterFactory::Create(httpOpts)` or
-   `OtlpGrpcExporterFactory::Create(grpcOpts)` accordingly.
-4. Update the runbook and dashboards to document the alternate port and TLS
-   settings.
-
-When wired up, the gRPC path will use `OtlpGrpcExporterOptions` configured with
-the collector endpoint (host on port 4317), TLS credentials enabled, and a CA
-certificate path.
-
-Until that work lands, `OtlpGrpcExporterOptions` is **not** used by any code
-path in Phase 1b through Phase 5.
-
----
-
-## 2.3 Span Naming Conventions
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List | **WS** = WebSocket
-
-### 2.3.1 Naming Schema
-
-```
-<component>.<operation>[.<sub-operation>]
-```
-
-**Examples**:
-
-- `tx.receive` - Transaction received from peer
-- `consensus.phase.establish` - Consensus establish phase
-- `rpc.command.server_info` - server_info RPC command
-
-### 2.3.2 Complete Span Catalog
-
-> **Status column.** This catalog is the design inventory; it is not a
-> statement of what currently emits. `Live` means the span is present in the
-> implemented inventory ([09-data-collection-reference.md §1.1](./09-data-collection-reference.md#11-complete-span-inventory-41-spans)),
-> which is the authoritative list. `Renamed`/`Split` means the concept shipped
-> under a different name than planned here. **Not built** means no span is
-> emitted for it today.
->
-> **"Not built" is not one thing.** All 14 such entries fall into three cases, and the
-> fourth column says which — filing them all as oversights would be wrong:
->
-> - **Superseded by metrics or logs (7)** — a deliberate trade-off: the signal is already
->   carried by a metric or by a log-derived panel, and a span would add per-event volume
->   without adding information. `tx.relay`, `fee.escalate`, `validator.list.fetch`,
->   `validator.manifest`, `shamap.sync`, `job.enqueue`, `job.execute`.
-> - **Gap (6)** — nothing was decided; they were simply never instrumented. The four
->   `peer.*` entries, plus `ledger.replay` and `ledger.delta` — and those last two are the
->   sharpest, because they have **no metric substitute at all**.
-> - **Deferred (1)** — scheduled work: `amendment.vote` (Phase 11).
->
-> The four `peer.*` entries are the peer-span coverage gap: only
-> `peer.proposal.receive` and `peer.validation.receive` exist, so protocol
-> message send/receive and connection lifecycle are untraced. See
-> [09 §6.4](./09-data-collection-reference.md#64-peer-span-coverage-gap-not-implemented).
->
-> `tx.validate` did ship, but renamed and split three ways: the apply pipeline
-> traces `tx.preflight` (stateless checks), `tx.preclaim` (ledger-state checks)
-> and `tx.transactor` (application), each stamped with a `stage` attribute.
-> Names come from `TxApplySpanNames.h:90,94,99`. The spans are created in two
-> different files, not one: `tx.preflight` and `tx.preclaim` come from
-> `applySteps.cpp` (`invokePreflight()` at `:211-212`, `invokePreclaim()` at
-> `:258-261`, both via the shared `makeStageSpan()` helper at `:89-126`), while
-> `tx.transactor` is created in `Transactor::operator()()`
-> (`Transactor.cpp:1601-1605`). Query them with
-> `name=~"tx\.(preflight|preclaim|transactor)"` — a **single** backslash; RE2
-> reads `\\.` as a literal backslash followed by any character, which matches
-> nothing here — never `name="tx.validate"`.
-
-| Span name                      | Description                             | Status                                                           | Why not built / where the signal lives instead                                                                                                                                                                                                                                                             |
-| ------------------------------ | --------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tx.receive`                   | Transaction received from network       | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `tx.validate`                  | Transaction signature/format validation | Renamed + split → `tx.preflight`, `tx.preclaim`, `tx.transactor` | —                                                                                                                                                                                                                                                                                                          |
-| `tx.process`                   | Full transaction processing             | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `tx.relay`                     | Transaction relay to peers              | **Not built**                                                    | **Superseded by metrics.** Relay volume is carried by the overlay traffic counters (`total_bytes_in/out`, `total_messages_in/out`, per-`TrafficCount` category). Relay is also per-peer fan-out, so one span per relay multiplies by peer count for data the counters already aggregate.                   |
-| `tx.apply`                     | Apply transaction to ledger             | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.round`              | Complete consensus round                | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.phase.open`         | Open phase - collecting transactions    | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.phase.establish`    | Establish phase - reaching agreement    | Renamed `consensus.establish`                                    | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.phase.accept`       | Accept phase - applying consensus       | Renamed `consensus.accept`                                       | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.proposal.receive`   | Receive peer proposal                   | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.proposal.send`      | Send our proposal                       | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.validation.receive` | Receive peer validation                 | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.validation.send`    | Send our validation                     | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `rpc.request`                  | HTTP/WebSocket request handling         | Split into `rpc.http_request` / `rpc.ws_message`                 | —                                                                                                                                                                                                                                                                                                          |
-| `rpc.command.*`                | Specific RPC command (dynamic)          | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `peer.connect`                 | Peer connection establishment           | **Not built**                                                    | **Gap, scoped as its own change** — see [09 §6.4](./09-data-collection-reference.md#64-peer-span-coverage-gap-not-implemented). Adding these changes the 41-family span count and the 40 catalogued in `expected_spans.json`.                                                                              |
-| `peer.disconnect`              | Peer disconnection                      | **Not built**                                                    | **Gap.** Partially observable: the aggregate count via the `Overlay.Peer_Disconnects` insight gauge and resource-charge drops via `server_info{metric="peer_disconnects_resources"}`, but not per-reason. Disconnect reasons are only recoverable from `debug.log` (the `log-derived-insights` dashboard). |
-| `peer.message.send`            | Send protocol message                   | **Not built**                                                    | **Gap.** Of the 13 protocol message families only `mtGET_OBJECTS` has native instrumentation (`getobject_*`); byte/message volume is aggregated by `TrafficCount` category, not traced per message.                                                                                                        |
-| `peer.message.receive`         | Receive protocol message                | **Not built**                                                    | **Gap.** Same as `peer.message.send`.                                                                                                                                                                                                                                                                      |
-| `ledger.acquire`               | Ledger acquisition from network         | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.build`                 | Build new ledger                        | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.validate`              | Ledger validation                       | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.close`                 | Close ledger                            | Renamed `consensus.ledger_close`                                 | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.replay`                | Ledger replay executed                  | **Not built**                                                    | **Gap, no substitute.** `LedgerReplayer.cpp` and `LedgerReplayTask.cpp` contain zero `SpanGuard` uses and no metric covers the replay path. A real hole, not a trade-off.                                                                                                                                  |
-| `ledger.delta`                 | Delta-based ledger acquired             | **Not built**                                                    | **Gap, no substitute.** `LedgerDeltaAcquire.cpp` contains zero `SpanGuard` uses. The `acquire_*` stats cover whole-ledger acquisition, not the delta path.                                                                                                                                                 |
-| `pathfind.request`             | Path request initiated                  | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `pathfind.compute`             | Path computation executed               | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `txq.enqueue`                  | Transaction queued                      | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `txq.apply`                    | Queued transaction applied              | Renamed `txq.apply_direct` / `txq.accept_tx`                     | —                                                                                                                                                                                                                                                                                                          |
-| `fee.escalate`                 | Fee escalation triggered                | **Not built**                                                    | **Superseded by metrics + existing spans.** Escalation state is `txq_metrics{metric=…}` and `load_factor_metrics{metric=…}`; the queueing path that triggers it is already traced by the six `txq.*` spans. An event span would restate a gauge.                                                           |
-| `validator.list.fetch`         | UNL list fetched                        | **Not built**                                                    | **Superseded by metrics.** `validator_health{metric="unl_expiry_days"}`, `{metric="unl_blocked"}` and `{metric="validation_quorum"}` carry the outcome. A fetch span would fire on a slow timer and tell an operator nothing the gauges do not.                                                            |
-| `validator.manifest`           | Manifest update processed               | **Not built**                                                    | **Superseded by logs.** Per-master-key manifest dispositions are on the `log-derived-insights` dashboard (`ManifestCache` partition, requires `log_level ManifestCache debug`).                                                                                                                            |
-| `amendment.vote`               | Amendment voting executed               | **Not built**                                                    | **Deferred to Phase 11.** `validator_health{metric="amendment_blocked"}` covers the blocked state in the meantime.                                                                                                                                                                                         |
-| `shamap.sync`                  | State tree synchronization              | **Not built**                                                    | **Superseded by metrics.** Covered by the nine `acquire_*` stats, `nodestore_state{metric=…}` and the five `getobject_*` families. Per-node-fetch spans would be prohibitive volume.                                                                                                                       |
-| `job.enqueue`                  | Job added to queue                      | **Not built**                                                    | **Superseded by metrics.** `job_queued_total` and `job_queued_us{job_type}` plus the 105 per-job-type `jobq_*` gauges. A span per enqueue is one span per unit of daemon work, for latency the histogram already records exactly.                                                                          |
-| `job.execute`                  | Job execution                           | **Not built**                                                    | **Superseded by metrics.** `job_started_total`, `job_finished_total`, `job_running_us{job_type}`. Same volume argument as `job.enqueue`.                                                                                                                                                                   |
-
-### 2.3.3 Attribute Naming Conventions
-
-Span **names** follow §2.3.1 (dotted `<component>.<operation>`). Span
-**attribute keys** follow the rules below. The constants in the `*SpanNames.h`
-headers are the single source of truth; the collector, Tempo, the Grafana
-dashboards, and the runbook all consume these exact keys, so every layer must
-agree with the code. A CI check enforces this end to end.
-
-1. **Per-span unique attribute** → bare field name, allowed when the field is
-   recorded by a single span/workflow so the span name already supplies the
-   domain (e.g. `command`, `version`, `local` on `rpc.command`).
-2. **Shared attribute (same concept on more than one span)** → ONE key, reused
-   verbatim on every span that records it; the span name tells the occurrences
-   apart, so no per-emitter prefix is added. Name it by the field's meaning: a
-   property of a domain object keeps that object's bare field name (`ledger_hash`,
-   `ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a field already
-   qualified by a sub-kind keeps that qualifier on every emitter (`proposal_trusted`
-   on both `consensus.proposal.receive` and `peer.proposal.receive`;
-   `validation_trusted` likewise). Defined once in the base `SpanNames.h`
-   `namespace attr` block and re-exported (`using`) by each domain header.
-3. **Collision qualifier** → `<domain>_<field>`, only when a bare name would
-   collide with a DIFFERENT concept in the shared span_metrics label space or with
-   the OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
-   `consensus_phase`, `consensus_round`, `consensus_mode`). This disambiguates
-   distinct concepts that share a word; it is NOT used to tag the same concept
-   with its emitting workflow — that is rule 2 (one shared name).
-4. **Resource attribute** → dotted `xrpl.<subsystem>.<field>`, reserved ONLY
-   for process/network identity set once at startup (`xrpl.network.id`,
-   `xrpl.network.type`). Span attributes are never dotted in the `xrpl.` form —
-   it blurs the resource/span scope boundary and parses awkwardly in TraceQL.
-5. **Span names** use `<subsystem>[.<component>]` (dotted, per §2.3.1). Only
-   attribute _keys_ follow rules 1–4.
-
-Standard OpenTelemetry semantic-convention keys keep their canonical dotted
-form (e.g. `service.*` resource attributes, `http.*` span attributes); the
-"no dotted form" rule applies to xrpl-custom keys only.
-
-The same rules are recorded in `CONTRIBUTING.md` (the permanent home, since
-`OpenTelemetryPlan/` is removed once the rollout completes). The attribute
-examples in §2.4 below follow these rules.
-
----
-
-## 2.4 Attribute Schema
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List | **OTLP** = OpenTelemetry Protocol
-
-### 2.4.1 Resource Attributes (Set Once at Startup)
-
-Resource attributes identify the process and are set once at startup. They use
-the standard OpenTelemetry semantic conventions plus custom dotted `xrpl.*`
-keys (the dotted form is reserved for resource scope per §2.3.3).
-
-Five are set, by `Telemetry.cpp:380-387` (tracer resource) and the matching
-block in `initMetrics()` (metrics resource); the custom key constants are
-`SpanNames.h:117-118`.
-
-| Key                   | Type / value                                                   | Description                    | Status                                                                                                                                                                                                                                                                                          |
-| --------------------- | -------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `service.name`        | `"xrpld"`                                                      | Standard `SERVICE_NAME`        | Set                                                                                                                                                                                                                                                                                             |
-| `service.version`     | `build_info::getVersionString()`                               | Standard `SERVICE_VERSION`     | Set                                                                                                                                                                                                                                                                                             |
-| `service.instance.id` | node public key (base58), or `[telemetry] service_instance_id` | Standard `SERVICE_INSTANCE_ID` | Set — but the node-key fallback reaches traces only; see [05 §5.1.1](./05-configuration-reference.md)                                                                                                                                                                                           |
-| `xrpl.network.id`     | network id (e.g. 0 for mainnet)                                | Network identifier             | Set                                                                                                                                                                                                                                                                                             |
-| `xrpl.network.type`   | `"mainnet"` \| `"testnet"` \| `"devnet"` \| `"unknown"`        | Network kind                   | Set                                                                                                                                                                                                                                                                                             |
-| `xrpl.node.type`      | `"validator"` \| `"stock"` \| `"reporting"`                    | Node role                      | **Not implemented** — no constant, no set-site. Node role is therefore not queryable from a trace. (Dashboards do offer an `$xrpl_node_role` filter, but it matches a Prometheus label stamped by the external perf-iac deployment — `check_otel_naming.py:872` — not by anything in this repo) |
-| `xrpl.node.cluster`   | cluster name                                                   | Cluster name, if clustered     | **Not implemented** — no constant, no set-site                                                                                                                                                                                                                                                  |
-
-The collector adds two more resource attributes of its own (`deployment.environment`
-and, when the node did not stamp it, `xrpl.network.type`) via the
-`resource/tier` processor, and deletes the SDK-injected `telemetry.sdk.*` trio
-via `resource/stripsdk`. See [05 §5.5.1](./05-configuration-reference.md).
-
-### 2.4.2 Span Attributes by Category
-
-> Span attribute keys use the underscore form from §2.3.3 (shared/qualified
-> keys are `<domain>_<field>`; per-span unique keys are bare). The dotted form
-> is reserved for the resource attributes in §2.4.1 above. This catalog lists
-> the planned attribute set by category; the exact emitted key **and its type**
-> for each implemented span is defined by the `*SpanNames.h` constants and their
-> set-sites, which win where the two differ. The types in the tables below are
-> the ones originally planned and are **not** all what shipped — `peer_id` is
-> the notable case (planned as a base58 string, shipped as an int64). §2.4.3
-> is the implemented view.
-
-#### Transaction Attributes
-
-| Key                  | Type   | Description                                                                                                                                                   |
-| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tx_hash`            | string | Transaction hash (hex)                                                                                                                                        |
-| `tx_type`            | string | `"Payment"`, `"OfferCreate"`, etc.                                                                                                                            |
-| `tx_account`         | string | Sending account, raw r-address                                                                                                                                |
-| `tx_<field>`         | string | One per account-typed top-level field the transaction carries (`tx_destination`, `tx_owner`, `tx_issuer`, ...), raw r-address; keys in `TxAccountSpanNames.h` |
-| `tx_sequence`        | int64  | Account sequence number                                                                                                                                       |
-| `tx_fee`             | int64  | Fee in drops                                                                                                                                                  |
-| `tx_result`          | string | `"tesSUCCESS"`, `"tecPATH_DRY"`, etc.                                                                                                                         |
-| `current_ledger_seq` | int64  | Open ledger the transaction targeted                                                                                                                          |
-| `relay_count`        | int64  | Peers the transaction was relayed to                                                                                                                          |
-
-> **Note:** `current_ledger_seq` and `ledger_seq` are the same concept — a ledger's sequence number — but they name different ledgers, so the design keeps two keys rather than one. `current_ledger_seq` is the open or in-flight ledger a transaction's work was applied into; it is named after the RPC field `ledger_current_index`. `ledger_seq` (see [Ledger & Job Attributes](#ledger--job-attributes)) is a closed or validated ledger, set by the ledger and consensus spans. Neither is spelled `ledger_index`: per rule 2 of [Telemetry span attribute naming](../CONTRIBUTING.md#telemetry-span-attribute-naming), one concept gets one key reused verbatim, and a different referent is disambiguated with a prefix rather than a synonym.
-
-#### Consensus Attributes
-
-| Key                  | Type    | Description                         |
-| -------------------- | ------- | ----------------------------------- |
-| `consensus_round`    | int64   | Round number                        |
-| `consensus_phase`    | string  | `"open"`, `"establish"`, `"accept"` |
-| `consensus_mode`     | string  | `"proposing"`, `"observing"`, etc.  |
-| `proposers`          | int64   | Number of proposers                 |
-| `prev_ledger_prefix` | string  | Previous ledger hash prefix         |
-| `ledger_seq`         | int64   | Ledger sequence                     |
-| `tx_count`           | int64   | Transactions in consensus set       |
-| `round_time_ms`      | float64 | Round duration                      |
-
-Establish-phase gap fill and cross-node correlation attributes (Phase 4a):
-
-| Key                   | Type   | Description                                               |
-| --------------------- | ------ | --------------------------------------------------------- |
-| `consensus_round_id`  | int64  | Consensus round number                                    |
-| `consensus_ledger_id` | string | `previousLedger.id()` — shared across nodes               |
-| `trace_strategy`      | string | `"deterministic"` or `"random"`                           |
-| `converge_percent`    | int64  | Convergence % (0-100+)                                    |
-| `establish_count`     | int64  | Number of establish iterations                            |
-| `disputes_count`      | int64  | Active disputed transactions                              |
-| `agree_count`         | int64  | Peers that agree (haveConsensus)                          |
-| `disagree_count`      | int64  | Peers that disagree                                       |
-| `threshold_percent`   | int64  | Close-time consensus threshold (`avCT_CONSENSUS_PCT`=75%) |
-| `consensus_result`    | string | `"yes"`, `"no"`, `"moved_on"`, `"expired"`                |
-| `mode_old`            | string | Previous consensus mode                                   |
-| `mode_new`            | string | New consensus mode                                        |
-
-#### RPC Attributes
-
-| Key           | Type    | Description                                                                   |
-| ------------- | ------- | ----------------------------------------------------------------------------- |
-| `command`     | string  | Command name (per-span unique on `rpc.command`)                               |
-| `version`     | int64   | API version                                                                   |
-| `rpc_role`    | string  | `"admin"` or `"user"` (qualified — `role` is generic)                         |
-| `params`      | string  | Sanitized parameters (optional)                                               |
-| `rpc_status`  | string  | Response status: `success` \| `error` (qualified — `status` is OTel-reserved) |
-| `duration_ms` | float64 | Request duration in milliseconds                                              |
-
-#### Peer & Message Attributes
-
-| Key                  | Type    | Description                                                               |
-| -------------------- | ------- | ------------------------------------------------------------------------- |
-| `peer_id`            | string  | Peer public key (base58) — **planned only; shipped as int64, see §2.4.3** |
-| `peer_address`       | string  | IP:port                                                                   |
-| `peer_latency_ms`    | float64 | Measured latency                                                          |
-| `peer_cluster`       | string  | Cluster name if clustered                                                 |
-| `message_type`       | string  | Protocol message type name                                                |
-| `message_size_bytes` | int64   | Message size                                                              |
-| `message_compressed` | bool    | Whether compressed                                                        |
-
-#### Ledger & Job Attributes
-
-| Key                         | Type    | Description                      |
-| --------------------------- | ------- | -------------------------------- |
-| `ledger_hash`               | string  | Ledger hash                      |
-| `ledger_seq`                | int64   | Closed/validated ledger sequence |
-| `close_time_ripple_epoch_s` | int64   | Close time (XRPL epoch seconds)  |
-| `ledger_tx_count`           | int64   | Transaction count                |
-| `job_type`                  | string  | Job type name                    |
-| `job_queue_ms`              | float64 | Time spent in queue              |
-| `job_worker`                | int64   | Worker thread ID                 |
-
-#### PathFinding Attributes
-
-| Key                        | Type   | Description                                                            |
-| -------------------------- | ------ | ---------------------------------------------------------------------- |
-| `pathfind_source_account`  | string | Source r-address, raw                                                  |
-| `pathfind_dest_account`    | string | Destination r-address, raw                                             |
-| `pathfind_source_currency` | string | Source currency code                                                   |
-| `pathfind_dest_currency`   | string | Destination asset: `XRP`, `<issuer>/<currency>`, or an MPT issuance id |
-| `pathfind_path_count`      | int64  | Number of paths found                                                  |
-| `pathfind_cache_hit`       | bool   | RippleLineCache hit                                                    |
-
-#### TxQ Attributes
-
-| Key                   | Type   | Description                 |
-| --------------------- | ------ | --------------------------- |
-| `txq_queue_depth`     | int64  | Current queue depth         |
-| `txq_fee_level`       | int64  | Fee level of transaction    |
-| `txq_eviction_reason` | string | Why transaction was evicted |
-
-#### Fee Attributes
-
-| Key                    | Type  | Description               |
-| ---------------------- | ----- | ------------------------- |
-| `fee_load_factor`      | int64 | Current load factor       |
-| `fee_escalation_level` | int64 | Fee escalation multiplier |
-
-#### Validator Attributes
-
-| Key                      | Type  | Description               |
-| ------------------------ | ----- | ------------------------- |
-| `validator_list_size`    | int64 | UNL size                  |
-| `validator_list_age_sec` | int64 | Seconds since last update |
-
-#### Amendment Attributes
-
-| Key                | Type   | Description                            |
-| ------------------ | ------ | -------------------------------------- |
-| `amendment_name`   | string | Amendment name                         |
-| `amendment_status` | string | `"enabled"`, `"vetoed"`, `"supported"` |
-
-#### SHAMap Attributes
-
-| Key                    | Type    | Description                                   |
-| ---------------------- | ------- | --------------------------------------------- |
-| `shamap_type`          | string  | `"transaction"`, `"state"`, `"account_state"` |
-| `shamap_missing_nodes` | int64   | Number of missing nodes during sync           |
-| `shamap_duration_ms`   | float64 | Sync duration                                 |
-
-### 2.4.3 Data Collection Summary
-
-§2.4.2 above is the _planned_ catalogue; this table is the **implemented** one.
-Its left column lists the keys of the `attr` namespaces of the `*SpanNames.h`
-headers; every key shown has at least one live `attr::` set-site in
-non-test code. The right column lists keys this document once claimed were
-collected but which have no constant and no set-site at all.
-
-**This table is a category-level roll-up, not the authority.** The
-authoritative per-span breakdown — which span carries which attribute — is
-[09-data-collection-reference.md §1.2](./09-data-collection-reference.md#12-complete-attribute-inventory-bareunderscore-keys),
-and the exact key _spelling_ is owned by the `*SpanNames.h` constants. Where
-this table disagrees with either, they win.
-
-> **Known divergence (documented, not resolved here).** 09 §1.2's Consensus
-> subsection lists 47 keys; `include/xrpl/consensus/ConsensusSpanNames.h`
-> defines 54 in its `attr` namespace (48 own `makeStr` constants plus 6
-> `using` re-exports of the shared keys in `SpanNames.h`), all 54 with
-> set-sites. Five of the difference — `open_duration_ms`,
-> `peer_positions_at_close`, `position_hash_prefix`, `prev_ledger_prefix`,
-> `disputes_resolved_count` — are emitted but absent from 09 §1.2's consensus
-> table; the other two, `proposal_trusted` and `validation_trusted`, are
-> documented in 09 §1.2's Peer subsection instead (they are shared keys set on
-> both the `peer.*` and the `consensus.*` receive spans — `PeerImp.cpp:1953`
-> and `:2027` for the proposal pair, `:2591` and `:2635` for the validation
-> pair). Fixing 09 is tracked separately; the Consensus row below lists all 54.
-
-| Category        | Attributes emitted (from `*SpanNames.h`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Named here but NOT emitted                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Purpose                      |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| **Transaction** | `tx_hash`, `tx_type`, `ter_result`, `fee`, `sequence`, `current_ledger_seq`, `current_ledger_hash`, `local`, `path`, `tx_status`, `peer_version`, `peer_id`, `stage`, `applied`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `tx_result` (renamed → `ter_result`), `tx_fee` (→ `fee`), `ledger_index` (→ `current_ledger_seq`), `relay_count`. **`ledger_seq` is not a `tx.*` key**: no `tx.*` span sets it — the receive and apply-stage spans stamp `current_ledger_seq` (`NetworkOPs.cpp:1422`, `PeerImp.cpp:1337`, `Transactor.cpp:1613`, `applySteps.cpp:115`) and, where a view exists, `current_ledger_hash` (`Transactor.cpp:1615`, `applySteps.cpp:121`)                                                                                                                                                                                      | Trace transaction lifecycle  |
-| **Consensus**   | All 54 keys in `ConsensusSpanNames.h`'s `attr` namespace (48 own constants + 6 `using` re-exports), each with a set-site: `consensus_ledger_id`, `consensus_round`, `consensus_round_id`, `consensus_phase`, `consensus_mode`, `consensus_state`, `consensus_result`, `consensus_stalled`, `proposers`, `proposers_finished`, `previous_proposers`, `previous_ledger_seq`, `previous_round_time_ms`, `round_time_ms`, `open_duration_ms`, `quorum`, `proposing`, `is_bow_out`, `trace_strategy`, `converge_percent`, `establish_count`, `tx_count`, `tx_count_open`, `tx_id`, `disputes_count`, `disputes_resolved_count`, `dispute_our_vote`, `dispute_yays`, `dispute_nays`, `agree_count`, `disagree_count`, `threshold_percent`, `avalanche_threshold`, `close_time_threshold`, `have_close_time_consensus`, `close_time_resolution_ms`, `close_time_self_ripple_epoch_s`, `close_time_vote_bins`, `resolution_direction`, `parent_close_time_ripple_epoch_s`, `peer_positions_at_close`, `prev_ledger_prefix`, `position_hash_prefix`, `mode_old`, `mode_new`, `validation_sign_time`, `proposal_trusted`, `validation_trusted`; re-exported shared keys `ledger_seq`, `ledger_hash`, `full_validation`, `close_time_ripple_epoch_s`, `close_time_correct`, `close_resolution_ms` | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Analyze consensus timing     |
-| **RPC**         | `command`, `version`, `rpc_role`, `rpc_status`, `request_payload_size`, `is_batch`, `batch_size`, `load_type`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `duration_ms` (span duration is a TraceQL intrinsic — query `duration`), `params`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Monitor RPC performance      |
-| **Peer**        | `peer_id` (**int64**, the process-local `Peer::id_` slot number — not a key of any kind; also set on `tx.receive`), `proposal_trusted`, `validation_trusted`, `ledger_hash`, `full_validation`. (`peer_version` is **not** a peer-span key: the constant lives in `TxSpanNames.h:79` and its only set-site is `PeerImp.cpp:1342` on the `tx.receive` span — see the Transaction row)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `peer_address`, `peer_latency_ms`, `peer_cluster`, `message_type`, `message_size_bytes`, `message_compressed` — the peer-span coverage gap (§2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Network topology analysis    |
-| **Ledger**      | `ledger_seq`, `tx_count`, `tx_failed`, `validations`, `acquire_reason`, `timeouts`, `peer_count`, `outcome`, `close_time_ripple_epoch_s`, `close_time_correct`, `close_resolution_ms`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `ledger_index` (→ `ledger_seq`), `ledger_tx_count` (→ `tx_count`). `ledger_hash` is a live key, but **no `ledger.*` span sets it** — only `consensus.validation.send` (`RCLConsensus.cpp:977`; that span is the one returned by `createValidationSpan()`, which names `cs::validationSend` at `RCLConsensus.cpp:1365,1373`) and `peer.validation.receive` (`PeerImp.cpp:2573`) do. The `LedgerSpanNames.h:41` `using` alias has zero uses. `consensus.ledger_close` sets **no** hash: its four attributes are `ledger_seq`, `consensus_mode`, `tx_count_open` and `close_time_resolution_ms` (`RCLConsensus.cpp:354-361`) | Ledger progression tracking  |
-| **gRPC**        | `method`, `grpc_role`, `grpc_status`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | gRPC surface monitoring      |
-| **Job**         | — (no job spans exist)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `job_type`, `job_queue_ms`, `job_worker`. JobQueue is observed via **metrics**, not spans — but by **two disjoint families**, and only one of them has a `job_type` label. See the note below the table                                                                                                                                                                                                                                                                                                                                                                                                                   | JobQueue performance         |
-| **PathFinding** | `pathfind_fast`, `pathfind_search_level`, `pathfind_num_paths`, `pathfind_ledger_index`, `pathfind_num_requests`, `pathfind_num_source_assets`, `pathfind_dest_currency`, `pathfind_source_account` (hashed), `pathfind_dest_account` (hashed)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `pathfind_source_currency`, `pathfind_path_count`, `pathfind_cache_hit`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Payment path analysis        |
-| **TxQ**         | `txq_status`, `fee_level_paid`, `required_fee_level`, `queue_size`, `ledger_changed`, `expired_count`, `ter_code`, `retries_remaining`, `num_cleared`, `tx_type`, plus the re-exported shared keys `tx_hash`, `ledger_seq`, `current_ledger_seq`, `current_ledger_hash`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `txq_queue_depth` (→ `queue_size`), `txq_fee_level` (→ `fee_level_paid`), `txq_eviction_reason`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Queue depth and fee tracking |
-| **Fee**         | — (no `fee.escalate` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `fee_load_factor`, `fee_escalation_level`. Fee escalation is dashboarded from metrics (`fee-market`), not spans                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Fee escalation monitoring    |
-| **Validator**   | — (no `validator.*` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `validator_list_size`, `validator_list_age_sec`. UNL health is dashboarded from metrics (`validator-health`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | UNL health monitoring        |
-| **Amendment**   | — (no `amendment.vote` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `amendment_name`, `amendment_status`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Protocol upgrade tracking    |
-| **SHAMap**      | — (no `shamap.sync` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `shamap_type`, `shamap_missing_nodes`, `shamap_duration_ms`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | State tree sync performance  |
-
-The right-hand column is the honest gap list: every key in it appears in the
-§2.4.2 design catalogue but has **zero set-sites** in the code. Where a rename
-happened the live name is given in parentheses; where the concept shipped as a
-metric rather than a span that is stated. Do not build a dashboard panel, an
-alert rule, or a TraceQL query against anything in that column — the query will
-return empty, and (per the PromQL/TraceQL asymmetry) a `=~".*"` matcher on an
-absent attribute silently blanks a TraceQL panel while quietly passing in
-PromQL.
-
-> **JobQueue metrics: two families, one label.** The Job row above has no span
-> attributes, and the metrics that replace them do **not** all carry a
-> `job_type` label. Getting this wrong produces a panel that renders but is
-> wrong, so treat the two families as separate query surfaces:
->
-> | Family                                                                                                                   | Where the job type lives                                                | Source                                                                                      |
-> | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-> | Native `XRPL_METRIC_*`: `job_queued_total`, `job_started_total`, `job_finished_total`, `job_queued_us`, `job_running_us` | In a **`job_type` label**                                               | `MetricsRegistry.cpp:360-362` (counters), `:94-95` (histogram names), `:101` (label key)    |
-> | `beast::insight` `jobq` group: `jobq_<jobtype>_waiting` / `_running` / `_deferred` / `_q`                                | In the **metric name itself** — there is **no** `job_type` label at all | `JobTypeData.h:29-32` (naming contract), `:35-38` (suffixes), `Application.cpp:392` (group) |
->
-> **The trap:** `sum by (job_type)(jobq_…)` collapses every job type into a
-> single series with an empty `job_type`, because an absent PromQL label is
-> equivalent to `""` — the query returns a plausible-looking number rather than
-> an error. Aggregate the `jobq_*` family with a name matcher
-> (`{__name__=~"jobq_.*_waiting"}`) and reserve `by (job_type)` for the
-> `job_*_total` / `job_*_us` family.
-
-### 2.4.4 Privacy & Sensitive Data Policy
-
-> **PII** = Personally Identifiable Information
-
-OpenTelemetry instrumentation is designed to collect **operational metadata only**, never sensitive content.
-
-#### Data NOT Collected
-
-The following data is explicitly **excluded** from telemetry collection:
-
-| Excluded Data           | Reason                                                                                                                                                                                                                                                |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Private Keys**        | Never exposed; not relevant to tracing                                                                                                                                                                                                                |
-| **Account Balances**    | Financial data; privacy sensitive                                                                                                                                                                                                                     |
-| **Transaction Amounts** | Financial data; privacy sensitive                                                                                                                                                                                                                     |
-| **Raw TX Payloads**     | May contain sensitive memo/data fields                                                                                                                                                                                                                |
-| **Personal Data**       | No PII collected                                                                                                                                                                                                                                      |
-| **IP Addresses**        | **Never in spans** — no span sets an address attribute (`peer_address` has zero set-sites); peer spans identify peers by `peer_id`, an int64 process-local slot number. **But the log pipeline is a different story** — see the note below this table |
-
-> **Peer IPs DO leave the node — via the log pipeline, not via spans.** The
-> "IP Addresses" row above is scoped to spans, and only to spans. This same
-> document describes a log pipeline (§2.6.5) that carries peer addresses:
->
-> 1. `PeerImp`'s constructor logs the peer's `remoteAddress_` — an `IP:port` —
->    at `info` severity (`PeerImp.h:837-842`), and other overlay call sites log
->    addresses too. These land in the ordinary `debug.log` stream.
-> 2. The collector's `file_log` receiver tails exactly that file
->    (`otel-collector-config.yaml:38-47`, `include: [/var/log/xrpld/*/debug.log]`)
->    and the `logs` pipeline exports it to Loki (`:236-239`).
->
-> So a deployment running the shipped stack **does** ship peer IPs off-box, as
-> log bodies. There is no attribute to drop and no span-level switch to flip,
-> because the IPs are inside free-text log messages rather than in structured
-> fields — a `delete` action on an attribute key would not touch them.
->
-> **The control points are therefore log-side, not trace-side:** Loki
-> retention and access control on the log store; the `file_log` receiver's
-> `include` list (dropping it disables log↔trace correlation entirely); or a
-> collector-side transform on the log body. Do not describe the telemetry
-> pipeline as IP-free without qualifying it to traces.
-
-#### Privacy Protection Mechanisms
-
-| Mechanism                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Account Addresses**         | Emitted raw (`pathfind_source_account`, `pathfind_dest_account`). An account address is a public ledger identifier; hashing it protects nothing and breaks the join against explorers, RPC and logs                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| **Collector Tail Sampling**   | **Optional, and OFF in the base stack.** xrpld head sampling is fixed at 1.0 (`Telemetry.h:234` `static constexpr double samplingRatio = 1.0;`), so 100% of traces leave the node. `docker/telemetry/otel-collector-config.yaml` has **no** `tail_sampling` processor either, so the local stack stores 100%. The only shipped policy is in the Grafana Cloud overlay (`otel-collector-config.grafanacloud.yaml:60-67`, wired at `:261`): one `probabilistic` policy at **0.5%**, on the trace-storage branch only so spanmetrics still see every span. Treat sampling as a cost control you opt into — not as a privacy control |
-| **Local Control**             | Node operators have full control over what gets exported                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| **No Raw Payloads**           | Transaction content is never recorded, only metadata (hash, type, result)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| **Collector-Level Filtering** | Available for a future genuinely sensitive attribute via an `attributes` processor. None is shipped, and none must be added for account addresses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-
-#### Account Addresses
-
-Account addresses are emitted **raw**, at every layer:
-
-1. **SDK-side** (this node): the path-finding RPC handlers set
-   `pathfind_source_account` / `pathfind_dest_account` to the request's
-   r-address, only when it parses as one, and `pathfind_dest_currency` to `to_string(Asset)`,
-   which carries the IOU issuer's r-address. The rationale sits on the attribute
-   constants in `PathFindSpanNames.h`.
-2. **Collector-side**: no collector configuration in this repository hashes
-   or deletes these attributes.
-
-Why raw: an r-address is a public, enumerable identifier on the ledger. An
-unsalted hash of it is reversible by table lookup, so it protects nothing, and
-it breaks the one thing the attribute is for: joining a span to the account as
-explorers, RPC responses and logs show it. The helper `redactAccount()`
-(`xrpl::telemetry`, `Redaction.h`) remains available for a value that is
-genuinely private, but it is applied to no span.
-
-#### Collector-Level Data Protection
-
-No hashing or redaction processor is shipped: account addresses are public
-identifiers and stay as emitted.
-
-**No `peer_address` or `params` scrubbing rule is needed on the trace pipeline,
-and none is shipped.** Earlier drafts prescribed `delete` actions for both.
-Neither attribute is ever emitted: `peer_address` has zero set-sites in the code
-(peer spans carry `peer_id`, an int64 process-local slot number — not an IP and
-not a key), and no span sets a `params` attribute — RPC spans carry `command`,
-`version`, `rpc_role`, `rpc_status`, `request_payload_size`, `is_batch`,
-`batch_size` and `load_type`, never the request body. Adding delete rules for
-absent keys would be harmless but misleading: it would imply the node emits IPs
-and request parameters in spans when it does not.
-
-This says nothing about the **log** pipeline, which is where peer IPs actually
-do leave the node (see the note under "Data NOT Collected" above). An
-`attributes` processor cannot help there — the addresses are inside free-text
-log bodies, not in structured attributes.
-
-If a future span _does_ introduce an IP-bearing or payload-bearing attribute,
-the `attributes` processor is the right place to strip it — and the attribute
-should be added to the §2.4 catalogue in the same change.
-
-#### Configuration Options for Privacy
-
-In `xrpld.cfg`, operators control data collection granularity through the
-`[telemetry]` section. Besides `enabled`, per-component toggles
-(`trace_transactions`, `trace_consensus`, `trace_rpc`, `trace_peer` — the last
-often disabled due to high volume) select which spans are emitted. There is no
-redaction setting: account addresses are public and are emitted raw.
-
-> **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes, public identifiers) — never **sensitive content** (keys, balances, amounts, raw payloads).
-
----
-
-## 2.5 Context Propagation Design
-
-> **WS** = WebSocket
-
-### 2.5.0 Deterministic Trace ID Strategy
-
-Both transaction and consensus tracing use **deterministic trace IDs** derived from
-a globally known hash, so all nodes handling the same workflow independently produce
-spans under the same `trace_id`. This is combined with protobuf `span_id` propagation
-for parent-child relay ordering when available.
-
-#### Transactions — `trace_id = txHash[0:16]`
-
-Every node that handles a transaction knows its `txID` (the `uint256` transaction
-hash). The first 16 bytes of this hash are used as the OTel `trace_id`:
-
-```
-uint256 txHash:  A1B2C3D4 E5F6A7B8 C9D0E1F2 A3B4C5D6  E7F8A9B0 C1D2E3F4 A5B6C7D8 E9F0A1B2
-                 |---------- trace_id (16 bytes) ---------|  (remaining 16 bytes unused)
-```
-
-Each node generates a **random 8-byte `span_id`** so its span is unique within the
-shared trace. When protobuf `TraceContext` is present in the incoming `TMTransaction`,
-the sender's `span_id` is extracted and used as the parent — preserving the relay
-chain as a parent-child tree. When absent (older peers, first hop from client), the
-span appears as a root in the same trace — correlation is preserved, only the tree
-structure degrades.
-
-```
-Node A (submitter)        Node B (relay)          Node C (relay)
-trace_id: A1B2...         trace_id: A1B2...       trace_id: A1B2...
-span_id:  1234 (random)   span_id:  5678 (random) span_id:  9ABC (random)
-parent:   (none)          parent:   1234 (proto)   parent:   5678 (proto)
-                               ↑                        ↑
-                       protobuf propagation      protobuf propagation
-```
-
-If protobuf propagation fails at Node B (old peer):
-
-```
-Node A                    Node B (old peer)       Node C
-trace_id: A1B2...         trace_id: A1B2...       trace_id: A1B2...
-span_id:  1234            span_id:  5678          span_id:  9ABC
-parent:   (none)          parent:   (none)        parent:   5678 (proto)
-                          ↑ no parent, but same trace_id — still grouped
-```
-
-#### Consensus — `trace_id = prevLedgerHash[0:16]`
-
-All validators in the same consensus round share the same `previousLedger.id()`.
-The first 16 bytes are used as trace_id. See [Phase 4a implementation status](./06-implementation-phases.md)
-and `createDeterministicContext()` in `RCLConsensus.cpp` for the implementation.
-
-Switchable via `consensus_trace_strategy` config:
-`"deterministic"` (default) or `"random"` (random trace_id, correlation via attribute queries).
-`"random"` is experimental and not used: it would break cross-node trace correlation.
-
-#### Why Not Random IDs with Propagation Only?
-
-Random trace IDs require **unbroken context propagation** across every hop. In a
-mixed-version network (common during upgrades), older peers silently drop the
-`trace_context` protobuf field. The trace splits and downstream spans become
-impossible to find. Deterministic IDs make correlation **propagation-resilient** — the trace
-backend groups all spans for the same transaction/round regardless of whether
-propagation succeeded.
-
-#### Why Keep Protobuf Propagation?
-
-Deterministic trace IDs alone provide correlation (all spans grouped) but not
-**causality** (which node relayed to which). Protobuf `span_id` propagation adds
-parent-child ordering that shows the exact relay path. The two mechanisms complement
-each other:
-
-| Mechanism                    | Provides                    | Fails when                             |
-| ---------------------------- | --------------------------- | -------------------------------------- |
-| Deterministic trace_id       | Cross-node correlation      | Never (hash is always known)           |
-| Protobuf span_id propagation | Parent-child relay ordering | Older peer drops `trace_context` field |
-
-#### Implementation Reference
-
-The utility function `createDeterministicTxContext(uint256 const& txHash)` follows
-the same pattern as `createDeterministicContext(uint256 const& ledgerId)` in
-`RCLConsensus.cpp`. See [Phase 3 Task 3.9](./Phase3_taskList.md) for the full spec.
-
-### 2.5.1 Propagation Boundaries
-
-```mermaid
-flowchart TB
-    subgraph http["HTTP/WebSocket (RPC)"]
-        w3c["W3C Trace Context Headers:<br/>traceparent:<br/>00-trace_id-span_id-flags<br/>tracestate: xrpld=..."]
-    end
-
-    subgraph protobuf["Protocol Buffers (P2P)"]
-        proto["message TraceContext {<br/>  bytes trace_id = 1;  // 16 bytes<br/>  bytes span_id = 2;   // 8 bytes<br/>  uint32 trace_flags = 3;<br/>  string trace_state = 4;<br/>}"]
-    end
-
-    subgraph jobqueue["JobQueue / Coroutines (Internal Async)"]
-        job["CoroAwareContextStorage<br/>(RuntimeContextStorage override)<br/><br/>Per-coroutine context stack,<br/>installed globally at startup.<br/>Job itself carries no context."]
-    end
-
-    style http fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style protobuf fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style jobqueue fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **HTTP/WebSocket - RPC (blue)**: For client-facing RPC requests, trace context is propagated using the W3C `traceparent` header. This is the standard approach and works with any OTel-compatible client.
-- **Protocol Buffers - P2P (green)**: For peer-to-peer messages between xrpld nodes, trace context is embedded as a protobuf `TraceContext` message carrying trace_id, span_id, flags, and optional trace_state.
-- **JobQueue / Coroutines - Internal Async (red)**: For asynchronous work within a single node, the ambient OTel context follows the coroutine rather than being carried on the work item. `include/xrpl/core/Job.h` has **no** telemetry include and no `traceContext_` member — an earlier draft of this diagram showed one, and that was never built. Instead `xrpl::telemetry::CoroAwareContextStorage` (`include/xrpl/telemetry/CoroAwareContextStorage.h:84`) overrides the SDK's `RuntimeContextStorage` with a per-coroutine context stack, and is installed as the global storage in `Telemetry::start()` (`Telemetry.cpp:416-419`) before the tracer provider and before the first span. That fixes the wrong-thread scope pop across coroutine yield/resume and keeps log↔trace correlation intact. The storage is never reset — tearing it down while spans may still exist is undefined behaviour in the SDK — so it lives for the process lifetime.
-
----
-
-## 2.6 Integration with Existing Observability
-
-> **OTLP** = OpenTelemetry Protocol | **WS** = WebSocket
-
-### 2.6.1 Existing Frameworks Comparison
-
-xrpld already has two observability mechanisms. OpenTelemetry complements (not replaces) them:
-
-| Aspect                | PerfLog                       | Beast Insight (StatsD)       | OpenTelemetry             |
-| --------------------- | ----------------------------- | ---------------------------- | ------------------------- |
-| **Type**              | Logging                       | Metrics                      | Distributed Tracing       |
-| **Data**              | JSON log entries              | Counters, gauges, histograms | Spans with context        |
-| **Scope**             | Single node                   | Single node                  | **Cross-node**            |
-| **Output**            | `perf.log` file               | StatsD server                | OTLP Collector            |
-| **Question answered** | "What happened on this node?" | "How many? How fast?"        | "What was the journey?"   |
-| **Correlation**       | By timestamp                  | By metric name               | By `trace_id`             |
-| **Overhead**          | Low (file I/O)                | Low (UDP packets)            | Low-Medium (configurable) |
-
-### 2.6.2 What Each Framework Does Best
-
-#### PerfLog
-
-- **Purpose**: Detailed local event logging for RPC and job execution
-- **Strengths**:
-  - Rich JSON output with timing data
-  - Already integrated in RPC handlers
-  - File-based, no external dependencies
-- **Limitations**:
-  - Single-node only (no cross-node correlation)
-  - No parent-child relationships between events
-  - Manual log parsing required
-
-A PerfLog entry is a JSON object with fields such as `time`, `method`,
-`duration_us`, and `result`.
-
-#### Beast Insight (StatsD)
-
-- **Purpose**: Real-time metrics for monitoring dashboards
-- **Strengths**:
-  - Aggregated metrics (counters, gauges, histograms)
-  - Low overhead (UDP, fire-and-forget)
-  - Good for alerting thresholds
-- **Limitations**:
-  - No request-level detail
-  - No causal relationships
-  - Single-node perspective
-  - Aggregation happens on the StatsD server, not in the process
-
-In xrpld, Beast Insight is used through `increment` (counters), `gauge`
-(point-in-time values), and `timing` (durations) calls. A `timing` call sends
-each measured value as its own raw `|ms` sample, so the histogram a dashboard
-reads is built by the StatsD server from that stream of values.
-
-#### OpenTelemetry (NEW)
-
-- **Purpose**: Distributed request tracing across nodes
-- **Strengths**:
-  - **Cross-node correlation** via `trace_id`
-  - Parent-child span relationships
-  - Rich attributes per span
-  - A `Histogram` instrument that aggregates **at the point of measure**
-  - Industry standard (CNCF)
-- **Limitations**:
-  - Requires collector infrastructure
-  - Higher complexity than logging
-
-A span is created via `startSpan` (e.g. `"tx.relay"`), annotated with
-attributes such as `tx_hash` and `peer_id`, and is automatically linked to its
-parent through the active context.
-
-OpenTelemetry is not only spans. The same SDK offers a `Histogram` instrument,
-and a `Record()` call folds the value straight into bucket counts inside the
-process — no per-event record is shipped and no server-side aggregation step is
-needed. That is what makes it affordable in a hot loop where one span per event
-would not be, and it is the one thing Beast Insight cannot do, because its
-`timing` path ships raw values and aggregates them on the StatsD server.
-
-### 2.6.3 When to Use Each
-
-| Scenario                                | PerfLog    | StatsD | OpenTelemetry |
-| --------------------------------------- | ---------- | ------ | ------------- |
-| "How many TXs per second?"              | ❌         | ✅     | ✅            |
-| "What's the p99 RPC latency?"           | ❌         | ✅     | ✅            |
-| "Why was this specific TX slow?"        | ⚠️ partial | ❌     | ✅            |
-| "Which node delayed consensus?"         | ❌         | ❌     | ✅            |
-| "What happened on node X at time T?"    | ✅         | ❌     | ✅            |
-| "Show me the TX journey across 5 nodes" | ❌         | ❌     | ✅            |
-| "p99 NodeStore fetch latency?"          | ❌         | ❌     | ✅            |
-
-The last row is the case a span cannot answer. One `TMGetObjectByHash` message
-requests up to `tuning::kHardMaxReplyNodes` objects, so a span per NodeStore
-fetch is not affordable in that loop. Instead the fetch loop's wall time is
-recorded once per message into an OpenTelemetry `Histogram`
-(`getobject_lookup_us`), and the quantile is read off its buckets. StatsD is
-marked ❌ because that instrument is recorded on the native OpenTelemetry metrics
-path, not through Beast Insight.
-
-### 2.6.4 Coexistence Strategy
-
-> **Note**: Phase 7 **added** a native OTel Metrics export path alongside the
-> StatsD bridge; it did not replace it. The diagram below shows the Phase 6
-> state, which is still reachable today via `[insight] server=statsd`. See
-> [Phase7_taskList.md](./Phase7_taskList.md) for the design.
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Process"]
-        perflog["PerfLog<br/>(JSON to file)"]
-        insight["Beast Insight<br/>(StatsD)"]
-        otel["OpenTelemetry<br/>(Tracing)"]
-    end
-
-    perflog --> perffile["perf.log"]
-    insight --> statsd["StatsD Server"]
-    otel --> collector["OTLP Collector"]
-
-    perffile --> grafana["Grafana<br/>(Unified UI)"]
-    statsd --> grafana
-    collector --> grafana
-
-    style xrpld fill:#212121,stroke:#0a0a0a,color:#ffffff
-    style grafana fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **xrpld Process (dark gray)**: The single xrpld node running all three observability frameworks side by side. Each framework operates independently with no interference.
-- **PerfLog to perf.log**: PerfLog writes JSON-formatted event logs to a local file. Grafana can ingest these via Loki or a file-based datasource.
-- **Beast Insight to StatsD Server**: Insight sends aggregated metrics (counters, gauges) over UDP to a StatsD server. Grafana reads from StatsD-compatible backends like Graphite or Prometheus (via StatsD exporter).
-- **OpenTelemetry to OTLP Collector**: OTel exports spans over OTLP/HTTP to a Collector, which then forwards to a trace backend (Tempo). (OTLP/gRPC is future work — §2.2.2.)
-- **Grafana (red, unified UI)**: All three data streams converge in Grafana, enabling operators to correlate logs, metrics, and traces in a single dashboard.
-
-**Phase 7 outcome (as shipped)**: Beast Insight gained an `OTelCollector`
-`Collector` implementation that rides the global MeterProvider and exports via
-OTLP/HTTP to the same collector as traces. It is selected with
-`[insight] server=otel`.
-
-The three back ends are **co-equal branches of one `if/else` chain** in
-`makeCollectorManager()` (`CollectorManager.cpp:37-75`), not a migration path:
-
-| `[insight] server=`    | Collector         | Status                                                                                                                                   |
-| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `otel`                 | `OTelCollector`   | OTLP/HTTP to the OTel Collector — the recommended setting                                                                                |
-| `statsd`               | `StatsDCollector` | Unchanged from before Phase 7. **Not deprecated**: no warning is logged, no removal is scheduled, and the code path is not marked legacy |
-| absent / anything else | `NullCollector`   | **The default.** A node with no `[insight]` section emits no metrics at all                                                              |
-
-Two corrections to earlier drafts, both of which matter operationally: StatsD
-is not a "deprecated fallback", and `otel` is not the default — you must set it
-explicitly. See [06-implementation-phases.md §6.8](./06-implementation-phases.md),
-[Phase7_taskList.md](./Phase7_taskList.md), and
-[05 §5.8.6](./05-configuration-reference.md) for which `[insight]` keys are live
-under `server=otel` (most are inert).
-
-### 2.6.5 Correlation with Logs
-
-**Shipped in Phase 8 — and not the way this section originally planned it.**
-The design here was a `setTraceId` hook on PerfLog, fed from the
-`rpc.command.<method>` span in `RPCHandler.cpp`. That hook was never built:
-`setTraceId` has zero occurrences in **source** — the only hits in the tree are
-in these plan documents, describing the design that was dropped — and PerfLog's
-JSON output carries no trace ID.
-
-What shipped instead is broader and needs no per-call-site wiring: the **journal
-sink** stamps the IDs onto _every_ log line written while a span is active.
-`Logs::format()` (`src/libxrpl/basics/Log.cpp:304-338`, inside
-`#ifdef XRPL_ENABLE_TELEMETRY`) reads the thread-local OTel context, and when
-the active span context is valid it prefixes the message with
-`trace_id=<32 hex> span_id=<16 hex>`. It inspects the context value directly
-rather than calling `GetSpan()`, so the common no-span path costs no heap
-allocation.
-
-Because the IDs land in the ordinary `debug.log` stream, correlation is
-end-to-end without touching PerfLog: the collector's `file_log` receiver parses
-`trace_id`/`span_id` as optional capture groups and ships the lines to Loki, and
-Grafana links both directions (Tempo `tracesToLogs` → Loki, Loki derived fields
-→ Tempo). Details in [05 §5.8.5](./05-configuration-reference.md).
-
-RPC spans still exist and still set status (OK on success, error with the
-recorded exception on failure) — that part of the original design is intact.
-Only the PerfLog-stamping mechanism was replaced.
-
----
-
-_Previous: [Architecture Analysis](./01-architecture-analysis.md)_ | _Next: [Implementation Strategy](./03-implementation-strategy.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/03-implementation-strategy.md

@@ -1,545 +0,0 @@
-# Implementation Strategy
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Configuration Reference](./05-configuration-reference.md)
-
----
-
-## 3.1 Directory Structure
-
-The telemetry implementation follows xrpld's existing code organization
-pattern. The tree below is the current on-disk contents of the three telemetry
-directories, and it has three differences from the original design sketch worth
-calling out: `TelemetryConfig.h`, `TraceContext.h`, `SpanAttributes.h` and
-`TraceContext.cpp` were never created (config structs live inside
-`Telemetry.h`, propagation lives in `TraceContextPropagator.h`, and attribute
-constants live in the `*SpanNames.h` headers next to their owning class); the
-metrics work of Phase 7/9 added a whole second module under
-`src/xrpld/telemetry/`, which the sketch predated.
-
-```
-include/xrpl/telemetry/            # libxrpl layer: tracing SDK wrapper
-├── Telemetry.h                    # Interface + Setup config struct + factories
-├── SpanGuard.h                    # RAII span management, factory methods, discard()
-├── SpanNames.h                    # StaticStr/join() + shared span & attr constants
-├── DiscardFlag.h                  # Thread-local discard flag
-├── CoroAwareContextStorage.h      # RuntimeContextStorage override for coroutines
-├── DeterministicIdGenerator.h     # trace_id from txHash / prevLedgerHash
-├── TraceContextPropagator.h       # protobuf TraceContext inject/extract (P2P)
-├── TraceContextValidation.h       # Validation of peer-supplied trace context
-├── Redaction.h                    # redactAccount() — hashing helper, applied to no span
-└── GetObjectMetricNames.h         # getobject_* metric name constants
-
-src/libxrpl/telemetry/
-├── Telemetry.cpp                  # TelemetryImpl + FilteringSpanProcessor + initMetrics()
-├── TelemetryConfig.cpp            # [telemetry] section parsing (makeTelemetrySetup)
-├── SpanGuard.cpp                  # Span/scope guard implementation
-├── CoroAwareContextStorage.cpp
-├── DeterministicIdGenerator.cpp
-├── Redaction.cpp
-└── NullTelemetry.cpp              # No-op impl — ALWAYS compiled (in-source #ifdef)
-
-src/xrpld/telemetry/               # xrpld layer: native metrics + tx tracing helpers
-├── MetricsRegistry.h / .cpp       # Owns the XRPL_METRIC_* instruments + MeterProvider
-├── MetricMacros.h                 # XRPL_METRIC_COUNTER_ADD / _HISTOGRAM_RECORD / ...
-├── ValidationTracker.h            # Validation-agreement tracking (impl in detail/)
-├── detail/ValidationTracker.cpp
-├── ConsensusReceiveTracing.h      # Peer proposal/validation receive spans
-├── PropagationHelpers.h           # Context inject/extract call-site helpers
-├── TxSpanNames.h                  # tx.* span + attribute constants
-└── TxTracing.h                    # Transaction span helpers
-```
-
-Per-class span-name headers deliberately live next to their owning class rather
-than in `telemetry/` — see `ConsensusSpanNames.h`, `TxApplySpanNames.h`,
-`LedgerSpanNames.h`, `RpcSpanNames.h`, `PathFindSpanNames.h`,
-`PeerSpanNames.h`, `TxQSpanNames.h`, `GrpcSpanNames.h`.
-
----
-
-## 3.2 Implementation Approach
-
-<div align="center">
-
-```mermaid
-%%{init: {'flowchart': {'nodeSpacing': 20, 'rankSpacing': 30}}}%%
-flowchart TB
-    subgraph phase1["Phase 1: Core"]
-        direction LR
-        sdk["SDK Integration"] ~~~ interface["Telemetry Interface"] ~~~ config["Configuration"]
-    end
-
-    subgraph phase2["Phase 2: RPC"]
-        direction LR
-        http["HTTP Context"] ~~~ rpc["RPC Handlers"]
-    end
-
-    subgraph phase3["Phase 3: P2P"]
-        direction LR
-        proto["Protobuf Context"] ~~~ tx["Transaction Relay"]
-    end
-
-    subgraph phase4["Phase 4: Consensus"]
-        direction LR
-        consensus["Consensus Rounds"] ~~~ proposals["Proposals"]
-    end
-
-    phase1 --> phase2 --> phase3 --> phase4
-
-    style phase1 fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style phase2 fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style phase3 fill:#e65100,stroke:#bf360c,color:#ffffff
-    style phase4 fill:#c2185b,stroke:#880e4f,color:#ffffff
-```
-
-</div>
-
-### Key Principles
-
-1. **Minimal Intrusion**: Instrumentation should not alter existing control flow
-2. **Zero-Cost When Disabled**: Use compile-time flags and no-op implementations
-3. **Backward Compatibility**: Protocol Buffer extensions use high field numbers
-4. **Graceful Degradation**: Tracing failures must not affect node operation
-
----
-
-## 3.3 Performance Overhead Summary
-
-> **OTLP** = OpenTelemetry Protocol
-
-| Metric        | Overhead   | Notes                                            |
-| ------------- | ---------- | ------------------------------------------------ |
-| CPU           | 1-3%       | Of per-transaction CPU cost (~200μs baseline)    |
-| Memory        | ~10 MB     | SDK statics + batch buffer + worker thread stack |
-| Network       | 10-50 KB/s | Compressed OTLP export to collector              |
-| Latency (p99) | <2%        | With proper sampling configuration               |
-
----
-
-## 3.4 Detailed CPU Overhead Analysis
-
-### 3.4.1 Per-Operation Costs
-
-> **Note on hardware assumptions**: The costs below are based on the official OTel C++ SDK CI benchmarks
-> (969 runs on GitHub Actions 2-core shared runners). On production server hardware (3+ GHz Xeon),
-> expect costs at the **lower end** of each range (~30-50% improvement over CI hardware).
-
-| Operation             | Time (ns) | Frequency              | Impact     |
-| --------------------- | --------- | ---------------------- | ---------- |
-| Span creation         | 500-1000  | Every traced operation | Low        |
-| Span end              | 100-200   | Every traced operation | Low        |
-| SetAttribute (string) | 80-120    | 3-5 per span (typical) | Low        |
-| SetAttribute (int)    | 40-60     | 2-3 per span (typical) | Negligible |
-| AddEvent              | 100-200   | 0-2 per span           | Low        |
-| Context injection     | 150-250   | Per outgoing message   | Low        |
-| Context extraction    | 100-180   | Per incoming message   | Low        |
-| GetCurrent context    | 10-20     | Thread-local access    | Negligible |
-
-> **"3-5 attributes per span" is a typical case, not a bound.** The frequency
-> column above describes the median span (`tx.receive`, `rpc.command.*`). A few
-> spans are deliberately attribute-rich: `consensus.accept.apply` sets **13**
-> attributes (`RCLConsensus.cpp:600-674`), and `consensus.round` /
-> `consensus.establish` are of the same order. Use ~15 as the worst case when
-> sizing per-span attribute cost and memory; the consensus spans that hit it fire
-> once per ~3-second round, so their absolute cost stays in the noise
-> (see §3.4.3).
-
-**Source**: Span creation based on OTel C++ SDK `BM_SpanCreation` benchmark (AlwaysOnSampler +
-SimpleSpanProcessor + InMemoryExporter), median ~1,000 ns on CI hardware. AddEvent includes
-timestamp read + string copy + vector push + mutex acquisition. Context injection/extraction
-confirmed by `BM_SpanCreationWithScope` benchmark delta (~160 ns).
-
-### 3.4.2 Transaction Processing Overhead
-
-<div align="center">
-
-```mermaid
-%%{init: {'pie': {'textPosition': 0.75}}}%%
-pie showData
-    "tx.receive (1400ns)" : 1400
-    "tx.process (1200ns)" : 1200
-    "tx.apply (1200ns)" : 1200
-    "Context inject (200ns)" : 200
-```
-
-**Transaction Tracing Overhead (~4.0μs total)**
-
-</div>
-
-**Overhead percentage**: 4.0 μs / 200 μs (avg tx processing) = **~2.0%**
-
-> **Breakdown**: Each span (tx.receive, tx.process, tx.apply) costs ~1,000 ns for creation plus
-> ~200-400 ns for 3-5 attribute sets. Context injection is ~200 ns (confirmed by benchmarks).
-> On production hardware, expect ~2.6 μs total (~1.3% overhead) due to faster span creation (~500-600 ns).
->
-> This three-span model predates the apply-pipeline instrumentation. The shipped
-> transaction path also emits `tx.preflight`, `tx.preclaim` and `tx.transactor`
-> (the spans planned here as `tx.validate`), and never emits `tx.relay`. Scale
-> the estimate by span count for a current figure: ~6 spans ≈ 7-8 μs on CI
-> hardware, ~4-5 μs on server hardware. The measured end-to-end cost is in
-> §3.5.3 (~3-4% throughput at head sampling 1.0), which supersedes this
-> bottom-up estimate.
-
-### 3.4.3 Consensus Round Overhead
-
-| Operation              | Count | Cost (ns) | Total      |
-| ---------------------- | ----- | --------- | ---------- |
-| consensus.round span   | 1     | ~1200     | ~1.2 μs    |
-| consensus.phase spans  | 3     | ~1100     | ~3.3 μs    |
-| proposal.receive spans | ~20   | ~1100     | ~22 μs     |
-| proposal.send spans    | ~3    | ~1100     | ~3.3 μs    |
-| Context operations     | ~30   | ~200      | ~6 μs      |
-| **TOTAL**              |       |           | **~36 μs** |
-
-> **Why higher**: Each span costs ~1,000 ns creation + ~100-200 ns for 1-2 attributes, totaling ~1,100-1,200 ns.
-> Context operations remain ~200 ns (confirmed by benchmarks). On production hardware, expect ~24 μs total.
->
-> The "1-2 attributes" figure understates the shipped consensus spans, which are
-> the attribute-rich ones: `consensus.accept.apply` alone sets 13
-> (`RCLConsensus.cpp:600-674`). Adding ~1 μs per such span still leaves the
-> round total under ~40 μs against a ~3 s round, so the conclusion below is
-> unaffected. Note also that the `consensus.phase` row covers the shipped names
-> `consensus.phase.open`, `consensus.establish` and `consensus.accept` — see
-> [02 §2.3.2](./02-design-decisions.md).
-
-**Overhead percentage**: 36 μs / 3s (typical round) = **~0.001%** (negligible)
-
-### 3.4.4 RPC Request Overhead
-
-| Operation                                  | Cost (ns)    |
-| ------------------------------------------ | ------------ |
-| `rpc.http_request` / `rpc.ws_message` span | ~1200        |
-| `rpc.command.*` span                       | ~1100        |
-| Context extract                            | ~250         |
-| Context inject                             | ~200         |
-| **TOTAL**                                  | **~2.75 μs** |
-
-> **Why higher**: Each span costs ~1,000 ns creation + ~100-200 ns for attributes (command name,
-> version, role). Context extract/inject costs are confirmed by OTel C++ benchmarks.
-
-- Fast RPC (1ms): 2.75 μs / 1ms = **~0.275%**
-- Slow RPC (100ms): 2.75 μs / 100ms = **~0.003%**
-
----
-
-## 3.5 Memory Overhead Analysis
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 3.5.1 Static Memory
-
-| Component                            | Size        | Allocated  |
-| ------------------------------------ | ----------- | ---------- |
-| TracerProvider singleton             | ~64 KB      | At startup |
-| BatchSpanProcessor (circular buffer) | ~16 KB      | At startup |
-| BatchSpanProcessor (worker thread)   | ~8 MB       | At startup |
-| OTLP/HTTP exporter (client init)     | ~64 KB      | At startup |
-| Propagator registry                  | ~8 KB       | At startup |
-| **Total static**                     | **~8.1 MB** |            |
-
-> **Why higher than earlier estimate**: The BatchSpanProcessor's circular buffer itself is only ~16 KB
-> (2049 x 8-byte `AtomicUniquePtr` entries), but it spawns a dedicated worker thread whose default
-> stack size on Linux is ~8 MB. The OTLP/HTTP exporter allocates a small client and TLS
-> initialization buffer. The worker thread stack dominates the static footprint.
-
-### 3.5.2 Dynamic Memory
-
-| Component            | Size per unit  | Max units  | Peak            |
-| -------------------- | -------------- | ---------- | --------------- |
-| Active span          | ~500-800 bytes | 1000       | ~500-800 KB     |
-| Queued span (export) | ~500 bytes     | 2048       | ~1 MB           |
-| Attribute storage    | ~80 bytes      | 5 per span | Included        |
-| Context storage      | ~64 bytes      | Per thread | ~6.4 KB         |
-| **Total dynamic**    |                |            | **~1.5-1.8 MB** |
-
-> **Why active spans are larger**: An active `Span` object includes the wrapper (~88 bytes: shared_ptr,
-> mutex, unique_ptr to Recordable) plus `SpanData` (~250 bytes: SpanContext, timestamps, name, status,
-> empty containers) plus attribute storage (~200-500 bytes for 3-5 string attributes in a `std::map`).
-> Source: `sdk/src/trace/span.h` and `sdk/include/opentelemetry/sdk/trace/span_data.h`.
-> Queued spans release the wrapper, keeping only `SpanData` + attributes (~500 bytes).
-
-### 3.5.3 Memory Growth Characteristics
-
-```mermaid
----
-config:
-    xyChart:
-        width: 700
-        height: 400
----
-xychart-beta
-    title "Memory Usage vs Span Rate (bounded by queue limit)"
-    x-axis "Spans/second" [0, 200, 400, 600, 800, 1000]
-    y-axis "Memory (MB)" 0 --> 12
-    line [8.5, 9.2, 9.6, 9.9, 10.0, 10.0]
-```
-
-**Notes**:
-
-- Memory increases with span rate but **plateaus at queue capacity** (default 2048 spans)
-- Batch export prevents unbounded growth
-- At queue limit, oldest spans are dropped (not blocked)
-- Maximum memory is bounded: ~8.3 MB static (dominated by worker thread stack) + 2048 queued spans x ~500 bytes (~1 MB) + active spans (~0.8 MB) ≈ **~10 MB ceiling**
-- The worker thread stack (~8 MB) is virtual memory; actual RSS depends on stack usage (typically much less)
-
-> **Measured outcome**: A perf-iac comparison (telemetry compiled-in + enabled vs compiled-out,
-> 9 nodes — validators and client-handlers — under sustained payment load) recorded **no measurable
-> RSS increase over the telemetry-off baseline** (~15 GiB mean / ~18–19 GiB peak on both sides),
-> with no OOM, no swap, and no leak across the run. The ~10 MB ceiling above is therefore a
-> provisioning safety margin (dominated by virtual thread-stack address space), not an expected
-> resident-memory increase. Steady-state cost shows up as throughput (~3–4% at head sampling 1.0),
-> not memory.
-
-### 3.5.4 Performance Data Sources
-
-The overhead estimates in Sections 3.3-3.5 are derived from the following sources:
-
-| Source                                           | What it covers                                        | URL                                                                                                                                        |
-| ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| OTel C++ SDK CI benchmarks (969 runs)            | Span creation, context activation, sampler overhead   | [Benchmark Dashboard](https://open-telemetry.github.io/opentelemetry-cpp/benchmarks/)                                                      |
-| `api/test/trace/span_benchmark.cc`               | API-level span creation (~22 ns no-op)                | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/api/test/trace/span_benchmark.cc)                                   |
-| `sdk/test/trace/sampler_benchmark.cc`            | SDK span creation with samplers (~1,000 ns AlwaysOn)  | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/test/trace/sampler_benchmark.cc)                                |
-| `sdk/include/.../span_data.h`                    | SpanData memory layout (~250 bytes base)              | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/trace/span_data.h)                    |
-| `sdk/src/trace/span.h`                           | Span wrapper memory layout (~88 bytes)                | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/src/trace/span.h)                                               |
-| `sdk/include/.../batch_span_processor_options.h` | Default queue size (2048), batch size (512)           | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/trace/batch_span_processor_options.h) |
-| `sdk/include/.../circular_buffer.h`              | CircularBuffer implementation (AtomicUniquePtr array) | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/common/circular_buffer.h)             |
-| OTLP proto definition                            | Serialized span size estimation                       | [Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto)                          |
-
----
-
-## 3.6 Network Overhead Analysis
-
-### 3.6.1 Export Bandwidth
-
-> **Bytes per span**: Estimates use ~500 bytes/span (conservative upper bound). OTLP protobuf analysis
-> shows a typical span with 3-5 string attributes serializes to ~200-300 bytes raw; with gzip
-> compression (~60-70% of raw) and batching (amortized headers), ~350 bytes/span is more realistic.
-> The table uses the conservative estimate for capacity planning.
-
-**Node → collector bandwidth is always the 100% row.** Head sampling is a
-`static constexpr` 1.0 (`Telemetry.h:234`) with no config key, so every node
-exports every span and the export bandwidth is not tunable from `xrpld.cfg`.
-
-| Sampling Rate         | Spans/sec | Bandwidth  | Where it applies                                                                                                                    |
-| --------------------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| 100%                  | ~500      | ~250 KB/s  | **The only reachable node→collector figure.** Plan capacity against this row                                                        |
-| 0.5%                  | ~2.5      | ~1.25 KB/s | Collector→backend only, and only with the Grafana Cloud overlay's `tail_sampling` (`otel-collector-config.grafanacloud.yaml:60-67`) |
-| 10% / 1% / error-only | —         | —          | **Not implemented.** No shipped config produces these ratios; treat them as illustrative of what a tail-sampling policy could do    |
-
-The rows below 100% therefore reduce _storage_ cost at the backend, never the
-node's egress. Note also that the shipped 0.5% policy is applied to the
-trace-storage branch only, so the spanmetrics-derived RED metrics still see
-100% of spans and stay exact.
-
-### 3.6.2 Trace Context Propagation
-
-| Message Type           | Context Size | Messages/sec | Overhead    |
-| ---------------------- | ------------ | ------------ | ----------- |
-| TMTransaction          | 25 bytes     | ~100         | ~2.5 KB/s   |
-| TMProposeSet           | 25 bytes     | ~10          | ~250 B/s    |
-| TMValidation           | 25 bytes     | ~50          | ~1.25 KB/s  |
-| **Total P2P overhead** |              |              | **~4 KB/s** |
-
----
-
-## 3.7 Optimization Strategies
-
-### 3.7.1 Sampling Strategies
-
-#### Head Sampling (node) — fixed, not a decision point
-
-There is no sampling decision on the node. `samplingRatio` is a
-`static constexpr double = 1.0` (`Telemetry.h:234`) and `TelemetryConfig.cpp:139`
-records why nothing is parsed: a per-node ratio would let two nodes make
-opposite keep/drop decisions for the same distributed trace, yielding partial
-traces. The ratio sampler is wrapped in a `ParentBasedSampler` so a span with a
-remote parent honours the upstream flag. The only node-local way to drop a span
-is the explicit, per-call-site `SpanGuard::discard()`, enforced downstream by
-`FilteringSpanProcessor`.
-
-#### Tail Sampling (collector) — aspirational shape
-
-The flowchart below is a **design sketch of a multi-policy tail sampler. It is
-not what ships.** The base collector config has no `tail_sampling` processor at
-all; the Grafana Cloud overlay has exactly one `probabilistic` policy at 0.5%
-with no error or latency carve-outs. Read it as a template for a policy you
-might write, not as a description of this repo — and note that adding
-error/latency policies would need `decision_wait` tuning, since a policy can
-only see spans that arrived within that window.
-
-```mermaid
-flowchart TD
-    trace["New Trace"]
-
-    trace --> errors{"Is Error?"}
-    errors -->|Yes| sample["SAMPLE"]
-    errors -->|No| consensus{"Is Consensus?"}
-
-    consensus -->|Yes| sample
-    consensus -->|No| slow{"Is Slow?"}
-
-    slow -->|Yes| sample
-    slow -->|No| prob{"Probabilistic keep?<br/>(shipped policy: 0.5%)"}
-
-    prob -->|Yes| sample
-    prob -->|No| drop["DROP"]
-
-    style sample fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style drop fill:#b71c1c,stroke:#7f1d1d,color:#fff
-    style trace fill:#0d47a1,stroke:#082f6a,color:#fff
-    style errors fill:#334155,stroke:#1e293b,color:#fff
-    style consensus fill:#334155,stroke:#1e293b,color:#fff
-    style slow fill:#334155,stroke:#1e293b,color:#fff
-    style prob fill:#334155,stroke:#1e293b,color:#fff
-```
-
-### 3.7.2 Batch Tuning Recommendations
-
-| Environment        | Batch Size | Batch Delay | Max Queue |
-| ------------------ | ---------- | ----------- | --------- |
-| Low-latency        | 128        | 1000ms      | 512       |
-| High-throughput    | 1024       | 10000ms     | 8192      |
-| Memory-constrained | 256        | 2000ms      | 512       |
-
-### 3.7.3 Conditional Instrumentation
-
-Instrumentation is gated on two levels. A compile-time feature flag reduces the trace macros to no-ops when telemetry is built out, so disabled builds carry zero cost. At runtime, per-component guards (e.g. `shouldTracePeer()`) skip span creation for components whose tracing is turned off, incurring no overhead beyond a single boolean check.
-
-> The compile-time gate is the macro `XRPL_ENABLE_TELEMETRY`, but that macro is
-> **not** the switch you flip. It is a compile definition added by
-> `CMakeLists.txt` (`add_compile_definitions(XRPL_ENABLE_TELEMETRY)`) when the CMake option `telemetry` is ON.
-> That option is declared ON today (`option(telemetry "Enable OpenTelemetry tracing" ON)`)
-> only so that CI compiles the instrumented build while the telemetry branches are
-> in review; **OFF is the intended default once merged**, flipped in a separate
-> change. Select the value explicitly instead of relying on the default:
-> `-Dtelemetry=ON|OFF` (CMake) or `-o telemetry=True|False` (Conan). See
-> [05 §5.4.2](./05-configuration-reference.md).
-
----
-
-## 3.8 Links to Detailed Documentation
-
-- **[Configuration Reference](./05-configuration-reference.md)**: Configuration options and collector setup
-- **[Implementation Phases](./06-implementation-phases.md)**: Detailed timeline and milestones
-
----
-
-## 3.9 Code Intrusiveness Assessment
-
-> **TxQ** = Transaction Queue
-
-This section provides a detailed assessment of how intrusive the OpenTelemetry integration is to the existing xrpld codebase.
-
-### 3.9.3 Risk Assessment by Component
-
-<div align="center">
-
-**Do First** ↖ ↗ **Plan Carefully**
-
-```mermaid
-quadrantChart
-    title Code Intrusiveness Risk Matrix
-    x-axis Low Risk --> High Risk
-    y-axis Low Value --> High Value
-
-    RPC Tracing: [0.2, 0.55]
-    Transaction Relay: [0.55, 0.85]
-    Consensus Tracing: [0.75, 0.92]
-    Peer Message Tracing: [0.85, 0.35]
-    JobQueue Context: [0.3, 0.42]
-    Ledger Acquisition: [0.48, 0.65]
-    PathFinding: [0.38, 0.72]
-    TxQ and Fees: [0.25, 0.62]
-    Validator Mgmt: [0.15, 0.35]
-```
-
-**Optional** ↙ ↘ **Avoid**
-
-</div>
-
-#### Risk Level Definitions
-
-| Risk Level | Definition                                                       | Mitigation                         |
-| ---------- | ---------------------------------------------------------------- | ---------------------------------- |
-| **Low**    | Additive changes only; no modification to existing logic         | Standard code review               |
-| **Medium** | Minor modifications to existing functions; clear boundaries      | Comprehensive unit tests           |
-| **High**   | Changes to core logic or data structures; potential side effects | Integration tests + staged rollout |
-
-### 3.9.4 Architectural Impact Assessment
-
-| Aspect               | Impact  | Justification                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Data Flow**        | Minimal | Read-only instrumentation; no modification to consensus or transaction data flow                                                                                                                                                                                                                                                                                                                                                                     |
-| **Threading Model**  | Minimal | Context propagation uses thread-local storage (standard OTel pattern)                                                                                                                                                                                                                                                                                                                                                                                |
-| **Memory Model**     | Low     | Bounded queues prevent unbounded growth; RAII ensures cleanup                                                                                                                                                                                                                                                                                                                                                                                        |
-| **Network Protocol** | Low     | Optional fields in protobuf (high field numbers); backward compatible                                                                                                                                                                                                                                                                                                                                                                                |
-| **Configuration**    | None    | New config section; existing configs unaffected                                                                                                                                                                                                                                                                                                                                                                                                      |
-| **Build System**     | Low     | A single CMake option (`telemetry`) selects the whole feature in or out, and builds work either way (`-Dtelemetry=ON` / `-Dtelemetry=OFF`). It is declared ON today only so CI compiles the instrumented paths; **OFF is the intended default once merged**, so the shipped build is opt-in                                                                                                                                                          |
-| **Dependencies**     | Medium  | `opentelemetry-cpp/1.28.0` is a **conditional** requirement, never a hard one: `conanfile.py:152-153` adds it only `if self.options.telemetry`, and `:238-239` adds the matching `libxrpl` component requirement the same way. The option's declared default is `True` today (`conanfile.py:59`), so a default `conan install` does resolve it; with `-o telemetry=False` it never enters the graph and the null implementation supplies the factory |
-
-### 3.9.5 Backward Compatibility
-
-| Compatibility   | Status  | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Config File** | ✅ Full | New `[telemetry]` section is optional                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| **Protocol**    | ✅ Full | Optional protobuf fields with high field numbers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| **Build**       | ✅ Full | `-Dtelemetry=OFF` (or `-o telemetry=False`) produces a binary with all tracing compiled out, whatever the option's declared default happens to be. **Not** `-DXRPL_ENABLE_TELEMETRY=OFF`, which does not disable anything — it is not a CMake option, only a compile definition that `CMakeLists.txt:152` adds inside the `if(telemetry)` block. CMake does flag it (`Manually-specified variables were not used by the project`) at the end of configuration, so it is not literally silent — but the warning is easy to scroll past and the resulting binary still has telemetry compiled in. See [05 §5.4.2](./05-configuration-reference.md) |
-| **Runtime**     | ✅ Full | `enabled=0` produces zero overhead                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| **API**         | ✅ Full | No changes to public RPC or P2P APIs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-
-### 3.9.6 Rollback Strategy
-
-If issues are discovered after deployment:
-
-1. **Immediate**: Set `enabled=0` in `[telemetry]` and restart (zero code change).
-   Also set `[insight] server=` to something other than `otel` if metrics must
-   stop too — `enabled=0` governs tracing, and the metrics pipeline is selected
-   separately ([02 §2.6.4](./02-design-decisions.md)).
-2. **Quick**: Rebuild with `-Dtelemetry=OFF` (CMake) or `-o telemetry=False`
-   (Conan). Pass the flag explicitly — an omitted flag resolves to the option's
-   declared default, which is ON today and OFF once the feature is merged; a
-   build that already has telemetry off needs no rebuild at all.
-   **Do not use `-DXRPL_ENABLE_TELEMETRY=OFF`** — it is not a CMake option, so
-   it is ignored (CMake reports it under `Manually-specified variables were not
-used by the project`) and the rebuilt binary still has telemetry compiled in.
-   This step also drops the `opentelemetry-cpp` dependency, so expect a full
-   rebuild rather than an incremental one.
-3. **Complete**: Revert telemetry commits (clean separation makes this easy)
-
-### 3.9.7 Code Change Examples
-
-**Minimal RPC Instrumentation (Low Intrusiveness):** Instrumenting an RPC handler adds roughly 3-4 lines: one macro to start the span and one or two `setAttribute` calls (command name, status). The span ends automatically via RAII, so the existing control flow — process the request, send the result — is untouched.
-
-**Consensus Instrumentation (Medium Intrusiveness):** Consensus is slightly more intrusive because child spans in later phase transitions need the round's context. Beyond the span-start and attribute macros, this requires **four** new member variables on the adaptor rather than the single `currentRoundContext_` this section originally sketched (`RCLConsensus.h:103,113,123,143`):
-
-- `std::optional<telemetry::SpanGuard> roundSpan_` (`:103`) — the round span
-  itself. It is **created and ended in one place**, `startRoundTracing()`: the
-  previous round's guard is released at `RCLConsensus.cpp:1288-1289`
-  (`if (roundSpan_) roundSpan_.reset();`) and the new one is emplaced a few
-  lines later — at `:1306` or `:1310` on the `"attribute"` strategy, at `:1319`
-  on the default `"deterministic"` one. `preStartRound()` does not create it; it
-  calls `startRoundTracing()` at `:1229`. There is no `reset()` method — the
-  span simply lives until the next round begins. A `SpanGuard` owns no
-  thread-local scope, so emplacing and resetting on different job workers is
-  safe.
-- `telemetry::SpanContext roundSpanContext_` (`:113`) — a lightweight value-type
-  snapshot, captured at the end of `startRoundTracing()` (`:1350`). Child spans
-  link through this, not through an ambient parent, so code running on another
-  worker (e.g. `createValidationSpan()` on `jtACCEPT`) never touches
-  `roundSpan_` cross-thread.
-- `telemetry::SpanContext prevRoundSpanContext_` (`:123`) — the prior round's
-  context, saved at `:1282` **before** the new span overwrites
-  `roundSpanContext_`, so the new round span can carry a follows-from link and
-  consecutive rounds stay navigable.
-- `telemetry::SpanContext acceptSpanContext_` (`:143`) — the current round's
-  accept-span context, set at `:544` and cleared at `:1286` on each new round.
-  `createValidationSpan()` prefers it as the parent and falls back to
-  `roundSpanContext_` (`:1363-1373`), so a stale value must not survive into the
-  next round.
-
-The split is the point: the guard is owned by one thread, the contexts are
-copied freely. The existing round logic itself remains unchanged.
-
----
-
-_Previous: [Design Decisions](./02-design-decisions.md)_ | _Next: [Configuration Reference](./05-configuration-reference.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/05-configuration-reference.md

@@ -1,665 +0,0 @@
-# Configuration Reference
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Phases](./06-implementation-phases.md)
-
----
-
-## 5.1 xrpld Configuration
-
-> **OTLP** = OpenTelemetry Protocol | **TxQ** = Transaction Queue
-
-### 5.1.1 Configuration File Section
-
-The authoritative `[telemetry]` example lives in `cfg/xrpld-example.cfg`. Telemetry is disabled by default (`enabled=0`); enabling it turns on distributed tracing for transaction flow, consensus, and RPC calls, with traces exported to an OpenTelemetry Collector over OTLP. Head sampling is intentionally fixed at 1.0 (sample everything) and is not configurable — per-node head-sampling would produce broken/partial distributed traces, so volume reduction is delegated to the collector's tail sampling (see Section 7.4.2). Transaction trace IDs are always deterministic (`trace_id = txHash[0:16]`); there is no strategy switch for the transaction path. The full option reference follows.
-
-> **`service_instance_id` defaults to the node public key for every producer.**
-> `Main.cpp` resolves the identity before `ApplicationImp` is constructed and it
-> is never empty, so all three producers below stamp the node key when the config
-> key is unset. They still build their resources at three different times, which
-> is what decides how each behaves if the identity ever changes mid-run:
->
-> | Producer                                    | Resource built by                            | Unset `service_instance_id` yields |
-> | ------------------------------------------- | -------------------------------------------- | ---------------------------------- |
-> | Traces (and therefore all `span_*` metrics) | `Telemetry::start()`, during `setup()`       | Base58 node public key             |
-> | Native `XRPL_METRIC_*` (`MetricsRegistry`)  | `MetricsRegistry::initExporterAndProvider()` | Base58 node public key             |
-> | `beast::insight` (`[insight] server=otel`)  | `TelemetryImpl` **constructor**              | Base58 node public key             |
->
-> - **Traces**: the tracer resource is built in `Telemetry::start()`, which runs
->   inside `setup()` after `getNodeIdentity()` has persisted the identity, so it
->   is the one resource that can still be corrected by
->   `setServiceInstanceId()`. The `spanmetrics` connector derives
->   `span_calls_total` / `span_duration_milliseconds_*` from those spans, so span
->   metrics inherit the same id.
-> - **Native `XRPL_METRIC_*` metrics** build their **own** MeterProvider resource
->   in `MetricsRegistry::initExporterAndProvider()`, called from the registry's
->   constructor. `makeMetricsRegistryOptions()` in `Application.cpp` supplies the
->   id: the config key when set, else the resolved node key.
-> - **`beast::insight` metrics** use the **global** MeterProvider, whose resource
->   is built in the `TelemetryImpl` **constructor**, because insight instruments
->   are created eagerly in subsystem constructors and would otherwise bind to the
->   noop provider forever. It receives the same resolved key. Note it writes the
->   attribute **unconditionally**, where `MetricsRegistry` guards the write with
->   `if (!options.serviceInstanceId.empty())`, so a deliberately blank
->   `service_instance_id` yields `service.instance.id=""` there and an absent
->   attribute here.
->
-> The one case where the three can disagree: a node whose wallet already holds an
-> identity different from the resolved one (another process wrote it between
-> construction and `setup()`). `setServiceInstanceId()` then corrects the tracer,
-> and both metric resources, already frozen, need a restart to follow. Every
-> shipped Grafana dashboard filters on `service_instance_id=~"$node"`, so that run
-> shows its metrics under the resolved key and its traces under the stored one.
-
-### 5.1.2 Configuration Options Summary
-
-| Option                     | Type   | Default                            | Description                                                                                                                                                                                      |
-| -------------------------- | ------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `enabled`                  | 0 or 1 | `0`                                | Enable/disable telemetry                                                                                                                                                                         |
-| `traces_endpoint`          | string | `http://localhost:4318/v1/traces`  | OTLP/HTTP collector endpoint for **traces**                                                                                                                                                      |
-| `metrics_endpoint`         | string | `http://localhost:4318/v1/metrics` | OTLP/HTTP collector endpoint for the native metrics pipeline (`MetricsRegistry`). Read by `makeMetricsRegistryOptions()` in `Application.cpp`                                                    |
-| `use_tls`                  | 0 or 1 | `0`                                | Enable TLS for exporter connection                                                                                                                                                               |
-| `tls_ca_cert`              | string | `""`                               | Path to CA certificate file                                                                                                                                                                      |
-| `tls_client_cert`          | string | `""`                               | Client cert (PEM) for mTLS; empty = one-way; if `enabled=1`, needs key + `use_tls=1` or startup fails                                                                                            |
-| `tls_client_key`           | string | `""`                               | Private key (PEM) for `tls_client_cert`; if set with `enabled=1`, needs the cert + `use_tls=1` or fails                                                                                          |
-| `batch_size`               | uint   | `512`                              | Spans per export batch                                                                                                                                                                           |
-| `batch_delay_ms`           | uint   | `5000`                             | Max delay before sending batch (ms)                                                                                                                                                              |
-| `max_queue_size`           | uint   | `2048`                             | Maximum queued spans                                                                                                                                                                             |
-| `trace_transactions`       | 0 or 1 | `1`                                | Enable transaction tracing                                                                                                                                                                       |
-| `trace_consensus`          | 0 or 1 | `1`                                | Enable consensus tracing                                                                                                                                                                         |
-| `trace_rpc`                | 0 or 1 | `1`                                | Enable RPC tracing                                                                                                                                                                               |
-| `trace_peer`               | 0 or 1 | `1`                                | Enable peer message tracing (high volume)                                                                                                                                                        |
-| `trace_ledger`             | 0 or 1 | `1`                                | Enable ledger tracing                                                                                                                                                                            |
-| `consensus_trace_strategy` | string | `"deterministic"`                  | Consensus trace ID strategy: `"deterministic"` (trace_id = prevLedgerHash[0:16]) or `"random"` (experimental, not used). Rejected at startup if it is neither spelling                           |
-| `service_name`             | string | `"xrpld"`                          | Service name (`service.name`) for traces and metrics                                                                                                                                             |
-| `service_instance_id`      | string | node public key (base58)           | Instance identifier (`service.instance.id`). Traces, span metrics and native `XRPL_METRIC_*` metrics all fall back to the node key; **`beast::insight` metrics do not** — see the note in §5.1.1 |
-
-**Not a config key — deterministic transaction trace IDs are unconditional.**
-Earlier drafts of this document listed a `tx_trace_strategy` option
-(`"deterministic"` \| `"attribute"`). No such key exists: `TelemetryConfig.cpp`
-parses no transaction-strategy key, and the transaction trace ID is always
-derived from the transaction hash. Only the **consensus** path has a
-switchable strategy.
-
-**Planned (not yet implemented)**: the following options appear in the design
-documents but are not parsed by `TelemetryConfig.cpp`. They will be added as
-the corresponding subsystems are instrumented:
-
-| Option            | Planned Phase | Purpose                                  |
-| ----------------- | ------------- | ---------------------------------------- |
-| `exporter`        | Future        | Select between OTLP/HTTP and OTLP/gRPC   |
-| `trace_pathfind`  | Phase 2       | Path computation tracing toggle          |
-| `trace_txq`       | Phase 3       | Transaction queue tracing toggle         |
-| `trace_validator` | Future        | Validator list / manifest update tracing |
-| `trace_amendment` | Future        | Amendment voting tracing                 |
-
-> **`exporter` is not read, so do not set it.** No shipped sample config
-> carries it. OTLP/HTTP is the only transport that exists (§2.2.1), so
-> `traces_endpoint` and `metrics_endpoint` are the only transport knobs until
-> the §2.2.2 gRPC work lands.
-
----
-
-## 5.2 Configuration Parser
-
-> **TxQ** = Transaction Queue
-
-The parser `makeTelemetrySetup()` in `src/libxrpl/telemetry/TelemetryConfig.cpp` reads the `[telemetry]` `Section` and populates a `Telemetry::Setup` struct, applying the defaults listed in Section 5.1.2 via `section.valueOr(...)`. It takes `serviceInstanceId` from the `nodePublicKey` argument when the key is absent, applies one unconditional `traces_endpoint` default (`dflt::tracesEndpoint`) — the parser has no notion of exporter type — and leaves the sampling ratio at its fixed 1.0 default (a `static constexpr` member, so there is nothing to parse). It also rejects two contradictory mTLS configurations outright (`tls_client_cert` without `tls_client_key`, and either without `use_tls=1`) rather than failing open at handshake time.
-
-`metrics_endpoint` reaches `MetricsRegistry` by a second route: `makeMetricsRegistryOptions()` in `Application.cpp` reads it from the same `Section` and passes it to the registry's constructor, because `Telemetry` does not expose the `Setup` it parsed. Both metric exporters resolve to that one key:
-
-| Metric source                              | Exporter built by                            | URL comes from                                                       |
-| ------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------- |
-| `beast::insight` (`[insight] server=otel`) | `Telemetry::initMetrics()` (global provider) | `metrics_endpoint`, used verbatim                                    |
-| Native `XRPL_METRIC_*` (`MetricsRegistry`) | `MetricsRegistry::initExporterAndProvider()` | `metrics_endpoint`, defaulting to `http://localhost:4318/v1/metrics` |
-
-Setting `traces_endpoint` therefore moves traces only; both metric pipelines follow `metrics_endpoint`.
-
----
-
-## 5.3 Application Integration
-
-### 5.3.1 ApplicationImp Changes
-
-> **Identity before construction**: telemetry stamps the node public key into
-> resources that are immutable once built, and it builds them during
-> `ApplicationImp`'s member initializer list. So `Main.cpp` calls
-> `resolveNodeIdentity()` first, from the config and command line alone, and
-> passes the keypair to `makeApplication()`. It never comes back empty: a
-> configured `[node_seed]` decides it, else the wallet database supplies it if
-> one already exists, else it is minted. Every producer therefore carries the
-> node key from the start — the tracer, the **global** MeterProvider the
-> `beast::insight` metrics use, and `MetricsRegistry`'s separate one.
-> `ApplicationImp::setup()` then calls `getNodeIdentity()`, which stores that
-> keypair when the wallet holds none and otherwise adopts what the wallet holds.
-> Only in that second case can the two differ, and then
-> `setServiceInstanceId()` corrects the tracer alone: both metric resources are
-> frozen once their providers are built, so those metrics need a restart to
-> report the stored key.
-
-`ApplicationImp` (in `src/xrpld/app/main/Application.cpp`) owns a `std::pair<PublicKey, SecretKey> nodeIdentity_`, declared before `std::unique_ptr<telemetry::Telemetry> telemetry_` and `std::unique_ptr<telemetry::MetricsRegistry> metricsRegistry_` so both resources can be built from it. All three are built in the member initializer list, before every subsystem. `setup()` persists the identity, starts tracing with `startTelemetry()` before the first consensus round, and arms the registry's observable gauges with `startTelemetryGauges()` once `overlay_` exists. `run()` stops both observers before any service, then stops telemetry last; `~ApplicationImp` repeats those stops for the paths that never reach `run()`. `getTelemetry()` and `getMetricsRegistry()` return the owned instances.
-
-### 5.3.2 ServiceRegistry Interface Addition
-
-`include/xrpl/core/ServiceRegistry.h` gains a pure-virtual `telemetry::Telemetry& getTelemetry()` (with a forward declaration of `telemetry::Telemetry`), giving every component a uniform accessor for the tracing subsystem.
-
-> **Note:** `Application` extends `ServiceRegistry`, so `getTelemetry()` is
-> available on both. Components that hold a `ServiceRegistry&` (e.g.
-> `NetworkOPsImp`) call `registry_.get().getTelemetry()`. Components that
-> still hold an `Application&` (e.g. `ServerHandler`, `PeerImp`,
-> `RCLConsensus::Adaptor`) call `app_.getTelemetry()` directly.
-
----
-
-## 5.4 CMake Integration
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 5.4.1 Locating the OpenTelemetry SDK
-
-> **Superseded design.** Earlier drafts described a hand-written
-> `cmake/FindOpenTelemetry.cmake` module that aliased `OpenTelemetry::api`,
-> `OpenTelemetry::sdk` and `OpenTelemetry::otlp_grpc_exporter` with a
-> `pkg-config` fallback. That module was never written — it exists in no
-> commit — and the aliasing approach it described does not work with the
-> package the build actually consumes.
-
-The SDK is located by the Conan-generated CMake config package, nothing else:
-
-- `CMakeLists.txt` — `find_package(opentelemetry-cpp CONFIG REQUIRED)`,
-  guarded by the `telemetry` option (§5.4.2). The dependency itself is
-  declared in `conanfile.py:153` (`opentelemetry-cpp/1.28.0`), also guarded —
-  `requirements()` adds it only `if self.options.telemetry` (`:152`), so with
-  the option off the package never enters the dependency graph.
-- Linking goes through the **umbrella** target
-  `opentelemetry-cpp::opentelemetry-cpp`, never the per-component targets.
-  `cmake/XrplCore.cmake:221-225` and `:83-91` record why: the Conan package
-  under-declares its inter-component dependencies, so naming `::api` / `::sdk`
-  individually produces the wrong static-link order and fails at executable
-  link time. The umbrella target supplies both the trace and metrics
-  components with the correct ordering.
-
-### 5.4.2 CMakeLists.txt Changes
-
-The build flag is `telemetry`:
-
-```
-option(telemetry "Enable OpenTelemetry tracing" ON)   # top-level CMakeLists.txt
-```
-
-The declared value is ON **temporarily**, so that CI compiles the telemetry code
-paths while the feature branches are in review. **OFF is the intended default
-once merged**, and the flip is a separate change. Set the value explicitly
-rather than relying on the default:
-
-| To …                      | Use (CMake)       | Use (Conan)          |
-| ------------------------- | ----------------- | -------------------- |
-| Build telemetry in        | `-Dtelemetry=ON`  | `-o telemetry=True`  |
-| Build it out (all no-ops) | `-Dtelemetry=OFF` | `-o telemetry=False` |
-
-When the option is ON, the guarded block below it runs
-`find_package(opentelemetry-cpp CONFIG REQUIRED)` and adds the
-**compile definition** `XRPL_ENABLE_TELEMETRY`.
-
-> **`XRPL_ENABLE_TELEMETRY` is not a CMake option.** It is only ever _added_
-> as a compile definition by `add_compile_definitions(XRPL_ENABLE_TELEMETRY)` in that same block. Passing
-> `-DXRPL_ENABLE_TELEMETRY=OFF` on the CMake command line disables **nothing** —
-> it defines an unused cache variable and telemetry stays compiled in. CMake does
-> report it, at the end of configuration under `Manually-specified variables were
-not used by the project`, so it is not literally silent — but that line is easy
-> to scroll past. Any procedure that relies on it (including the rollback path in
-> [§3.9.6](./03-implementation-strategy.md)) must use `-Dtelemetry=OFF`.
-
-The target is `xrpl.libxrpl.telemetry`, created by `add_module(xrpl telemetry)`
-at `cmake/XrplCore.cmake:231` from `include/xrpl/telemetry/` +
-`src/libxrpl/telemetry/`. There is no `xrpl_telemetry` target.
-
-Selection between the real and the no-op implementation is an **in-source
-`#ifdef`, not a source swap**: `NullTelemetry.cpp` is compiled into the target
-unconditionally (see its header comment, `NullTelemetry.cpp:1-12`). It provides
-the `makeTelemetry()` factory when `XRPL_ENABLE_TELEMETRY` is undefined; when
-the macro is defined, `Telemetry.cpp` provides the factory instead and
-`NullTelemetry`'s virtuals only serve as noop tracer/span fallbacks. Call sites
-compile unchanged either way.
-
----
-
-## 5.5 OpenTelemetry Collector Configuration
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring
-
-The authoritative collector config lives in the repo at `docker/telemetry/otel-collector-config.yaml` (with Tempo backend config in `docker/telemetry/tempo.yaml`). The sections below summarize the development and production shapes of that pipeline.
-
-### 5.5.1 Development / Base Configuration
-
-`docker/telemetry/otel-collector-config.yaml` is the base config used by the
-local stack and by CI. It carries **three** pipelines, not one:
-
-| Pipeline  | Receivers              | Processors                                                     | Exporters                                  |
-| --------- | ---------------------- | -------------------------------------------------------------- | ------------------------------------------ |
-| `traces`  | `otlp`                 | `resource/tier`, `resource/stripsdk`, `batch`                  | `debug`, `otlp_grpc/tempo`, `span_metrics` |
-| `metrics` | `otlp`, `span_metrics` | `resource/tier`, `resource/stripsdk`, `batch`                  | `prometheus`                               |
-| `logs`    | `file_log`             | `resource/logs`, `resource/tier`, `resource/stripsdk`, `batch` | `otlp_http/loki`                           |
-
-Component detail:
-
-- **Receivers.** `otlp` on gRPC `0.0.0.0:4317` and HTTP `0.0.0.0:4318` (both
-  traces and native metrics arrive on 4318). `file_log` tails
-  `/var/log/xrpld/*/debug.log` and runs a `regex_parser` that lifts
-  `timestamp`, `partition`, `severity` and the optional `trace_id`/`span_id`
-  emitted by the journal sink (§5.8.5).
-- **Processors.** `batch` (1s timeout, `send_batch_size: 100`);
-  `resource/tier` (`action: upsert` on `deployment.environment`, `action: insert` on
-  `xrpl.network.type` only when absent); `resource/stripsdk` (drops the
-  `telemetry.sdk.*` attributes); `resource/logs` (`action: upsert` on
-  `service.name` and `job` — only the former becomes a Loki stream label, see
-  the known issue in §5.8.5). No processor hashes or drops span attributes:
-  account addresses are public identifiers and are stored as emitted.
-- **Connector.** `span_metrics` with `namespace: "span"`
-  (`otel-collector-config.yaml:114`) — this is why the derived RED metrics are
-  `span_calls_total` / `span_duration_milliseconds_*`. The connector's own
-  default namespace is **empty**, so without this setting the names would be
-  the bare `calls_total` / `duration_milliseconds_*`. The
-  `traces_span_metrics_*` family is **not** the connector's default and is not
-  produced here at all — it comes from a different producer, Tempo's
-  `metrics_generator` `span-metrics` processor (`tempo.yaml:75`), whose
-  `remote_write` is commented out in this repo (see §5.8.6). Histogram
-  `unit: ms`
-  with sub-millisecond buckets from `0.01ms`, plus explicit `2s`–`30s`
-  boundaries for consensus and `ledger.acquire`. ~25 low-cardinality
-  dimensions are promoted to labels (`command`, `rpc_status`, `tx_type`,
-  `ter_result`, `stage`, `consensus_mode`, `outcome`, …).
-- **Exporters.** `debug` (console, `verbosity: detailed`), `otlp_grpc/tempo`
-  (`tempo:4317`, `tls.insecure: true`), `otlp_http/loki`
-  (`http://loki:3100/otlp` — Loki 3.x native OTLP; the old `loki` exporter was
-  removed in collector-contrib v0.147.0), and `prometheus` on
-  `0.0.0.0:8889` with `resource_to_telemetry_conversion.enabled: true` so the
-  tier and instance resource attributes become Prometheus labels.
-- **Extensions.** `health_check` on `0.0.0.0:13133` only. There is **no**
-  `zpages` extension.
-
-Deliberately absent from the base config — do not document them as present:
-no `memory_limiter`, no `tail_sampling`, no Elastic APM exporter, and no
-attribute hashing or redaction rule (account addresses are emitted raw).
-
-### 5.5.2 Production Configuration
-
-There is no separate "production" collector config in this repo. The one
-overlay that exists is `docker/telemetry/otel-collector-config.grafanacloud.yaml`.
-It is **not** the base config plus one processor — it restructures the service
-graph. The full delta:
-
-| Added by the overlay     | Where  | Purpose                                                                   |
-| ------------------------ | ------ | ------------------------------------------------------------------------- |
-| `basicauth/grafanacloud` | `:29`  | Extension; instance id / API token from the container environment         |
-| `tail_sampling`          | `:60`  | One `probabilistic` policy at **0.5%**, `decision_wait: 10s`              |
-| `transform/cloudlabels`  | `:119` | Copies three resource attrs onto datapoint labels for Cloud (OTLP) ingest |
-| `otlp_http/grafanacloud` | `:236` | Single OTLP/HTTP exporter fanning all three signals to Grafana Cloud      |
-| `metrics_flush_interval` | `:136` | `spanmetrics` flushes every 15s instead of the 60s default                |
-
-| Removed by the overlay | Consequence                                                       |
-| ---------------------- | ----------------------------------------------------------------- |
-| `debug`                | No console span dump; collector logs alone when diagnosing ingest |
-
-Pipelines go from **three** (`traces`, `metrics`, `logs`) to **five**
-(`:253-280`): `traces/metrics`, `traces/store`, `metrics/local`,
-`metrics/cloud`, `logs`. `tail_sampling` is applied in **`traces/store`**
-(`:259-261`) — the branch feeding Tempo and Grafana Cloud — not in a pipeline
-named `traces`, which does not exist in the overlay. The `traces/metrics`
-branch feeds `spanmetrics` unsampled, so the derived RED metrics stay exact
-while stored traces are ~1/200 of ingested ones.
-
-Hardening a collector for a real deployment (TLS/mTLS on the receiver,
-NetworkPolicy, peer trace-context validation) is covered in
-[Securing the OTel Pipeline](./secure-OTel.md) — not by any config file in
-`docker/telemetry/`.
-
----
-
-## 5.6 Docker Compose Development Environment
-
-> **OTLP** = OpenTelemetry Protocol
-
-The authoritative development stack lives in the repo at `docker/telemetry/docker-compose.yml`. It brings up **six** services on a shared `xrpld-telemetry` bridge network. All images are pinned to exact tags.
-
-| Service          | Image                                          | Published ports        | Role                                                              |
-| ---------------- | ---------------------------------------------- | ---------------------- | ----------------------------------------------------------------- |
-| `otel-collector` | `otel/opentelemetry-collector-contrib:0.158.0` | `4317`, `4318`, `8889` | OTLP ingest, spanmetrics, file_log tail, Prometheus scrape target |
-| `tempo`          | `grafana/tempo:2.9.4`                          | `3200`                 | Trace storage and TraceQL                                         |
-| `loki`           | `grafana/loki:3.7.6`                           | `3100`                 | Log storage for log↔trace correlation                             |
-| `prometheus`     | `prom/prometheus:v3.13.2`                      | `9090`                 | Scrapes the collector's `:8889`                                   |
-| `grafana`        | `grafana/grafana:13.1.2`                       | `3000`                 | Dashboards + provisioned datasources/alerts, anonymous admin      |
-| `renderer`       | `grafana/grafana-image-renderer:v5.12.0`       | none                   | Panel→PNG rendering for image export and alert screenshots        |
-
-Two corrections to earlier drafts:
-
-- **`prometheus` is not optional.** `grafana` lists it in `depends_on` (along
-  with `tempo`, `loki` and `renderer`), and 7 of the 15 dashboards query
-  `span_calls_total` from it. Removing it blanks most panels.
-- **Port `13133` is not published.** The collector's `health_check` extension
-  listens on `13133` inside the container, but the base compose file publishes
-  only `4317`, `4318` and `8889`. Health checks from the host must either add a
-  port mapping or run `docker compose exec`.
-
-The collector also bind-mounts the xrpld log root read-only
-(`${XRPLD_LOG_DIR:-./data/logs}` → `/var/log/xrpld`) for the `file_log`
-receiver, and the `grafana` service reads Slack/email alert secrets from an
-optional gitignored `.env.alerting`.
-
----
-
-## 5.7 Configuration Architecture
-
-> **OTLP** = OpenTelemetry Protocol
-
-```mermaid
-flowchart TB
-    subgraph config["Configuration Sources"]
-        cfgFile["xrpld.cfg<br/>[telemetry] section"]
-        cmake["CMake option: telemetry<br/>ON today for CI, OFF once merged<br/>when ON, defines XRPL_ENABLE_TELEMETRY"]
-    end
-
-    subgraph init["Initialization"]
-        parse["makeTelemetrySetup()"]
-        factory["makeTelemetry()"]
-    end
-
-    subgraph runtime["Runtime Components"]
-        tracer["TracerProvider"]
-        exporter["OTLP Exporter"]
-        processor["BatchProcessor"]
-    end
-
-    subgraph collector["Collector Pipeline"]
-        recv["Receivers"]
-        proc["Processors"]
-        exp["Exporters"]
-    end
-
-    cfgFile --> parse
-    cmake -->|"compile flag"| parse
-    parse --> factory
-    factory --> tracer
-    tracer --> processor
-    processor --> exporter
-    exporter -->|"OTLP"| recv
-    recv --> proc
-    proc --> exp
-
-    style config fill:#e3f2fd,stroke:#1976d2
-    style runtime fill:#e8f5e9,stroke:#388e3c
-    style collector fill:#fff3e0,stroke:#ff9800
-```
-
-**Reading the diagram:**
-
-- **Configuration Sources**: `xrpld.cfg` provides runtime settings (endpoint, per-component trace toggles) while the CMake `telemetry` option controls whether telemetry is compiled in at all. That option is declared ON today only so CI compiles the instrumented paths; OFF is the intended default once merged, so treat the build gate as something to pass explicitly, and the runtime gate is opt-in either way (`enabled=0` by default). Head sampling is fixed at 1.0 and is not a config option; volume reduction happens via tail sampling in the collector.
-- **Initialization**: `makeTelemetrySetup()` parses config values, then `makeTelemetry()` constructs the provider, processor, and exporter objects.
-- **Runtime Components**: The `TracerProvider` creates spans, the `BatchProcessor` buffers them, and the `OTLP Exporter` serializes and sends them over the wire.
-- **OTLP arrow to Collector**: Trace data leaves the xrpld process via OTLP/HTTP and enters the external Collector pipeline. (OTLP/gRPC is future work — see design decisions §2.2.2.)
-- **Collector Pipeline**: `Receivers` ingest OTLP data, `Processors` apply sampling/filtering/enrichment, and `Exporters` forward traces to storage backends (Tempo, etc.).
-
----
-
-## 5.8 Grafana Integration
-
-> **APM** = Application Performance Monitoring
-
-Step-by-step instructions for integrating xrpld traces with Grafana.
-
-### 5.8.1 Data Source Configuration
-
-Three datasources are provisioned from `docker/telemetry/grafana/provisioning/datasources/`. There is **no** Elastic APM datasource — `elastic-apm.yaml` was described in an earlier draft but never existed. Elastic remains a _possible_ backend (§7.2); nothing in this repo provisions it.
-
-| File              | Type         | URL                      | uid          | Notes                                                                                                                |
-| ----------------- | ------------ | ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `tempo.yaml`      | `tempo`      | `http://tempo:3200`      | `tempo`      | `nodeGraph`, `serviceMap`/`tracesToMetrics` → `prometheus`, `tracesToLogs` → `loki`, plus ~30 Explore search filters |
-| `prometheus.yaml` | `prometheus` | `http://prometheus:9090` | `prometheus` | Backs every span-metric and native-metric panel                                                                      |
-| `loki.yaml`       | `loki`       | `http://loki:3100`       | `loki`       | Backs `log-derived-insights`; derived fields jump back to Tempo                                                      |
-
-The Tempo `tracesToLogs` block is configured as `filterByTraceID: true`,
-`filterBySpanID: false`, **`tags: []`**. The empty tag list is deliberate: the
-correlation is by trace ID alone, so no span attribute needs to exist on both
-sides. Earlier drafts claimed `trace_id` + `tx_hash` tags — that is not what
-ships, and adding a tag Tempo cannot resolve blanks the link.
-
-The search-filter list is the practical index of queryable span attributes:
-resource scope (`service.name`, `service.instance.id`, `service.version`,
-`xrpl.network.id`, `xrpl.network.type`), intrinsics (`name`, `status`,
-`duration`), and span scope (`command`, `rpc_status`, `rpc_role`, `tx_hash`,
-`tx_type`, `tx_status`, `local`, `path`, `peer_version`,
-`consensus_*`, `ledger_seq`, `ledger_hash`, `close_time_correct`,
-`close_resolution_ms`, `proposers`, `mode_old`, `mode_new`, `txq_status`,
-`ter_code`).
-
-### 5.8.2 Dashboard Provisioning
-
-`grafana/provisioning/dashboards/dashboards.yaml` declares a single `file`
-provider named `xrpld-telemetry`, `orgId: 1`, targeting Grafana folder `xrpld`
-from path `/var/lib/grafana/dashboards` (no `/rippled` suffix), with
-`disableDeletion: false`, `editable: true`, `foldersFromFilesStructure: false`.
-It sets **no** poll interval — Grafana's `updateIntervalSeconds` default
-applies; the "every 30s" figure in earlier drafts was invented.
-
-`docker-compose.yml` mounts `./grafana/dashboards` read-only at that path, so
-the 15 JSON files in `docker/telemetry/grafana/dashboards/` are what gets
-provisioned.
-
-### 5.8.3 Shipped Dashboards
-
-The dashboards are Prometheus-first, not TraceQL-first, and their uids are
-bare (no `xrpld-` prefix). The full inventory and per-panel query reference is
-[09-data-collection-reference.md](./09-data-collection-reference.md); the uids
-are:
-
-`consensus-health`, `fee-market`, `job-queue`, `ledger-data-sync`,
-`ledger-operations`, `log-derived-insights`, `network-traffic`, `node-health`,
-`overlay-traffic-detail`, `peer-network`, `peer-quality`, `rpc-pathfinding`,
-`rpc-performance`, `transaction-overview`, `validator-health`.
-
-> **Panel-count convention used in these docs**: counts are of **data panels
-> only** — `type: "row"` collapsible headers are excluded, because a row is a
-> layout element with no query. A board's raw `panels` array is therefore longer
-> than its stated count (e.g. `rpc-performance` has 19 array entries: 2 rows +
-> 17 data panels).
-
-Two examples described in earlier drafts do not exist and should not be looked
-for: `xrpld-rpc-performance` (the real board is `rpc-performance`, **17** data
-panels in 2 rows, mostly Prometheus span metrics) and `xrpld-tx-tracing` (the
-transaction board is `transaction-overview`, **18** data panels in 3 rows; its
-error panel filters `span_calls_total{span_name="tx.process",
-ter_result!~"tesSUCCESS|"}`, since no `tx.validate` span was ever built — see
-[02 §2.3.2](./02-design-decisions.md)).
-
-> **Why `!~"tesSUCCESS|"` and not `!="tesSUCCESS"`.** An absent Prometheus label
-> compares equal to the empty string, and `tx.process` can end **without** a
-> `ter_result` attribute: `processTransaction()` returns early when
-> `preProcessTransaction()` rejects the transaction
-> (`NetworkOPs.cpp:1437-1438`) and `doTransactionAsync()` returns early when the
-> transaction is already applying (`:1461-1462`); the only setter runs later, at
-> `:1674`. Those series carry `ter_result=""`, which `!="tesSUCCESS"` counts as
-> an error. The regex form excludes the empty value explicitly (the trailing
-> `|` alternative), which is the form `docs/telemetry-runbook.md:1198` and two
-> of the three `transaction-overview.json` failure panels already use.
-
-Every dashboard exposes a `$node` template variable bound to
-`service_instance_id`; see the §5.1.1 note on why `service_instance_id` must be
-set for metric panels to split per node.
-
-### 5.8.4 TraceQL Query Examples
-
-Common queries for xrpld traces. Every span name and attribute below is one
-that the code actually emits — check against the `*SpanNames.h` constants
-before adding more.
-
-```
-# Find all traces for a specific transaction hash
-{resource.service.name="xrpld" && span.tx_hash="ABC123..."}
-
-# Find slow RPC commands (>100ms)
-{resource.service.name="xrpld" && name=~"rpc.command.*"} | { duration > 100ms }
-
-# Find consensus rounds taking >5 seconds
-{resource.service.name="xrpld" && name="consensus.round"} | { duration > 5s }
-
-# Find failed transaction processing
-{resource.service.name="xrpld" && name="tx.process" && span.ter_result!="tesSUCCESS"}
-
-# Find failed apply-pipeline stages (preflight / preclaim / transactor)
-{resource.service.name="xrpld" && name=~"tx\\.(preflight|preclaim|transactor)" && status=error}
-
-# Find transactions that arrived from a peer rather than a local client.
-# The `local` attribute lives on tx.process, NOT on tx.receive (see the note
-# below).
-{resource.service.name="xrpld" && name="tx.process" && span.local=false}
-
-# Compare latency across nodes
-{resource.service.name="xrpld" && name="rpc.command.account_info"} | avg_over_time(duration) by (resource.service.instance.id)
-```
-
-> Queries in earlier drafts used `tx.validate`, `tx.relay` and
-> `span.relay_count`. None of the three exists: signature/format validation
-> ships as `tx.preflight`/`tx.preclaim`, and no relay span or relay-count
-> attribute was ever built. See [02 §2.3.2](./02-design-decisions.md).
-
-> **TraceQL silently returns nothing for an absent attribute.** Unlike PromQL,
-> where a missing label compares equal to `""`, a TraceQL attribute predicate
-> matches only spans that actually carry the attribute — including negated
-> forms such as `!=` and `=~".*"`. So filtering on the wrong span name yields
-> zero rows with no error. `local` has exactly one set-site,
-> `NetworkOPs.cpp:1417`, and it is on **`tx.process`**: an earlier draft paired
-> it with `name="tx.receive"`, which can never match. Check the attribute's
-> owning span in
-> [09 §1.2](./09-data-collection-reference.md) before combining a `name=` and a
-> `span.` predicate.
-
-### 5.8.5 Correlation with Logs
-
-Log↔trace correlation is **implemented** (Phase 8) and needs no Promtail,
-Fluentd or PerfLog change. Two pieces:
-
-1. **The node stamps the IDs.** The journal sink `Logs::format()`
-   (`src/libxrpl/basics/Log.cpp:304-338`, guarded by `XRPL_ENABLE_TELEMETRY`)
-   reads the thread-local OTel context and, when a valid span is active,
-   prefixes the message with `trace_id=<32 hex> span_id=<16 hex>`. It reads
-   the context value directly rather than calling `GetSpan()` to avoid a heap
-   allocation on the (common) no-span path. This is the ordinary `debug.log`
-   stream — PerfLog is not involved, and the `setTraceId` hook described in
-   earlier drafts was never built.
-2. **The collector ingests them.** The `file_log` receiver tails
-   `/var/log/xrpld/*/debug.log` and its `regex_parser` lifts `trace_id` and
-   `span_id` as optional capture groups (§5.5.1). `resource/logs` applies an
-   `upsert` of `service.name=xrpld`, which Loki promotes to the stream label
-   `service_name`, so the canonical selector is **`{service_name="xrpld"}`**.
-   Logs land in Loki via `otlp_http/loki`.
-
-> **Known issue — the collector's `job` upsert is ineffective for stream
-> selection.** `resource/logs` also applies an `upsert` of a `job=xrpld` attribute
-> (`otel-collector-config.yaml:62-70`) with the stated intent that operators
-> could paste `{job="xrpld"}`. That does not work. On OTLP ingest Loki promotes
-> only an **allow-listed** set of resource attributes to indexed stream labels
-> (`service.name`, `service.namespace`, `service.instance.id`,
-> `deployment.environment`, the `k8s.*`/`cloud.*` keys); `job` is not on that
-> list, and this repo ships no Loki config override — `docker-compose.yml:116`
-> starts Loki with the image's built-in `/etc/loki/local-config.yaml`. `job`
-> therefore lands in **structured metadata**, which cannot appear in a stream
-> selector, so `{job="xrpld"}` returns an empty result rather than an error.
-> Corroboration in-repo: `docs/telemetry-runbook.md:2533` states the same
-> ("`service_name="xrpld"` (not `job="xrpld"`)"), and **all 38 Loki queries** in
-> the shipped dashboards (35 panel targets + 3 Loki-backed template variables)
-> select on `service_name` — **zero** use `job`. Either drop the `job`
-> upsert or add `job` to Loki's `distributor.otlp_config.resource_attributes`
-> allow-list via a mounted Loki config; until then, use `service_name`.
-
-Grafana then links the two directions: the Tempo datasource's `tracesToLogs`
-(`filterByTraceID: true`, `tags: []`) jumps trace → logs, and `loki.yaml`'s
-derived fields jump log → trace.
-
-### 5.8.6 Correlation with Insight/OTel System Metrics
-
-To correlate traces with Beast Insight system metrics:
-
-**Step 1: Export Insight metrics to Prometheus**
-
-Beast Insight metrics are exported natively via OTLP to the OTel Collector,
-which exposes them on its Prometheus endpoint (`:8889`) alongside spanmetrics.
-Set `server=otel` in the `[insight]` section of `xrpld.cfg`; no separate StatsD
-exporter or Prometheus scrape job is needed.
-
-`makeCollectorManager()` (`src/xrpld/app/main/CollectorManager.cpp`) reads these
-`[insight]` keys:
-
-| Key                   | Read at      | Effect when `server=otel`                                                                                                          |
-| --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `server`              | `:35`        | **Live.** `statsd` \| `otel` \| anything else. Selects the collector implementation.                                               |
-| `address`             | `:39`        | StatsD only — the UDP endpoint.                                                                                                    |
-| `prefix`              | `:41`, `:53` | **Inert.** Stored on the OTel collector but `formatName()` prepends nothing (`OTelCollector.cpp:855-866`); only StatsD applies it. |
-| `endpoint`            | `:50`        | **Inert.** Logged for diagnostics (`OTelCollector.cpp:730`), then unused.                                                          |
-| `service_instance_id` | `:58`        | **Inert.** `(void)`-discarded (`OTelCollector.cpp:722`).                                                                           |
-| `service_name`        | `:64`        | **Inert.** `(void)`-discarded (`OTelCollector.cpp:723`).                                                                           |
-
-> **Where the identity and endpoint actually come from.** `OTelCollector`
-> deliberately does **not** own a pipeline: it fetches the Meter from the
-> **global** MeterProvider that `Telemetry::initMetrics()` published
-> (`OTelCollector.cpp:726-745`). So the resource attributes — including
-> `service.instance.id`, which every dashboard filters on — and the exporter
-> URL both come from the **`[telemetry]`** section, not `[insight]`. The four
-> inert keys above are back-compat leftovers from the StatsD-era signature;
-> setting them has no effect. Set `[telemetry] service_instance_id` instead
-> (§5.1.1).
-
-> **`server=otel` is not the default.** `CollectorManager.cpp:72-75` falls through
-> to `NullCollector` for any unrecognised or absent `server` value, so a node
-> with no `[insight]` section emits no metrics at all.
-
-**Step 2: Correlate metrics to traces**
-
-Today this is a **time-range** correlation, not a click-through one: note the
-window from the metric panel, then search Tempo over the same window filtered
-by `service.instance.id`.
-
-> **Exemplars are NOT implemented.** Earlier drafts of this section instructed
-> operators to rely on automatic exemplars, set
-> `exemplarTraceIdDestinations` on the Prometheus datasource, and enable
-> `exemplar: true` on panels. None of that is wired up: the string `exemplar`
-> appears **nowhere** in `src/libxrpl/telemetry/`, `src/xrpld/telemetry/`, or
-> `docker/telemetry/`. Concretely, three things are missing —
->
-> 1. the SDK's exemplar filter is left at its default and no reservoir is
->    configured in `Telemetry::initMetrics()` or `MetricsRegistry`;
-> 2. the collector's `prometheus` exporter has no exemplar settings;
-> 3. `grafana/provisioning/datasources/prometheus.yaml` has no
->    `exemplarTraceIdDestinations` block.
->
-> Note also that the query used as an example, `rpc_duration_seconds_bucket`,
-> does not exist — RPC latency histograms are `span_duration_milliseconds_bucket`
-> (spanmetrics, `unit: ms`) and `rpc_method_us` (native). Wiring exemplars end
-> to end is genuine open work; until it lands, do not document a click-through
-> that operators cannot perform.
-
-**Step 3: Jump the other way instead**
-
-Trace → metrics is available now: the Tempo datasource sets
-`tracesToMetrics.datasourceUid: prometheus` with a ±1h time shift, so the
-span-metric queries it builds resolve against the `span_*` families the
-collector's `spanmetrics` connector produces. Trace → logs and log → trace are
-both live (§5.8.5).
-
-> **Known gap — Service Map is configured but inactive.** The Tempo datasource
-> declares `serviceMap.datasourceUid: prometheus`, and `tempo.yaml:70-76`
-> enables the `service-graphs` metrics-generator processor, but the generator
-> has nowhere to write: its `remote_write` block is **commented out**
-> (`tempo.yaml:53-56`), and `prometheus.yml:6-9` defines a single scrape job
-> against `otel-collector:8889` — it never scrapes or accepts writes from
-> Tempo. `traces_service_graph_request_total` and its siblings are therefore
-> never stored, so the Service Map / Node Graph tab renders empty. The same gap
-> means Tempo's `span-metrics` processor never lands
-> `traces_spanmetrics_*` either (§5.5.1) — every span metric the dashboards use
-> comes from the collector's connector instead. Closing it needs both halves:
-> uncomment `remote_write` in `tempo.yaml` **and** enable
-> `--web.enable-remote-write-receiver` on the Prometheus service (or add a
-> scrape job for Tempo).
-
----
-
-_Previous: [Implementation Strategy](./03-implementation-strategy.md)_ | _Next: [Implementation Phases](./06-implementation-phases.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/07-observability-backends.md

@@ -1,572 +0,0 @@
-# Observability Backend Recommendations
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Phases](./06-implementation-phases.md) | [Appendix](./08-appendix.md)
-
----
-
-## 7.1 Development/Testing Backends
-
-> **OTLP** = OpenTelemetry Protocol
-
-| Backend    | Pros                                | Cons                   | Use Case            |
-| ---------- | ----------------------------------- | ---------------------- | ------------------- |
-| **Tempo**  | Cost-effective, Grafana integration | Requires Grafana stack | Local dev, CI, Prod |
-| **Zipkin** | Simple, lightweight                 | Basic features         | Quick prototyping   |
-
-### Quick Start with Tempo
-
-```bash
-# Start Tempo with OTLP support.
-# Version pinned to match docker/telemetry/docker-compose.yml:55 — keep the
-# two in step, since Tempo config keys change between minor releases.
-#
-# Only 4317 (OTLP/gRPC) is published: docker/telemetry/tempo.yaml:28-33
-# declares a single distributor receiver, `otlp.protocols.grpc` on
-# 0.0.0.0:4317. There is no `http` protocol block, so nothing listens on 4318
-# and publishing it would give you a port that silently refuses connections.
-# 3200 is Tempo's HTTP API/query port (tempo.yaml:17-18), not an ingest port.
-docker run -d --name tempo \
-    -p 3200:3200 \
-    -p 4317:4317 \
-    grafana/tempo:2.9.4
-```
-
-> Note that xrpld itself exports OTLP/**HTTP** only (§2.2.1), so it cannot send
-> to this container directly — the collector is what bridges HTTP ingest to
-> Tempo's gRPC receiver (`otlp/tempo` → `tempo:4317`). A bare Tempo container is
-> useful for replaying traces from another OTLP/gRPC producer, not as an xrpld
-> endpoint.
-
-> In practice, prefer the full stack —
-> `docker compose -f docker/telemetry/docker-compose.yml up -d` — over a bare
-> Tempo container. Most shipped dashboards query Prometheus span metrics, which
-> need the collector and Prometheus services too. See
-> [05 §5.6](./05-configuration-reference.md).
-
----
-
-## 7.2 Production Backends
-
-> **APM** = Application Performance Monitoring
-
-| Backend           | Pros                                      | Cons                   | Use Case                    |
-| ----------------- | ----------------------------------------- | ---------------------- | --------------------------- |
-| **Grafana Tempo** | Cost-effective, Grafana integration       | Requires Grafana stack | Most production deployments |
-| **Elastic APM**   | Full observability stack, log correlation | Resource intensive     | Existing Elastic users      |
-| **Honeycomb**     | Excellent query, high cardinality         | SaaS cost              | Deep debugging needs        |
-| **Datadog APM**   | Full platform, easy setup                 | SaaS cost              | Enterprise with budget      |
-
-### Backend Selection Flowchart
-
-```mermaid
-flowchart TD
-    start[Select Backend] --> budget{Budget<br/>Constraints?}
-
-    budget -->|Yes| oss[Open Source]
-    budget -->|No| saas{Prefer<br/>SaaS?}
-
-    oss --> existing{Existing<br/>Stack?}
-    existing -->|Grafana| tempo[Grafana Tempo]
-    existing -->|Elastic| elastic[Elastic APM]
-    existing -->|None| tempo
-
-    saas -->|Yes| enterprise{Enterprise<br/>Support?}
-    saas -->|No| oss
-
-    enterprise -->|Yes| datadog[Datadog APM]
-    enterprise -->|No| honeycomb[Honeycomb]
-
-    tempo --> final[Configure Collector]
-    elastic --> final
-    honeycomb --> final
-    datadog --> final
-
-    style start fill:#0f172a,stroke:#020617,color:#fff
-    style budget fill:#334155,stroke:#1e293b,color:#fff
-    style oss fill:#1e293b,stroke:#0f172a,color:#fff
-    style existing fill:#334155,stroke:#1e293b,color:#fff
-    style saas fill:#334155,stroke:#1e293b,color:#fff
-    style enterprise fill:#334155,stroke:#1e293b,color:#fff
-    style final fill:#0f172a,stroke:#020617,color:#fff
-    style tempo fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style elastic fill:#bf360c,stroke:#8c2809,color:#fff
-    style honeycomb fill:#0d47a1,stroke:#082f6a,color:#fff
-    style datadog fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-**Reading the diagram:**
-
-- **Budget Constraints? (Yes)**: Leads to open-source options. If you already run Grafana or Elastic, pick the matching backend; otherwise default to Grafana Tempo.
-- **Budget Constraints? (No) → Prefer SaaS?**: If you want a managed service, choose between Datadog (enterprise support) and Honeycomb (developer-focused). If not, fall back to open-source.
-- **Terminal nodes (Tempo / Elastic / Honeycomb / Datadog)**: Each represents a concrete backend choice, all of which feed into the same final step.
-- **Configure Collector**: Regardless of backend, you always finish by configuring the OTel Collector to export to your chosen destination.
-
----
-
-## 7.3 Recommended Production Architecture
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring | **HA** = High Availability
-
-```mermaid
-flowchart TB
-    subgraph validators["Validator Nodes"]
-        v1[xrpld<br/>Validator 1]
-        v2[xrpld<br/>Validator 2]
-    end
-
-    subgraph stock["Stock Nodes"]
-        s1[xrpld<br/>Stock 1]
-        s2[xrpld<br/>Stock 2]
-    end
-
-    subgraph collector["OTel Collector Cluster"]
-        c1[Collector<br/>DC1]
-        c2[Collector<br/>DC2]
-    end
-
-    subgraph backends["Storage Backends"]
-        tempo[(Grafana<br/>Tempo)]
-        elastic[(Elastic<br/>APM)]
-        archive[(S3/GCS<br/>Archive)]
-    end
-
-    subgraph ui["Visualization"]
-        grafana[Grafana<br/>Dashboards]
-    end
-
-    v1 -->|OTLP| c1
-    v2 -->|OTLP| c1
-    s1 -->|OTLP| c2
-    s2 -->|OTLP| c2
-
-    c1 --> tempo
-    c1 --> elastic
-    c2 --> tempo
-    c2 --> archive
-
-    tempo --> grafana
-    elastic --> grafana
-
-    %% Note: simplified single-collector-per-DC topology shown for clarity
-
-    style validators fill:#b71c1c,stroke:#7f1d1d,color:#ffffff
-    style stock fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style collector fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style backends fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style ui fill:#4a148c,stroke:#2e0d57,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **Validator / Stock Nodes**: All xrpld nodes emit trace data via OTLP. Validators and stock nodes are grouped separately because they may reside in different network zones.
-- **Collector Cluster (DC1, DC2)**: Regional collectors receive OTLP from nodes in their datacenter, apply processing (sampling, enrichment), and fan out to multiple backends. Enrichment includes deployment-tier tagging: each collector stamps `deployment.environment` and (as a fallback) `xrpl.network.type` so one Grafana stack can filter data from many collectors by tier.
-- **Storage Backends**: Tempo and Elastic provide queryable trace storage; S3/GCS Archive provides long-term cold storage for compliance or post-incident analysis.
-- **Grafana Dashboards**: The single visualization layer that queries both Tempo and Elastic, giving operators a unified view of all traces.
-- **Data flow direction**: Nodes → Collectors → Storage → Grafana. Each arrow represents a network hop; minimizing collector-to-backend hops reduces latency.
-
-> **Note**: Production deployments should use multiple collector instances behind a load balancer for high availability. The diagram shows a simplified single-collector topology for clarity.
-
----
-
-## 7.4 Architecture Considerations
-
-### 7.4.1 Collector Placement
-
-| Strategy      | Description          | Pros                     | Cons                    |
-| ------------- | -------------------- | ------------------------ | ----------------------- |
-| **Sidecar**   | Collector per node   | Isolation, simple config | Resource overhead       |
-| **DaemonSet** | Collector per host   | Shared resources         | Complexity              |
-| **Gateway**   | Central collector(s) | Centralized processing   | Single point of failure |
-
-**Recommendation**: Use **Gateway** pattern with regional collectors for xrpld networks:
-
-- One collector cluster per datacenter/region
-- Tail-based sampling at collector level
-- Multiple export destinations for redundancy
-
-### 7.4.2 Sampling Strategy
-
-An earlier version of this section described a three-policy tail sampler (keep
-all errors / keep anything >5s / keep 10% of the rest). **No such sampler
-exists in this repo.** What ships is below.
-
-```mermaid
-flowchart LR
-    subgraph head["Head Sampling (Node) — fixed"]
-        hs["ParentBased(TraceIdRatio 1.0)<br/>samplingRatio is static constexpr<br/>no config key exists<br/>100% of spans exported"]
-    end
-
-    subgraph tail["Tail Sampling (Collector) — opt-in"]
-        base["Base config:<br/>NO tail_sampling processor<br/>100% of traces stored"]
-        cloud["grafanacloud overlay only:<br/>one probabilistic policy<br/>sampling_percentage: 0.5"]
-    end
-
-    head --> tail
-    base --> final["Stored Traces"]
-    cloud --> final
-
-    style head fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style tail fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style hs fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style base fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style cloud fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style final fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **Head Sampling (Node)** — fixed at 100% and genuinely not configurable:
-  `Telemetry.h:234` declares `static constexpr double samplingRatio = 1.0;` and
-  `TelemetryConfig.cpp:139` records that there is nothing to parse. This is
-  intentional: a per-node ratio would let different nodes make divergent
-  keep/drop decisions for the same distributed trace, producing broken/partial
-  traces. The ratio sampler is wrapped in a `ParentBased` sampler so spans
-  inheriting a remote parent honour the upstream decision.
-- **Tail Sampling (Collector)** — the base config
-  (`docker/telemetry/otel-collector-config.yaml`) has **no** `tail_sampling`
-  processor, so the local and CI stacks keep 100% of traces. The only shipped
-  policy lives in `otel-collector-config.grafanacloud.yaml:60-67`, wired into
-  the **`traces/store`** pipeline (`:259-261`) — the overlay has no pipeline
-  named `traces`; it splits the trace stream into `traces/metrics` (unsampled,
-  feeds `spanmetrics`) and `traces/store` (sampled, feeds Tempo and Grafana
-  Cloud). See [05 §5.5.2](./05-configuration-reference.md) for the full overlay
-  delta. The policy is a single `probabilistic` at **0.5%**,
-  `decision_wait: 10s`, `num_traces: 50000`. There are no error or latency
-  carve-outs.
-- **Why 0.5% does not damage the dashboards**: the policy is applied on the
-  trace-storage branch only. The `spanmetrics` connector runs on a separate
-  branch that still sees every span, so `span_calls_total` and
-  `span_duration_milliseconds_*` remain exact. Sampling costs you individual
-  example traces in Tempo, not metric accuracy.
-- **If you want the error/latency policies**: they are a reasonable thing to
-  add, but they must be written — and `decision_wait` sized so a trace's spans
-  have all arrived before the policy evaluates it.
-
-#### Companion guard: `memory_limiter` (recommended, not configured)
-
-Tail sampling bounds what the collector **stores**; it does not bound what the
-collector **buffers**. `tail_sampling` is the opposite of cheap here — it holds
-up to `num_traces` (50 000) traces in memory for `decision_wait` before
-deciding — and the `spanmetrics` connector keeps a live series cache on top of
-that. A production gateway collector should therefore also run a
-[`memory_limiter`](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md)
-processor as an OOM guard: it applies backpressure (refusing new data with a
-retryable error, which the node's `sending_queue` will retry) instead of letting
-the process be killed and losing every buffered trace.
-
-> **Not currently configured anywhere in this repo.** Neither
-> `otel-collector-config.yaml` nor
-> `otel-collector-config.grafanacloud.yaml` declares a `memory_limiter`, and
-> neither compose file sets a container memory limit — so today a traffic spike
-> is bounded only by host RAM. This is a recommendation for real deployments,
-> recorded here because [05 §5.5.1](./05-configuration-reference.md) lists
-> `memory_limiter` among the processors deliberately **absent** from the shipped
-> config and that must not be read as "not needed". Placement rules if you add
-> it: it must be the **first** processor in every pipeline (ahead of `batch`),
-> and `limit_mib` must sit below the container/cgroup limit with headroom for
-> the sampling and spanmetrics caches.
-
-### 7.4.3 Data Retention
-
-| Environment                 | Hot Storage | Warm Storage | Cold Archive | Source                                                       |
-| --------------------------- | ----------- | ------------ | ------------ | ------------------------------------------------------------ |
-| Development (local stack)   | **1 hour**  | N/A          | N/A          | `tempo.yaml:40` — `compactor.compaction.block_retention: 1h` |
-| Staging (recommendation)    | 7 days      | N/A          | N/A          | Not configured in this repo                                  |
-| Production (recommendation) | 7 days      | 30 days      | many years   | Not configured in this repo                                  |
-
-> **The local stack keeps traces for 1 hour, not 24.** `block_retention: 1h`
-> is deliberate — it bounds disk for a long-running dev node — but it means a
-> trace you found this morning is gone by lunchtime. Raise
-> `block_retention` in `docker/telemetry/tempo.yaml` before starting any
-> investigation that needs to span a working day. The staging and production
-> rows are recommendations only; nothing in this repo provisions them.
-
----
-
-## 7.5 Integration Checklist
-
-- [ ] Choose primary backend (Tempo recommended for cost/features)
-- [ ] Deploy collector cluster with high availability
-- [ ] Configure tail-based sampling for error/latency traces
-- [ ] Set up Grafana dashboards for trace visualization
-- [ ] Configure alerts for trace anomalies
-- [ ] Establish data retention policies
-- [ ] Test trace correlation with logs and metrics
-
----
-
-## 7.6 Grafana Dashboards and Alerts
-
-> **Superseded.** This section was written in Phase 1a, before any dashboard
-> shipped, and described three hypothetical boards (`xrpld-consensus-health`,
-> `xrpld-node-overview`, `xrpld-unified`) and three TraceQL alert rules in a
-> group called `xrpld-tracing-alerts`. **None of those uids or rule names exist
-> anywhere in the repo.** What actually ships is 15 dashboards and 13 alert
-> rules, and both are Prometheus-first rather than TraceQL-first. The
-> authoritative references are:
->
-> | For                                              | See                                                                                                       |
-> | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-> | Dashboard and panel inventory, per-panel queries | [09-data-collection-reference.md](./09-data-collection-reference.md)                                      |
-> | Alert catalogue, thresholds and response steps   | `docs/telemetry-runbook.md`                                                                               |
-> | Files on disk                                    | `docker/telemetry/grafana/dashboards/*.json`, `docker/telemetry/grafana/provisioning/alerting/rules.yaml` |
->
-> The rest of this section records only the facts a reader needs so as not to
-> chase the removed names.
-
-### 7.6.1 Shipped Dashboards
-
-15 JSON dashboards are provisioned into Grafana folder `xrpld`. The uids are
-bare — there is no `xrpld-` prefix:
-
-`consensus-health`, `fee-market`, `job-queue`, `ledger-data-sync`,
-`ledger-operations`, `log-derived-insights`, `network-traffic`, `node-health`,
-`overlay-traffic-detail`, `peer-network`, `peer-quality`, `rpc-pathfinding`,
-`rpc-performance`, `transaction-overview`, `validator-health`.
-
-> **Panel-count convention** (shared with [05 §5.8.3](./05-configuration-reference.md)):
-> counts are of **data panels only**. `type: "row"` collapsible headers are
-> excluded because a row carries no query, so a board's raw `panels` array is
-> longer than its stated count.
-
-`consensus-health.json` is a useful calibration for how far this section drifted:
-where the removed text described "four TraceQL panels", the real board carries **22
-data panels** in 4 rows (26 `panels` array entries) — 19 Prometheus targets
-against `${DS_PROMETHEUS}` and 9 TraceQL targets against `${DS_TEMPO}`. Tempo is
-used for trace _drill-down_; the time series come from span metrics.
-
-### 7.6.2 Shipped Alert Rules
-
-`docker/telemetry/grafana/provisioning/alerting/rules.yaml` provisions **13
-rules in 5 groups**, all in folder `xrpld`, all `interval: 1m`, and all
-**PromQL** — there are zero TraceQL alert rules.
-
-| Group              | Rules                                                                       |
-| ------------------ | --------------------------------------------------------------------------- |
-| `xrpld-consensus`  | `LedgerHistoryMismatch`, `LedgerCloseStalled`, `ValidatedLedgerStale`       |
-| `xrpld-validator`  | `ValidationsMissed`, `ValidationsNotChecked`                                |
-| `xrpld-jobqueue`   | `JobQueueTxOverflow`, `JobQueueLatencyHigh`, `NodeStoreIOLatencyHigh`       |
-| `xrpld-node-state` | `NodeStateFlapping`, `NodeNotFull`                                          |
-| `xrpld-overlay`    | `ManifestJobQueueConvoy`, `ManifestFloodInbound`, `PeerResourceDisconnects` |
-
-> Two placements are worth noting because they are not what the rule name
-> suggests. `ValidatedLedgerStale` is grouped under `xrpld-consensus`, not
-> `xrpld-validator` — it fires on any node whose validated-ledger sequence stops
-> advancing, which is a chain-progress symptom rather than a validator-identity
-> one. `NodeStoreIOLatencyHigh` is grouped under `xrpld-jobqueue`, not
-> `xrpld-node-state` — slow NodeStore I/O manifests first as job-queue backlog,
-> so grouping it there keeps the cause and its effect in one notification.
-
-Thresholds, measured baselines and response procedures are in the runbook's
-alert catalogue, not here.
-
-### 7.6.3 Writing New Rules: the metric name
-
-If you add a span-metric alert, the metric is **`span_calls_total`**. This stack
-sets the `span_metrics` connector's `namespace: "span"`
-(`otel-collector-config.yaml:114`); the connector's own default namespace is
-**empty**, so without that setting the names would be the bare `calls_total` /
-`duration_milliseconds_*`. 7 of the 15 dashboards already query the `span_`
-names. Durations are likewise `span_duration_milliseconds_bucket`.
-
-> **`traces_spanmetrics_*` is a different producer, not the connector's
-> default.** That family is emitted by **Tempo's** `metrics_generator`
-> `span-metrics` processor (`tempo.yaml:70-76`), which is a separate
-> implementation from the collector connector. It does not exist in this stack
-> either: the generator's `remote_write` is commented out (`tempo.yaml:53-56`)
-> and `prometheus.yml:6-9` scrapes only `otel-collector:8889`, so nothing stores
-> what Tempo generates. Do not write a rule against `traces_spanmetrics_*` and
-> do not describe `namespace: "span"` as overriding it.
-
-An RPC error-rate rule, written against the real metric name, looks like this.
-Note that error _rate_ is a ratio, so it must divide the error-span rate by the
-total-span rate — a bare rate returns calls/second and would fire on traffic
-volume alone:
-
-```
-sum(rate(span_calls_total{service_name="xrpld", span_name=~"rpc.command.*", status_code="STATUS_CODE_ERROR"}[5m]))
-/
-sum(rate(span_calls_total{service_name="xrpld", span_name=~"rpc.command.*"}[5m]))
-> 0.05
-```
-
-> **Prefer PromQL over TraceQL for alerting.** TraceQL aggregates
-> (`avg(duration)`, `rate()`) need Tempo 2.3+ with TraceQL metrics enabled, are
-> slower, and are distorted by any tail sampling in the path (§7.4.2). Span
-> metrics are computed pre-sampling and cost nothing extra to query. That is
-> why all 13 shipped rules are PromQL.
-
----
-
-## 7.7 PerfLog and Insight Correlation
-
-> **OTLP** = OpenTelemetry Protocol
-
-How to correlate OpenTelemetry traces with existing xrpld observability.
-
-### 7.7.1 Correlation Architecture
-
-There is **one** collection agent, not three. Earlier drafts of this diagram
-routed logs through "Promtail/Fluentd" and metrics through a "StatsD Exporter";
-neither exists in this stack. Logs are read by the OTel Collector's own
-`file_log` receiver, and `beast::insight` metrics arrive at the same collector
-over OTLP (`[insight] server=otel`). The single-agent shape is the point: one
-process, one config file, one place to add redaction or tier tagging.
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Node"]
-        otel["OpenTelemetry Spans"]
-        journal["Journal debug.log<br/>trace_id= span_id= prefix<br/>(Log.cpp:304-338)"]
-        insight["Beast Insight + XRPL_METRIC_*<br/>native OTLP metrics"]
-    end
-
-    otelc["OTel Collector<br/>receivers: otlp, file_log<br/>connector: spanmetrics<br/>3 pipelines"]
-
-    subgraph storage["Storage"]
-        tempo[("Tempo")]
-        loki[("Loki")]
-        prom[("Prometheus")]
-    end
-
-    dashboards["Grafana<br/>Tempo to Loki via tracesToLogs<br/>Loki to Tempo via derived fields"]
-
-    otel -->|"OTLP/HTTP :4318"| otelc
-    journal -->|"file_log tails<br/>/var/log/xrpld"| otelc
-    insight -->|"OTLP/HTTP :4318"| otelc
-
-    otelc -->|"otlp/tempo"| tempo
-    otelc -->|"otlp_http/loki"| loki
-    otelc -->|"prometheus :8889"| prom
-
-    tempo --> dashboards
-    loki --> dashboards
-    prom --> dashboards
-
-    style xrpld fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style storage fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style otel fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style journal fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style insight fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style otelc fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style tempo fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style loki fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style prom fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style dashboards fill:#4a148c,stroke:#2e0d57,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **xrpld Node (three signals, one transport)**: spans and metrics both leave over OTLP/HTTP on port 4318. Logs do not leave the node at all — the node just writes `debug.log`, and the journal sink prefixes `trace_id=`/`span_id=` whenever a span is active (`Log.cpp:304-338`).
-- **OTel Collector (single agent)**: an `otlp` receiver takes spans and metrics; a `file_log` receiver tails `/var/log/xrpld/*/debug.log` and regex-parses the trace/span IDs out of each line. A `spanmetrics` connector derives RED metrics from the trace stream and feeds them into the metrics pipeline. Three pipelines, three exporters — see [05 §5.5.1](./05-configuration-reference.md).
-- **PerfLog is not in this picture.** It still writes `perf.log`, but nothing collects it and it carries no trace ID; the `setTraceId` hook once planned for it was never built ([02 §2.6.5](./02-design-decisions.md)).
-- **StatsD is not in this picture either.** It remains a supported `[insight] server=` choice, but selecting it takes metrics _out_ of this pipeline and requires a StatsD receiver you would have to add yourself — the compose file's StatsD port mapping is commented out.
-- **Grafana**: correlation is bidirectional and configured in the datasources, not in a bespoke panel — Tempo's `tracesToLogs` (`filterByTraceID: true`) jumps trace → logs, and `loki.yaml`'s derived fields jump log → trace.
-
-### 7.7.2 Correlation Fields
-
-| Source          | Field                 | Link To | Status                                                                                                                                                                                                                                                            |
-| --------------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Trace**       | `trace_id`            | Logs    | **Live.** Tempo `tracesToLogs`, `filterByTraceID: true`                                                                                                                                                                                                           |
-| **Trace**       | `tx_hash`             | —       | Live as a span attribute for search; **not** used as a cross-signal join key (`tags: []`)                                                                                                                                                                         |
-| **Trace**       | `ledger_seq`          | —       | Live as a span attribute; not a join key                                                                                                                                                                                                                          |
-| **Journal log** | `trace_id`, `span_id` | Traces  | **Live.** Emitted by `Log.cpp:304-338` into `debug.log`, parsed by the collector's `file_log` receiver, jumped via `loki.yaml` derived fields                                                                                                                     |
-| **PerfLog**     | `trace_id`            | Traces  | **Not implemented.** PerfLog output has no trace ID; the planned `setTraceId` hook was never built. Use the journal log instead                                                                                                                                   |
-| **Insight**     | `exemplar.trace_id`   | Traces  | **Not implemented.** No exemplar configuration exists anywhere in the code or collector config — no `exemplar_filter` on the SDK side, no `exemplarTraceIdDestinations` on the Prometheus datasource. Metric spike → trace jumps must be done by time range today |
-
-### 7.7.3 Example: Debugging a Slow Transaction
-
-**Step 1: Find the trace**
-
-```
-# In Grafana Explore with Tempo
-{resource.service.name="xrpld" && span.tx_hash="ABC123..."}
-```
-
-**Step 2: Get the trace_id from the trace view**
-
-```
-Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736
-```
-
-**Step 3: Find related log lines**
-
-```
-# In Grafana Explore with Loki. `service_name` is the promoted stream label;
-# do NOT use {job="xrpld"} — see the note below.
-{service_name="xrpld"} |= "4bf92f3577b34da6a3ce929d0e0e4736"
-```
-
-These are journal (`debug.log`) lines, not PerfLog lines — see §7.7.2.
-
-> **Known issue — `{job="xrpld"}` does not select anything.** The collector's
-> `resource/logs` processor does upsert a `job=xrpld` resource attribute
-> (`otel-collector-config.yaml:62-70`), explicitly so that operators could paste
-> `{job="xrpld"}`. Loki does not cooperate: on OTLP ingest it promotes only an
-> **allow-listed** set of resource attributes to indexed stream labels
-> (`service.name`, `service.namespace`, `service.instance.id`,
-> `deployment.environment`, `k8s.*`, `cloud.*`), and `job` is not on it. This
-> repo mounts no Loki config override (`docker-compose.yml:116` uses the image's
-> built-in `local-config.yaml`), so `job` lands in **structured metadata** —
-> queryable only with a `|` filter after a selector, never as the selector
-> itself. A `{job="xrpld"}` query returns empty with no error, which is why this
-> is easy to miss. `docs/telemetry-runbook.md:2533` says the same, and all 38
-> Loki queries in the shipped dashboards (35 panel targets + 3 template
-> variables) select on `service_name` — zero use `job`. Fix options:
-> drop the ineffective `job` upsert, or mount a Loki config adding `job` to
-> `distributor.otlp_config.resource_attributes`.
-
-**Step 4: Check metrics for the time window**
-
-```
-# In Grafana with Prometheus. Span-derived RED metrics for the transaction
-# pipeline (namespace "span" — see 7.6.3):
-sum(rate(span_calls_total{span_name="tx.process"}[1m])) by (service_instance_id)
-
-# Error share of the same pipeline. Note !~"tesSUCCESS|" — NOT
-# !="tesSUCCESS" — so spans that carry no ter_result are excluded:
-sum(rate(span_calls_total{span_name="tx.process", ter_result!~"tesSUCCESS|"}[5m]))
-/
-sum(rate(span_calls_total{span_name="tx.process"}[5m]))
-```
-
-> **Why the regex form.** An absent Prometheus label is indistinguishable from
-> the empty string, and `tx.process` can end **without** a `ter_result`: the span
-> is opened at `NetworkOPs.cpp:1416`, but `processTransaction()` returns early
-> when `preProcessTransaction()` rejects the transaction (`:1437-1438`), and
-> `doTransactionAsync()` returns early when the transaction is already applying
-> (`:1461-1462`) — both before the only setter, at `:1674`. Those series arrive
-> with `ter_result=""`, which `!="tesSUCCESS"` happily counts as a failure and
-> inflates the ratio. `!~"tesSUCCESS|"` excludes the empty value via the trailing
-> `|` alternative. This is the form `docs/telemetry-runbook.md:1198` and the
-> `transaction-overview.json` stage-failure panels already use; apply it to any
-> new `ter_result` predicate.
-
-> Earlier drafts used `rate(xrpld_tx_applied_total[1m])` and
-> `rate(xrpld_tx_received_total[5m])`. **Neither metric exists** — there is no
-> `xrpld_`-prefixed metric family at all, because `OTelCollector::formatName()`
-> deliberately prepends no prefix (`OTelCollector.cpp:855-866`); the OTel
-> resource `service.name` identifies the service instead. Use the `span_*`
-> families above (verified in `transaction-overview.json` and
-> `rpc-performance.json`) or the native `XRPL_METRIC_*` instrument names listed
-> in [09-data-collection-reference.md](./09-data-collection-reference.md).
-
-### 7.7.4 Unified Dashboard
-
-> **Superseded.** No `xrpld-unified` dashboard exists. The single-pane view it
-> described is instead delivered by two things that did ship: the
-> **`log-derived-insights`** dashboard (31 data panels in 10 rows, all
-> Loki-backed — 41 `panels` array entries; see the counting convention in
-> §7.6.1) plus the
-> bidirectional datasource links (Tempo `tracesToLogs` → Loki, `loki.yaml`
-> derived fields → Tempo), which let you cross signals from _any_ board rather
-> than only from one dedicated dashboard.
->
-> The correlation fields those links rely on — and which of them are actually
-> implemented — are in §7.7.2. For the full board inventory see
-> [09-data-collection-reference.md](./09-data-collection-reference.md).
-
----
-
-_Previous: [Implementation Phases](./06-implementation-phases.md)_ | _Next: [Appendix](./08-appendix.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/08-appendix.md

@@ -1,232 +0,0 @@
-# Appendix
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Observability Backends](./07-observability-backends.md)
-
----
-
-## 8.1 Glossary
-
-> **OTLP** = OpenTelemetry Protocol | **TxQ** = Transaction Queue
-
-| Term                  | Definition                                                 |
-| --------------------- | ---------------------------------------------------------- |
-| **Span**              | A unit of work with start/end time, name, and attributes   |
-| **Trace**             | A collection of spans representing a complete request flow |
-| **Trace ID**          | 128-bit unique identifier for a trace                      |
-| **Span ID**           | 64-bit unique identifier for a span within a trace         |
-| **Context**           | Carrier for trace/span IDs across boundaries               |
-| **Propagator**        | Component that injects/extracts context                    |
-| **Sampler**           | Decides which traces to record                             |
-| **Exporter**          | Sends spans to backend                                     |
-| **Collector**         | Receives, processes, and forwards telemetry                |
-| **OTLP**              | OpenTelemetry Protocol (wire format)                       |
-| **W3C Trace Context** | Standard HTTP headers for trace propagation                |
-| **Baggage**           | Key-value pairs propagated across service boundaries       |
-| **Resource**          | Entity producing telemetry (service, host, etc.)           |
-| **Instrumentation**   | Code that creates telemetry data                           |
-
-### xrpld-Specific Terms
-
-| Term              | Definition                                                    |
-| ----------------- | ------------------------------------------------------------- |
-| **Overlay**       | P2P network layer managing peer connections                   |
-| **Consensus**     | XRP Ledger consensus algorithm (RCL)                          |
-| **Proposal**      | Validator's suggested transaction set for a ledger            |
-| **Validation**    | Validator's signature on a closed ledger                      |
-| **HashRouter**    | Component for transaction deduplication                       |
-| **JobQueue**      | Thread pool for asynchronous task execution                   |
-| **PerfLog**       | Existing performance logging system in xrpld                  |
-| **Beast Insight** | Existing metrics framework in xrpld                           |
-| **PathFinding**   | Payment path computation engine for cross-currency payments   |
-| **TxQ**           | Transaction queue managing fee-based prioritization           |
-| **LoadManager**   | Dynamic fee escalation based on network load                  |
-| **SHAMap**        | SHA-256 hash-based map (Merkle trie variant) for ledger state |
-
-### Phase 9–11 Terms
-
-| Term                        | Definition                                                                |
-| --------------------------- | ------------------------------------------------------------------------- |
-| **MetricsRegistry**         | Centralized class for OTel async gauge registrations (Phase 9)            |
-| **ObservableGauge**         | OTel Metrics SDK async instrument polled via callback at fixed intervals  |
-| **PeriodicMetricReader**    | OTel SDK component that invokes gauge callbacks at configurable intervals |
-| **CountedObject**           | xrpld template that tracks live instance counts via atomic counters       |
-| **TxQ**                     | Transaction queue managing fee escalation and ordering                    |
-| **Load Factor**             | Combined multiplier affecting transaction cost (local, cluster, network)  |
-| **OTel Collector Receiver** | Custom Go plugin that polls xrpld RPC and emits OTel metrics (Phase 11)   |
-
----
-
-## 8.2 Span Hierarchy Visualization
-
-The authoritative span-flow diagrams — a master overview plus per-stage
-flowcharts (ingress, the shared apply pipeline, the consensus round, ledger
-finalize, and the pathfinding / ledger-acquire side flows) — live in the operator
-runbook. They map every span onto the **real xrpld control flow and XRPL protocol
-order** (verified against code and `docs/consensus.md`, with file:line evidence),
-label every node and branch with the span that represents that state or
-transition, and call out where the OpenTelemetry span parent links diverge from
-that flow.
-
-> **See**: [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow).
-
-The full span inventory (names, attributes, parents as instrumented) is in
-[09-data-collection-reference.md §1](./09-data-collection-reference.md#1-opentelemetry-spans).
-
----
-
-## 8.3 References
-
-> **OTLP** = OpenTelemetry Protocol
-
-### OpenTelemetry Resources
-
-1. [OpenTelemetry C++ SDK](https://github.com/open-telemetry/opentelemetry-cpp)
-2. [OpenTelemetry Specification](https://opentelemetry.io/docs/specs/otel/)
-3. [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
-4. [OTLP Protocol Specification](https://opentelemetry.io/docs/specs/otlp/)
-
-### Standards
-
-5. [W3C Trace Context](https://www.w3.org/TR/trace-context/)
-6. [W3C Baggage](https://www.w3.org/TR/baggage/)
-7. [Protocol Buffers](https://protobuf.dev/)
-
-### xrpld Resources
-
-8. [xrpld Source Code](https://github.com/XRPLF/rippled)
-9. [XRP Ledger Documentation](https://xrpl.org/docs/)
-10. [xrpld Overlay README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/README.md)
-11. [xrpld RPC README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/rpc/README.md)
-12. [xrpld Consensus README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/app/consensus/README.md)
-
----
-
-## 8.4 Version History
-
-| Version | Date       | Author | Changes                                                        |
-| ------- | ---------- | ------ | -------------------------------------------------------------- |
-| 1.0     | 2026-02-12 | -      | Initial implementation plan                                    |
-| 1.1     | 2026-02-13 | -      | Refactored into modular documents                              |
-| 1.2     | 2026-03-09 | -      | Added Phases 9–11 (future enhancement plans)                   |
-| 1.3     | 2026-03-24 | -      | Review fixes: accuracy corrections, cross-document consistency |
-
----
-
-## 8.5 Document Index
-
-### Plan Documents
-
-| Document                                                             | Description                                  |
-| -------------------------------------------------------------------- | -------------------------------------------- |
-| [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)                       | Master overview and executive summary        |
-| [00-tracing-fundamentals.md](./00-tracing-fundamentals.md)           | Distributed tracing concepts and OTel primer |
-| [01-architecture-analysis.md](./01-architecture-analysis.md)         | xrpld architecture and trace points          |
-| [02-design-decisions.md](./02-design-decisions.md)                   | SDK selection, exporters, span conventions   |
-| [03-implementation-strategy.md](./03-implementation-strategy.md)     | Directory structure, performance analysis    |
-| [05-configuration-reference.md](./05-configuration-reference.md)     | xrpld config, CMake, Collector configs       |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Timeline, tasks, risks, success metrics      |
-| [07-observability-backends.md](./07-observability-backends.md)       | Backend selection and architecture           |
-| [08-appendix.md](./08-appendix.md)                                   | Glossary, references, version history        |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Span/metric/dashboard inventory              |
-
-### Task Lists
-
-| Document                                                                   | Description                                    |
-| -------------------------------------------------------------------------- | ---------------------------------------------- |
-| [Phase2_taskList.md](./Phase2_taskList.md)                                 | RPC layer trace instrumentation                |
-| [Phase3_taskList.md](./Phase3_taskList.md)                                 | Peer overlay & consensus tracing               |
-| [Phase4_taskList.md](./Phase4_taskList.md)                                 | Transaction lifecycle tracing                  |
-| [Phase5_taskList.md](./Phase5_taskList.md)                                 | Ledger processing & advanced tracing           |
-| [Phase5_IntegrationTest_taskList.md](./Phase5_IntegrationTest_taskList.md) | Observability stack integration tests          |
-| [Phase7_taskList.md](./Phase7_taskList.md)                                 | Native OTel metrics migration                  |
-| [Phase8_taskList.md](./Phase8_taskList.md)                                 | Log-trace correlation                          |
-| [Phase9_taskList.md](./Phase9_taskList.md)                                 | Internal metric instrumentation gap fill       |
-| [Phase10_taskList.md](./Phase10_taskList.md)                               | Synthetic workload generation & validation     |
-| [Phase11_taskList.md](./Phase11_taskList.md)                               | Third-party data collection pipelines (future) |
-
-> **Only Phase 11 is still "future".** Phase 9 ships on
-> `pratik/otel-phase9-metric-gap-fill` (18 task entries, 9.1–9.17 plus 9.7a) and
-> Phase 10 on `pratik/otel-phase10-workload-validation` (7 tasks). Their task
-> lists are present on every branch from those points forward, so a reader on a
-> later branch sees plans that are already implemented, not proposals. Phase 11
-> (13 tasks) has no implementation branch.
-
-> **Note**: Phases 1 and 6 do not have separate task list files. Phase 1 tasks are documented in [06-implementation-phases.md §6.2](./06-implementation-phases.md). Phase 6 tasks are documented in [06-implementation-phases.md §6.7](./06-implementation-phases.md).
-
----
-
-## 8.6 Phase 9–11 Cross-Reference Guide
-
-This guide maps Phase 9–11 content to its location across the documentation.
-
-### Phase 9: Internal Metric Instrumentation Gap Fill
-
-| Content                                           | Location                                                                                                                                                                                                     |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Plan & architecture                               | [06-implementation-phases.md §6.8.2](./06-implementation-phases.md)                                                                                                                                          |
-| Task list (18 entries, 9.1–9.17)                  | [Phase9_taskList.md](./Phase9_taskList.md)                                                                                                                                                                   |
-| Metric definitions                                | [09-data-collection-reference.md §5b](./09-data-collection-reference.md)                                                                                                                                     |
-| New classes: `MetricsRegistry`, `AppMetricGauges` | `include/xrpl/telemetry/MetricsRegistry.h` + `src/libxrpl/telemetry/MetricsRegistry.cpp` (pipeline, counters, histograms) and `src/xrpld/telemetry/AppMetricGauges.h/.cpp` (observable gauges) — **shipped** |
-| New dashboards (4)                                | `fee-market`, `job-queue`, `peer-quality`, `validator-health` — **shipped**                                                                                                                                  |
-| Updated dashboards (2)                            | `node-health`, `rpc-performance`                                                                                                                                                                             |
-| Provisioned alert rules                           | `docker/telemetry/grafana/provisioning/alerting/rules.yaml` — 13 rules in 5 groups ([07 §7.6.2](./07-observability-backends.md))                                                                             |
-
-> **Task numbering**: `Phase9_taskList.md` carries 18 `## Task 9.x` headings —
-> 9.1 through 9.17 plus the inserted 9.7a (`push_metrics.py` parity). The "10
-> tasks" figure in earlier revisions predates 9.7a and 9.11–9.17. Tasks 9.8 and
-> 9.11–9.13 together produce the four new dashboards; Task 9.17 (peer span
-> coverage) is explicitly **deferred to Phase 11**.
-
-**Metric categories**: NodeStore I/O, Cache Hit Rates, TxQ, PerfLog Per-RPC, PerfLog Per-Job, Counted Objects, Fee Escalation & Load Factors.
-
-### Phase 10: Synthetic Workload Generation & Telemetry Validation
-
-| Content              | Location                                                                 |
-| -------------------- | ------------------------------------------------------------------------ |
-| Plan & architecture  | [06-implementation-phases.md §6.8.3](./06-implementation-phases.md)      |
-| Task list (7 tasks)  | [Phase10_taskList.md](./Phase10_taskList.md)                             |
-| Branch               | `pratik/otel-phase10-workload-validation`                                |
-| Validation inventory | [09-data-collection-reference.md §5c](./09-data-collection-reference.md) |
-| Test harness         | `docker/telemetry/docker-compose.workload.yaml` (phase-10 branch)        |
-| CI workflow          | `.github/workflows/telemetry-validation.yml` (phase-10 branch)           |
-
-**Validates** (Phase-10 harness inventory): **40** span types, **67** unique
-required span attributes, **36** metric entries, **14** dashboards, log-trace
-correlation.
-
-> **These are the harness manifests' counts, and two of them lag the code.** The
-> manifests (`docker/telemetry/workload/expected_spans.json`,
-> `expected_metrics.json`) live only on the phase-10 branch. `expected_spans.json`
-> holds 40 span entries against the **41** span-name families the code emits
-> (`rpc.ws_upgrade` has no entry), and its own `total_unique_attributes: 58` field
-> is stale against the 67 attributes its per-span `required_attributes` lists
-> actually name. `expected_metrics.json` asserts 14 dashboard uids against the
-> **15** dashboard JSONs in `docker/telemetry/grafana/dashboards/`;
-> `log-derived-insights` is the unasserted one. The full emitted inventory is in
-> [09-data-collection-reference.md §1.1](./09-data-collection-reference.md#11-complete-span-inventory-41-spans)
-> and [§5c](./09-data-collection-reference.md#validated-telemetry-inventory).
-
-### Phase 11: Third-Party Data Collection Pipelines
-
-| Content                           | Location                                                                 |
-| --------------------------------- | ------------------------------------------------------------------------ |
-| Plan & architecture               | [06-implementation-phases.md §6.8.4](./06-implementation-phases.md)      |
-| Task list (13 tasks)              | [Phase11_taskList.md](./Phase11_taskList.md)                             |
-| External metric definitions (~30) | [09-data-collection-reference.md §5d](./09-data-collection-reference.md) |
-| Custom OTel Collector receiver    | `docker/telemetry/otel-rippled-receiver/` (planned)                      |
-| Prometheus alerting rules (11)    | [09-data-collection-reference.md §5d](./09-data-collection-reference.md) |
-| New dashboards (4)                | Validator Health, Network Topology, Fee Market (External), DEX & AMM     |
-
-> **Two of those names now collide with shipped Phase-9 boards.** Phase 9
-> already ships `validator-health` and `fee-market`, both built from the node's
-> **own** telemetry. The Phase-11 entries are the third-party-data variants
-> (network-wide validator agreement, external fee/DEX feeds via the custom
-> receiver). They need distinct uids, or they will overwrite the Phase-9 boards
-> on provisioning.
-
-**Consumer categories**: Exchanges, Payment Processors, DeFi/AMM, NFT Marketplaces, Analytics Providers, Wallets, Compliance, Academic Researchers, Institutional Custody, CBDC Bridge Operators.
-
----
-
-_Previous: [Observability Backends](./07-observability-backends.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/OpenTelemetryPlan.md

@@ -1,239 +0,0 @@
-# [OpenTelemetry](00-tracing-fundamentals.md) Distributed Tracing Implementation Plan for xrpld
-
-## Executive Summary
-
-> **OTLP** = OpenTelemetry Protocol
-
-This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. The plan addresses the unique challenges of a decentralized peer-to-peer system where trace context must propagate across network boundaries between independent nodes.
-
-### Key Benefits
-
-- **End-to-end transaction visibility**: Track transactions from submission through consensus to ledger inclusion
-- **Consensus round analysis**: Understand timing and behavior of consensus phases across validators
-- **RPC performance insights**: Identify slow handlers and optimize response times
-- **Network topology understanding**: Visualize message propagation patterns between peers
-- **Incident debugging**: Correlate events across distributed nodes during issues
-
-### Estimated Performance Overhead
-
-| Metric        | Overhead   | Notes                                            |
-| ------------- | ---------- | ------------------------------------------------ |
-| CPU           | 1-3%       | Span creation and attribute setting              |
-| Memory        | <10 MB     | SDK statics + batch buffer + worker thread stack |
-| Network       | 10-50 KB/s | Compressed OTLP export to collector              |
-| Latency (p99) | <2%        | With proper sampling configuration               |
-
----
-
-## Document Structure
-
-This implementation plan is organized into modular documents for easier navigation:
-
-<div align="center">
-
-```mermaid
-flowchart TB
-    overview["📋 OpenTelemetryPlan.md<br/>(This Document)"]
-
-    subgraph fundamentals["Fundamentals"]
-        fund["00-tracing-fundamentals.md"]
-    end
-
-    subgraph analysis["Analysis & Design"]
-        arch["01-architecture-analysis.md"]
-        design["02-design-decisions.md"]
-    end
-
-    subgraph impl["Implementation"]
-        strategy["03-implementation-strategy.md"]
-        config["05-configuration-reference.md"]
-    end
-
-    subgraph deploy["Deployment & Planning"]
-        phases["06-implementation-phases.md"]
-        backends["07-observability-backends.md"]
-        appendix["08-appendix.md"]
-        dataref["09-data-collection-reference.md"]
-    end
-
-    overview --> fundamentals
-    overview --> analysis
-    overview --> impl
-    overview --> deploy
-
-    fund --> arch
-    arch --> design
-    design --> strategy
-    strategy --> config
-    config --> phases
-    phases --> backends
-    backends --> appendix
-    appendix --> dataref
-
-    style overview fill:#1b5e20,stroke:#0d3d14,color:#fff,stroke-width:2px
-    style fundamentals fill:#00695c,stroke:#004d40,color:#fff
-    style fund fill:#00695c,stroke:#004d40,color:#fff
-    style analysis fill:#0d47a1,stroke:#082f6a,color:#fff
-    style impl fill:#bf360c,stroke:#8c2809,color:#fff
-    style deploy fill:#4a148c,stroke:#2e0d57,color:#fff
-    style arch fill:#0d47a1,stroke:#082f6a,color:#fff
-    style design fill:#0d47a1,stroke:#082f6a,color:#fff
-    style strategy fill:#bf360c,stroke:#8c2809,color:#fff
-    style config fill:#bf360c,stroke:#8c2809,color:#fff
-    style phases fill:#4a148c,stroke:#2e0d57,color:#fff
-    style backends fill:#4a148c,stroke:#2e0d57,color:#fff
-    style appendix fill:#4a148c,stroke:#2e0d57,color:#fff
-    style dataref fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-</div>
-
----
-
-## Table of Contents
-
-| Section | Document                                                       | Description                                                            |
-| ------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **0**   | [Tracing Fundamentals](./00-tracing-fundamentals.md)           | Distributed tracing concepts, span relationships, context propagation  |
-| **1**   | [Architecture Analysis](./01-architecture-analysis.md)         | xrpld component analysis, trace points, instrumentation priorities     |
-| **2**   | [Design Decisions](./02-design-decisions.md)                   | SDK selection, exporters, span naming, attributes, context propagation |
-| **3**   | [Implementation Strategy](./03-implementation-strategy.md)     | Directory structure, key principles, performance optimization          |
-| **5**   | [Configuration Reference](./05-configuration-reference.md)     | xrpld config, CMake integration, Collector configurations              |
-| **6**   | [Implementation Phases](./06-implementation-phases.md)         | 11-phase timeline, tasks, risks, success metrics                       |
-| **7**   | [Observability Backends](./07-observability-backends.md)       | Backend selection guide and production architecture                    |
-| **8**   | [Appendix](./08-appendix.md)                                   | Glossary, references, version history                                  |
-| **9**   | [Data Collection Reference](./09-data-collection-reference.md) | Complete inventory of spans, attributes, metrics, and dashboards       |
-
-> Note there is no document 4: `04-code-samples.md` was removed during the
-> rollout, and the numbering was left as-is rather than renumbering every
-> cross-reference in the chain.
-
----
-
-## 0. Tracing Fundamentals
-
-This document introduces distributed tracing concepts for readers unfamiliar with the domain. It covers what traces and spans are, how parent-child and follows-from relationships model causality, how context propagates across service boundaries, and how sampling controls data volume. It also maps these concepts to xrpld-specific scenarios like transaction relay and consensus.
-
-➡️ **[Read Tracing Fundamentals](./00-tracing-fundamentals.md)**
-
----
-
-## 1. Architecture Analysis
-
-> **WS** = WebSocket | **TxQ** = Transaction Queue
-
-The xrpld node consists of several key components that require instrumentation for comprehensive distributed tracing. The main areas include the RPC server (HTTP/WebSocket), Overlay P2P network, Consensus mechanism (RCLConsensus), JobQueue for async task execution, PathFinding, Transaction Queue (TxQ), fee escalation (LoadManager), ledger acquisition, validator management, and existing observability infrastructure (PerfLog, Insight/StatsD, Journal logging).
-
-Key trace points span across transaction submission via RPC, peer-to-peer message propagation, consensus round execution, ledger building, path computation, transaction queue behavior, fee escalation, and validator health. The implementation prioritizes high-value, low-risk components first: RPC handlers provide immediate value with minimal risk, while consensus tracing requires careful implementation to avoid timing impacts.
-
-➡️ **[Read full Architecture Analysis](./01-architecture-analysis.md)**
-
----
-
-## 2. Design Decisions
-
-> **OTLP** = OpenTelemetry Protocol | **CNCF** = Cloud Native Computing Foundation
-
-The OpenTelemetry C++ SDK is selected for its CNCF backing, active development, and native performance characteristics. Traces are exported via OTLP/HTTP to an OpenTelemetry Collector, which provides flexible routing and sampling. OTLP/gRPC is planned future work (see design decisions §2.2.2).
-
-Span naming follows a hierarchical `<component>.<operation>` convention (e.g., `rpc.command.server_info`, `tx.process`, `consensus.round`). Context propagation uses W3C Trace Context headers for HTTP and embedded Protocol Buffer fields for P2P messages. The implementation coexists with existing PerfLog and Insight observability systems through correlation IDs.
-
-**Data Collection & Privacy**: Telemetry collects only operational metadata (timing, counts, hashes, public identifiers) — never sensitive content (private keys, balances, amounts, raw payloads). Account addresses are public ledger identifiers and are emitted raw; there is no redaction setting and no collector-side hashing. Trace volume is _not_ reduced on the node (head sampling is fixed at 100%); reduction, where wanted, is a collector-side tail-sampling decision. Node operators control which subsystems are traced via the `[telemetry]` per-component toggles.
-
-➡️ **[Read full Design Decisions](./02-design-decisions.md)**
-
----
-
-## 3. Implementation Strategy
-
-The telemetry code is organized under `include/xrpl/telemetry/` for headers, `src/libxrpl/telemetry/` for implementation, and `src/xrpld/telemetry/` for the native-metrics module added in Phases 7 and 9. Key principles include RAII-based span management via `SpanGuard` (with `discard()` for dropping unwanted spans), a `FilteringSpanProcessor` that intercepts `OnEnd()` to prevent discarded spans from entering the export pipeline, conditional compilation behind the `XRPL_ENABLE_TELEMETRY` compile definition (set by the CMake `telemetry` option, which defaults to **ON** — build it out with `-Dtelemetry=OFF`), and minimal runtime overhead through batch processing.
-
-Performance optimization strategies include head sampling fixed at 100% (intentionally not configurable, so trace keep/drop decisions stay coherent across nodes), optional tail-based sampling at the collector to reduce stored volume (not enabled in the base stack — the only shipped policy is a 0.5% probabilistic one in the Grafana Cloud overlay), batch export to reduce network overhead, and conditional instrumentation that compiles to no-ops when disabled.
-
-➡️ **[Read full Implementation Strategy](./03-implementation-strategy.md)**
-
----
-
-## 5. Configuration Reference
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring
-
-Configuration is handled through the `[telemetry]` section in `xrpld.cfg` with options for enabling/disabling, TLS/mTLS, batch tuning, and component-level filtering. Exporter selection is _not_ configurable — OTLP/HTTP is the only transport. Head sampling is fixed at 1.0 (not operator-configurable); volume reduction is done by tail sampling in the collector. CMake integration uses the `telemetry` option (default **ON**) for compile-time control.
-
-Endpoints are spread across **three** keys in two sections, not one "traces and metrics" pair:
-
-| Signal                                               | Key                            | Default                            | Source                                              |
-| ---------------------------------------------------- | ------------------------------ | ---------------------------------- | --------------------------------------------------- |
-| Traces                                               | `[telemetry] endpoint`         | `http://localhost:4318/v1/traces`  | `TelemetryConfig.cpp:36,61`                         |
-| Native metrics (`XRPL_METRIC_*` / `MetricsRegistry`) | `[telemetry] metrics_endpoint` | `http://localhost:4318/v1/metrics` | `makeMetricsRegistryOptions()` in `Application.cpp` |
-| `beast::insight` metrics (`server=otel`)             | `[insight] endpoint`           | `http://localhost:4318/v1/metrics` | `CollectorManager.cpp:50`                           |
-
-`[telemetry]` itself has exactly **one** `endpoint` key, and it is traces-only.
-
-The repo ships one collector config (`docker/telemetry/otel-collector-config.yaml`, three pipelines: traces, metrics, logs) plus a Grafana Cloud overlay that adds 0.5% tail sampling. A six-service Docker Compose stack — collector, Tempo, Loki, Prometheus, Grafana, renderer — gives a complete local environment.
-
-➡️ **[View full Configuration Reference](./05-configuration-reference.md)**
-
----
-
-## 6. Implementation Phases
-
-The plan was originally scoped at **13 weeks across 8 phases** — the table below
-is that original scope. As delivered it grew to **11 phases through week 20**;
-Phases 9-11 were added after the original plan was written. See
-[06-implementation-phases.md §6.12.6](./06-implementation-phases.md) for the
-authoritative per-phase status, and treat the eight rows below as the
-originally-planned subset rather than the current timeline:
-
-| Phase | Duration    | Focus                 | Key Deliverables                                          |
-| ----- | ----------- | --------------------- | --------------------------------------------------------- |
-| 1     | Weeks 1-2   | Core Infrastructure   | SDK integration, Telemetry interface, Configuration       |
-| 2     | Weeks 3-4   | RPC Tracing           | HTTP context extraction, Handler instrumentation          |
-| 3     | Weeks 5-6   | Transaction Tracing   | Protocol Buffer context, Relay propagation                |
-| 4     | Weeks 7-8   | Consensus Tracing     | Round spans, Proposal/validation tracing                  |
-| 5     | Week 9      | Documentation         | Runbook, Dashboards, Training                             |
-| 6     | Week 10     | StatsD Metrics Bridge | OTel Collector StatsD receiver, 3 Grafana dashboards      |
-| 7     | Weeks 11-12 | Native OTel Metrics   | OTelCollector impl, OTLP metrics export (StatsD retained) |
-| 8     | Week 13     | Log-Trace Correlation | trace_id in logs, Loki ingestion, Tempo↔Loki linking      |
-
-Delivered beyond the original scope: **Phase 9** (weeks 14-15, internal metric
-instrumentation gap fill), **Phase 10** (weeks 16-17, synthetic workload
-generation and telemetry validation) and **Phase 11** (weeks 18-20, third-party
-data-collection pipelines).
-
-**Total Effort**: 65.1 developer-days with 2 developers, for the eight
-originally-planned phases only.
-
-➡️ **[View full Implementation Phases](./06-implementation-phases.md)**
-
----
-
-## 7. Observability Backends
-
-> **APM** = Application Performance Monitoring | **GCS** = Google Cloud Storage
-
-Grafana Tempo is recommended for all environments due to its cost-effectiveness and Grafana integration, and it is the only backend this repo provisions. Elastic APM remains a reasonable choice for organizations with existing Elastic infrastructure, but nothing here configures it.
-
-The recommended production architecture uses a gateway collector pattern with regional collectors performing tail-based sampling, routing traces to multiple backends (Tempo for primary storage, Elastic for log correlation, S3/GCS for long-term archive). Note that several subsections of doc 7 predate the shipped dashboards and alert rules and are marked superseded in place, pointing at [09-data-collection-reference.md](./09-data-collection-reference.md) and `docs/telemetry-runbook.md`.
-
-➡️ **[View Observability Backend Recommendations](./07-observability-backends.md)**
-
----
-
-## 8. Appendix
-
-The appendix contains a glossary of OpenTelemetry and xrpld-specific terms, references to external documentation and specifications, version history for this implementation plan, and a complete document index.
-
-➡️ **[View Appendix](./08-appendix.md)**
-
----
-
-## 9. Data Collection Reference
-
-A single-source-of-truth reference documenting every piece of telemetry data collected by xrpld: the OpenTelemetry span inventory with per-span attributes, the `beast::insight` and native `XRPL_METRIC_*` instruments (gauges, counters, histograms, overlay traffic), the SpanMetrics-derived Prometheus metrics, and the **15** Grafana dashboards. Includes Tempo search guides and Prometheus query examples. Consult that document rather than this index for any count — it tracks the code, this summary does not.
-
-➡️ **[View Data Collection Reference](./09-data-collection-reference.md)**
-
----
-
-_This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. For detailed information on any section, follow the links to the corresponding sub-documents._

OpenTelemetryPlan/Phase10_taskList.md

@@ -1,309 +0,0 @@
-# Phase 10: Synthetic Workload Generation & Telemetry Validation — Task List
-
-> **Status**: Future Enhancement
->
-> **Goal**: Build tools that generate realistic XRPL traffic to validate the full Phases 1-9 telemetry stack end-to-end — all spans, attributes, metrics, dashboards, and log-trace correlation — under controlled load.
->
-> **Scope**: Python/shell test harness + multi-node docker-compose environment + automated validation scripts + performance benchmarks.
->
-> **Branch**: `pratik/otel-phase10-workload-validation` (from `pratik/otel-phase9-metric-gap-fill`)
->
-> **Depends on**: Phase 9 (internal metric gap fill) — validates the full metric surface
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 10 plan: motivation, architecture, exit criteria (§6.8.3) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Defines the full inventory of spans/metrics to validate         |
-| [Phase9_taskList.md](./Phase9_taskList.md)                           | Prerequisite — all internal metrics must be emitting            |
-
-### Why This Phase Exists
-
-Before Phases 1-9 can be considered production-ready, we need proof that:
-
-1. Every emitted span fires with its required attributes under real transaction
-   workloads — the harness derives the span and attribute totals from
-   `expected_spans.json`, so no fixed "16 spans / 22 attributes" figure applies
-2. All 255+ StatsD metrics + ~50 Phase 9 metrics appear in Prometheus with non-zero values
-3. Log-trace correlation (Phase 8) produces clickable trace_id links in Loki
-4. The 14 harness-asserted Grafana dashboards render meaningful data (no empty
-   panels); 15 are on disk
-5. Performance overhead stays within bounds (< 3% CPU, < 5MB memory)
-6. The telemetry stack survives sustained load without data loss or queue backpressure
-
----
-
-## Task 10.1: Multi-Node Test Harness
-
-**Objective**: Create a docker-compose environment with 3-5 validator nodes that produces real consensus rounds.
-
-**What to do**:
-
-- Create `docker/telemetry/docker-compose.workload.yaml` — **as shipped this file
-  holds only the observability backend**: `otel-collector`, `tempo`,
-  `prometheus`, `loki`, `grafana`. It contains **no xrpld services**.
-  - Shared network (`workload-net`) with service discovery
-
-- The 5 validators are **native `xrpld` processes**, not containers.
-  `docker/telemetry/workload/run-full-validation.sh` (`NUM_NODES=5`) generates
-  keys, writes a per-node `xrpld.cfg`, and launches each node on
-  `127.0.0.1` with sequential RPC / WS / peer ports. Each node:
-  - Gets its validator key from `generate-validator-keys.sh`
-  - Lists the other 4 nodes in `ips_fixed`
-  - Has all telemetry enabled: `[telemetry] enabled=1`, `[insight] server=otel`
-  - Enables all trace categories including `trace_peer=1`
-  - Writes logs to a file tailed by the OTel Collector filelog receiver
-
-- ❌ **`make telemetry-workload-up` / `make telemetry-workload-down` were never
-  implemented.** There is no `Makefile` anywhere in the repository. The entry
-  point is `run-full-validation.sh` (with `--profile`, `--nodes`,
-  `--skip-loki`, `--skip-regression`, `--with-benchmark`). The node-count flag is
-  spelled `--nodes`, **not** `--num-nodes` — `run-full-validation.sh:80` (usage)
-  and `:100` (the `case` arm). `NUM_NODES` is the internal shell variable it
-  assigns to.
-
-**Key files**:
-
-- New: `docker/telemetry/docker-compose.workload.yaml` (backend only)
-- New: `docker/telemetry/workload/generate-validator-keys.sh`
-- New: `docker/telemetry/workload/run-full-validation.sh` — writes each node's
-  cfg **inline** via a heredoc at `run-full-validation.sh:242`
-  (`cat >"$NODE_DIR/xrpld.cfg" <<EOCFG`)
-- New: `docker/telemetry/workload/xrpld-validator.cfg.template` (96 lines) — it
-  **was** created and is tracked on the Phase 10 branch, but it is **unused**:
-  nothing reads it, and its `{{NODE_INDEX}}` / `{{RPC_PORT}}` / `{{OTEL_ENDPOINT}}`
-  placeholders are never substituted, because the inline heredoc above supersedes
-  it. Either wire the script to the template or delete the template — keeping both
-  guarantees they drift.
-
----
-
-## Task 10.2: RPC Load Generator
-
-**Objective**: Configurable tool that fires all traced RPC commands at controlled rates.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/rpc_load_generator.py`:
-  - Connects to one or more xrpld WebSocket endpoints
-  - Fires all RPC commands that have trace spans: `server_info`, `ledger`, `tx`, `account_info`, `account_lines`, `fee`, `submit`, etc.
-  - Configurable parameters: rate (RPS), duration, command distribution weights
-  - Injects `traceparent` HTTP headers to test W3C context propagation
-  - Logs progress and errors to stdout
-
-- Command distribution should match realistic production ratios:
-  - 40% `server_info` / `fee` (health checks)
-  - 30% `account_info` / `account_lines` / `account_objects` (wallet queries)
-  - 15% `ledger` / `ledger_data` (explorer queries)
-  - 10% `tx` / `account_tx` (transaction lookups)
-  - 5% `book_offers` / `amm_info` (DEX queries)
-
-**Key files**:
-
-- New: `docker/telemetry/workload/rpc_load_generator.py`
-- New: `docker/telemetry/workload/requirements.txt`
-
----
-
-## Task 10.3: Transaction Submitter
-
-**Objective**: Generate diverse transaction types to exercise `tx.*` and `ledger.*` spans.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/tx_submitter.py`:
-  - Pre-funds test accounts from genesis account
-  - Submits a mix of transaction types:
-    - `Payment` (XRP and issued currencies) — exercises `tx.process`, `tx.apply`
-    - `OfferCreate` / `OfferCancel` — DEX activity
-    - `TrustSet` — trust line creation for issued currencies
-    - `NFTokenMint` / `NFTokenCreateOffer` / `NFTokenAcceptOffer` — NFT activity
-    - `EscrowCreate` / `EscrowFinish` — escrow lifecycle
-    - `AMMCreate` / `AMMDeposit` / `AMMWithdraw` — AMM pool operations (if amendment enabled)
-  - Configurable: TPS target, transaction mix weights, duration
-  - Monitors submission results and tracks success/failure rates
-
-- The transaction mix ensures the telemetry captures the full range of ledger activity that third parties care about.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/tx_submitter.py`
-- New: `docker/telemetry/workload/test_accounts.json` (pre-generated keypairs)
-
----
-
-## Task 10.4: Telemetry Validation Suite
-
-**Objective**: Automated scripts that verify all expected telemetry data exists after a workload run.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/validate_telemetry.py`:
-
-  **Span validation** (queries Tempo API):
-  - Assert every required span name in `expected_spans.json` appears in traces.
-    Conditional spans — `grpc.*`, `ledger.acquire`, `txq.*`,
-    `consensus.mode_change`, `rpc.process` — are marked `optional` and skipped
-    when the workload does not exercise them.
-  - Assert each span has its required attributes (bare/underscore keys; dotted
-    `xrpl.*` is reserved for resource attributes)
-  - Assert parent-child relationships are correct. The two live RPC trees are:
-    - HTTP: `rpc.http_request` -> `rpc.process` -> `rpc.command.*`
-    - WebSocket: `rpc.ws_message` -> `rpc.command.*` — **there is no
-      `rpc.process` on the WS path**. `rpc.process` is created only in
-      `ServerHandler::processRequest()` (`ServerHandler.cpp:718`), reached from
-      `processSession(Session, coro)`, i.e. HTTP only. Under WS-only load
-      `rpc.process` never appears, and `rpc.command.*` parents directly to
-      `rpc.ws_message`.
-  - Assert span durations are reasonable (> 0, < 60s)
-
-  **Metric validation** (queries Prometheus API):
-  - Assert all SpanMetrics-derived metrics are non-zero: `span_calls_total`,
-    `span_duration_milliseconds_bucket` (the connector's `namespace` is `span`,
-    not `traces_span_metrics` — `otel-collector-config.yaml:113-114`)
-  - Assert the insight-sourced metrics are non-zero: `ledgermaster_validated_ledger_age`,
-    `peer_finder_active_{inbound,outbound}_peers`, etc. — all lowercase, no
-    `xrpld_` prefix (`77f35c03db` removed the prefix and lowercased names)
-  - Assert all Phase 9 metrics are non-zero: `nodestore_state`, `cache_metrics`,
-    `txq_metrics`, `rpc_method_{started,finished,errored}_total`, `object_count`,
-    `load_factor_metrics`
-  - Assert metric label cardinality is within bounds
-
-  **Log-trace correlation validation** (queries Loki API):
-  - Assert logs contain `trace_id=` and `span_id=` fields
-  - Pick a random trace_id from Tempo → query Loki for matching logs → assert results exist
-  - Assert Grafana derived field links are functional
-
-  **Dashboard validation**:
-  - For each dashboard, query the dashboard API and assert no panels show "No
-    data". There are **15 dashboards on disk**; the harness asserts **14** —
-    `log-derived-insights` is provisioned but unasserted.
-
-- Output: JSON report with pass/fail per check, suitable for CI.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/validate_telemetry.py`
-- New: `docker/telemetry/workload/expected_spans.json` (span inventory for validation)
-- New: `docker/telemetry/workload/expected_metrics.json` (metric inventory for validation)
-
----
-
-## Task 10.5: Performance Benchmark Suite
-
-**Objective**: Measure CPU/memory/latency overhead of the telemetry stack.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/benchmark.sh`:
-  - **Baseline run**: Start cluster with `[telemetry] enabled=0`, run transaction workload for 5 minutes, record metrics
-  - **Telemetry run**: Start cluster with full telemetry enabled, run identical workload, record metrics
-  - **Comparison**: Calculate deltas for:
-    - CPU usage (per-node average)
-    - Memory RSS (per-node peak)
-    - RPC p99 latency
-    - Transaction throughput (TPS)
-    - Consensus round time p95
-    - Ledger close time p95
-
-- Output: Markdown table comparing baseline vs. telemetry, with pass/fail against targets:
-  - CPU overhead < 3%
-  - Memory overhead < 5MB
-  - RPC latency impact < 2ms p99
-  - Throughput impact < 5%
-  - Consensus impact < 1%
-
-- Store results in `docker/telemetry/workload/benchmark-results/` for historical tracking.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/benchmark.sh`
-- New: `docker/telemetry/workload/collect_system_metrics.sh`
-
----
-
-## Task 10.6: CI Integration
-
-**Objective**: Wire the validation suite into CI for regression detection.
-
-**What to do**:
-
-- Create a CI workflow (GitHub Actions or equivalent) that:
-  1. Builds xrpld with `-DXRPL_ENABLE_TELEMETRY=ON`
-  2. Starts the multi-node workload harness
-  3. Runs the RPC load generator + transaction submitter for 2 minutes
-  4. Runs the validation suite
-  5. Runs the benchmark suite
-  6. Fails the build if any validation check fails or benchmark exceeds thresholds
-  7. Archives the validation report and benchmark results as artifacts
-
-- This should be a separate workflow (not part of the main CI), triggered manually or on telemetry-related branch changes.
-
-**Key files**:
-
-- New: `.github/workflows/telemetry-validation.yml`
-- New: `docker/telemetry/workload/run-full-validation.sh` (orchestrator script)
-
----
-
-## Task 10.7: Documentation
-
-**Objective**: Document the workload tools and validation process.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/README.md`:
-  - Quick start guide for running workload harness
-  - Configuration options for load generator and tx submitter
-  - How to read validation reports
-  - How to run benchmarks and interpret results
-
-- Update `docs/telemetry-runbook.md`:
-  - Add "Validating Telemetry Stack" section
-  - Add "Performance Benchmarking" section
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add "Validation" section with expected metric/span counts
-
----
-
-## Exit Criteria — Delivered in PR #6519
-
-- [x] 5-node validator cluster starts and reaches consensus — as native `xrpld`
-      processes driven by `run-full-validation.sh` (`NUM_NODES=5`), not from
-      docker-compose
-- [x] RPC load generator fires all traced RPC commands at configurable rates
-- [x] Transaction submitter generates 6+ transaction types at configurable TPS
-- [x] Validation suite confirms the full span / attribute / metric inventory
-      (totals computed dynamically from `expected_spans.json` /
-      `expected_metrics.json`)
-- [x] Log-trace correlation validated end-to-end (Loki <-> Tempo) — implemented,
-      and gated in CI: the workflow passes no `--skip-loki`, so
-      `validate_telemetry.py` builds and runs both log-correlation checks
-- [x] All 14 harness-asserted Grafana dashboards render data (no empty panels);
-      15 on disk, `log-derived-insights` unasserted
-- [x] Overhead benchmark (`benchmark.sh`) measures telemetry-off vs telemetry-on
-      deltas
-- [ ] Benchmark shows < 3% CPU overhead, < 5MB memory overhead — needs a
-      measured run
-- [x] CI workflow runs validation on telemetry branch changes
-- [x] Validation report output is CI-parseable (JSON with exit codes)
-- [x] OTel-driven regression gate captures per-span and per-job timings from
-      Prometheus and compares against a committed baseline. Per-RPC timings are
-      **not** gated: `regression-metrics.json` defines only `spans` and
-      `job_queue` groups (FU-4).
-
-## Follow-up Work (tracked in separate PRs)
-
-- [ ] FU-2: Automate baseline persistence across CI runs (artifact uploaded
-      on merge to `develop`, downloaded on PR runs). Current mechanism
-      requires a manual baseline-refresh PR.
-- [ ] FU-4: Replace the proxy measurements in `benchmark.sh` (wall-clock curl
-      p99, ledger-cadence-as-TPS, ledger-cadence-as-consensus-p95) with
-      PromQL quantile queries from the same pipeline the regression gate uses,
-      and add an `rpc_methods` group to `regression-metrics.json` plus a
-      `defaults.rpc_method` block to `regression-thresholds.json` (without both,
-      any `rpc.*` metric resolves to "no threshold configured" and never gates).
-- [ ] FU-6: Grafana dashboard plotting historical baseline values keyed by
-      commit SHA, for triaging noisy regressions.

OpenTelemetryPlan/Phase11_taskList.md

@@ -1,664 +0,0 @@
-# Phase 11: Third-Party Data Collection Pipelines — Task List
-
-> **Status**: Not started — 0 of 13 tasks complete (`grep -c '^## Task 11\.'` = 13:
-> Tasks 11.1 through 11.13). Verified against the tree:
-> no `.go` files exist anywhere, `docker/telemetry/otel-rippled-receiver/` does
-> not exist, `docker/telemetry/prometheus/` does not exist (so no
-> `prometheus/rippled-alerts.yml`), and no `network-topology` / `dex-amm`
-> dashboards are present under `docker/telemetry/grafana/dashboards/`. **No Phase 11 work has
-> been done, so no task box below may be ticked.**
->
-> One **prerequisite** box is ticked, and only one: Task 11.12's
-> "`state_tracking` gauge implemented (Task 7.12)". That is an upstream
-> dependency satisfied by Phase 7/9 code, not Phase 11 work — see the citation
-> there.
->
-> **Goal**: Build a custom OTel Collector receiver that periodically polls xrpld's admin RPCs and exports structured metrics for external consumers — making all XRPL health, validator, peer, fee, and DEX data available as Prometheus/OTLP metrics without xrpld code changes.
->
-> **Scope**: Go-based OTel Collector receiver plugin + Grafana dashboards + Prometheus alerting rules.
->
-> **Branch**: `pratik/otel-phase11-third-party-collection` (from `pratik/otel-phase10-workload-validation`)
->
-> **Depends on**: Phase 10 (validation harness for testing the new receiver)
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 11 plan: motivation, architecture, exit criteria (§6.8.4) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Defines full metric inventory including third-party metrics     |
-| [Phase10_taskList.md](./Phase10_taskList.md)                         | Prerequisite — validation harness for testing                   |
-
-### Third-Party Consumer Gap Analysis
-
-This phase addresses the cross-cutting gap identified during research: **xrpld has no native Prometheus/OTLP metrics export for data accessible only via RPC**. Every consumer (exchanges, payment processors, analytics providers, validators, researchers, compliance firms, custodians) must build custom JSON-RPC polling and conversion. This receiver centralizes that work.
-
-| Consumer Category          | Data Unlocked by This Phase                                        |
-| -------------------------- | ------------------------------------------------------------------ |
-| **Exchanges**              | Real-time fee estimates, TxQ capacity, server health scores        |
-| **Payment Processors**     | Settlement latency percentiles, corridor health, path availability |
-| **Analytics Providers**    | Validator metrics, network topology, amendment voting status       |
-| **DeFi / AMM**             | AMM pool TVL, DEX order book depth, trade volumes                  |
-| **Validators / Operators** | Per-peer latency, version distribution, UNL health, alerting       |
-| **Compliance**             | Transaction volume trends, network growth metrics                  |
-| **Academic Researchers**   | Consensus performance time-series, decentralization metrics        |
-| **CBDC / Tokenization**    | Token supply tracking, trust line adoption, freeze status          |
-| **Institutional Custody**  | Multi-sig status, escrow tracking, reserve calculations            |
-| **Wallet Providers**       | Server health for node selection, fee prediction data              |
-
----
-
-## Task 11.1: OTel Collector Receiver Scaffold
-
-**Objective**: Create the Go project structure for a custom OTel Collector receiver that polls xrpld JSON-RPC.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-rippled-receiver/`:
-  - `receiver.go` — implements `receiver.Metrics` interface
-  - `config.go` — configuration struct (endpoint, poll interval, enabled RPCs)
-  - `factory.go` — receiver factory registration
-  - `go.mod` / `go.sum` — Go module with OTel Collector SDK dependency
-
-- Configuration model:
-
-  ```yaml
-  xrpld_receiver:
-    endpoint: "http://localhost:5005" # xrpld admin RPC
-    poll_interval: 30s # how often to poll
-    enabled_collectors:
-      - server_info
-      - get_counts
-      - fee
-      - peers
-      - validators
-      - feature
-      - server_state
-    amm_pools: [] # optional: AMM pool IDs to track
-    book_offers_pairs: [] # optional: currency pairs for DEX depth
-  ```
-
-- Build a custom OTel Collector binary that includes this receiver alongside the standard receivers.
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/receiver.go`
-- New: `docker/telemetry/otel-rippled-receiver/config.go`
-- New: `docker/telemetry/otel-rippled-receiver/factory.go`
-- New: `docker/telemetry/otel-rippled-receiver/go.mod`
-- New: `docker/telemetry/otel-rippled-receiver/Dockerfile`
-
----
-
-## Task 11.2: server_info / server_state Collector
-
-**Objective**: Poll `server_info` and `server_state` and export all fields as OTel metrics.
-
-**What to do**:
-
-- Implement `serverInfoCollector` that calls `server_info` (admin) and extracts:
-
-  **Node Health Gauges:**
-  - `xrpl_server_state` (enum → int: disconnected=0, connected=1, syncing=2, tracking=3, full=4, proposing=5)
-  - `xrpl_server_state_duration_seconds`
-  - `xrpl_uptime_seconds`
-  - `xrpl_io_latency_ms`
-  - `xrpl_amendment_blocked` (0 or 1)
-  - `xrpl_peers_count`
-  - `xrpl_peer_disconnects_total`
-  - `xrpl_peer_disconnects_resources_total`
-  - `xrpl_jq_trans_overflow_total`
-
-  **Consensus Gauges:**
-  - `xrpl_last_close_proposers`
-  - `xrpl_last_close_converge_time_seconds`
-  - `xrpl_validation_quorum`
-
-  **Ledger Gauges:**
-  - `xrpl_validated_ledger_seq`
-  - `xrpl_validated_ledger_age_seconds`
-  - `xrpl_validated_ledger_base_fee_drops`
-  - `xrpl_validated_ledger_reserve_base_drops`
-  - `xrpl_validated_ledger_reserve_inc_drops`
-  - `xrpl_close_time_offset_seconds` (0 when absent)
-
-  **Load Factor Gauges:**
-  - `xrpl_load_factor`
-  - `xrpl_load_factor_server`
-  - `xrpl_load_factor_fee_escalation`
-  - `xrpl_load_factor_fee_queue`
-  - `xrpl_load_factor_local`
-  - `xrpl_load_factor_net`
-  - `xrpl_load_factor_cluster`
-
-  **State Accounting Gauges** (per state: disconnected, connected, syncing, tracking, full):
-  - `xrpl_state_duration_seconds{state="<name>"}`
-  - `xrpl_state_transitions_total{state="<name>"}`
-
-  **Validator Info** (when node is a validator):
-  - `xrpl_validator_list_count`
-  - `xrpl_validator_list_expiration_seconds` (epoch)
-  - `xrpl_validator_list_active` (0 or 1)
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/server_info.go`
-
----
-
-## Task 11.3: get_counts Collector
-
-**Objective**: Poll `get_counts` and export internal object counts and NodeStore stats.
-
-**What to do**:
-
-- Implement `getCountsCollector`:
-
-  **Database Gauges:**
-  - `xrpl_db_size_kb{db="total"}`, `xrpl_db_size_kb{db="ledger"}`, `xrpl_db_size_kb{db="transaction"}`
-
-  **NodeStore Gauges:**
-  - `xrpl_nodestore_reads_total`, `xrpl_nodestore_reads_hit`, `xrpl_nodestore_writes_total`
-  - `xrpl_nodestore_read_bytes`, `xrpl_nodestore_written_bytes`
-  - `xrpl_nodestore_read_duration_us`, `xrpl_nodestore_write_load`
-  - `xrpl_nodestore_read_queue`, `xrpl_nodestore_read_threads_running`
-
-  **Cache Gauges:**
-  - `xrpl_cache_hit_rate{cache="SLE"}`, `xrpl_cache_hit_rate{cache="ledger"}`, `xrpl_cache_hit_rate{cache="accepted_ledger"}`
-  - `xrpl_cache_size{cache="treenode"}`, `xrpl_cache_size{cache="fullbelow"}`, `xrpl_cache_size{cache="accepted_ledger"}`
-
-  **Object Count Gauges:**
-  - `xrpl_object_count{type="<name>"}` for each counted object type (Transaction, Ledger, NodeObject, STTx, STLedgerEntry, InboundLedger, Pathfinder, etc.)
-
-  **Rates:**
-  - `xrpl_historical_fetch_per_minute`
-  - `xrpl_local_txs`
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/get_counts.go`
-
----
-
-## Task 11.4: Peer Topology Collector
-
-**Objective**: Poll `peers` and export per-peer and aggregate network metrics.
-
-**What to do**:
-
-- Implement `peersCollector`:
-
-  **Aggregate Gauges:**
-  - `xrpl_peers_inbound_count`
-  - `xrpl_peers_outbound_count`
-  - `xrpl_peers_cluster_count`
-
-  **Per-Peer Gauges** (with labels `peer_key` truncated to 8 chars for cardinality control):
-  - `xrpl_peer_latency_ms{peer="<key>", version="<ver>", inbound="<bool>"}`
-  - `xrpl_peer_uptime_seconds{peer="<key>"}`
-  - `xrpl_peer_load{peer="<key>"}`
-
-  **Distribution Gauges** (aggregated across all peers):
-  - `xrpl_peer_latency_p50_ms`, `xrpl_peer_latency_p95_ms`, `xrpl_peer_latency_p99_ms`
-  - `xrpl_peer_version_count{version="<semver>"}` — count of peers per software version
-
-  **Tracking Status:**
-  - `xrpl_peer_diverged_count` — peers with `track=diverged`
-  - `xrpl_peer_unknown_count` — peers with `track=unknown`
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/peers.go`
-
-**Cardinality note**: Per-peer metrics use truncated keys. For large peer sets (50+), the aggregate distribution gauges are preferred over per-peer labels.
-
----
-
-## Task 11.5: Validator & Amendment Collector
-
-**Objective**: Poll `validators` and `feature` to export validator health and amendment voting status.
-
-**What to do**:
-
-- Implement `validatorCollector`:
-
-  **From `validators` RPC:**
-  - `xrpl_trusted_validators_count`
-  - `xrpl_validator_signing` (0 or 1 — whether local validator is signing)
-
-  **From `feature` RPC:**
-  - `xrpl_amendment_enabled_count` — total enabled amendments
-  - `xrpl_amendment_majority_count` — amendments with majority but not yet enabled
-  - `xrpl_amendment_vetoed_count` — locally vetoed amendments
-  - `xrpl_amendment_unsupported_majority` (0 or 1) — any unsupported amendment has majority (critical alert)
-
-  **Per-amendment with majority** (limited cardinality — only amendments with `majority` set):
-  - `xrpl_amendment_majority_time{name="<amendment>"}` — epoch time when majority was gained
-  - `xrpl_amendment_votes{name="<amendment>"}` — current vote count
-  - `xrpl_amendment_threshold{name="<amendment>"}` — votes needed
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/validators.go`
-
----
-
-## Task 11.6: Fee & TxQ Collector
-
-**Objective**: Poll `fee` RPC and export real-time fee market data.
-
-**What to do**:
-
-- Implement `feeCollector` that calls the public `fee` RPC:
-
-  **Fee Level Gauges:**
-  - `xrpl_fee_current_ledger_size` — transactions in current open ledger
-  - `xrpl_fee_expected_ledger_size` — expected transactions at close
-  - `xrpl_fee_max_queue_size` — maximum transaction queue size
-  - `xrpl_fee_open_ledger_fee_drops` — minimum fee for open ledger inclusion
-  - `xrpl_fee_median_fee_drops` — median fee level
-  - `xrpl_fee_minimum_fee_drops` — base reference fee
-  - `xrpl_fee_queue_size` — current queue depth
-
-- This overlaps with Phase 9's internal TxQ metrics but provides an external-only collection path that doesn't require xrpld code changes.
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/fee.go`
-
----
-
-## Task 11.7: DEX & AMM Collector (Optional)
-
-**Objective**: Periodically poll configured AMM pools and order book pairs for DeFi metrics.
-
-**What to do**:
-
-- Implement `dexCollector` (enabled only when `amm_pools` or `book_offers_pairs` are configured):
-
-  **AMM Pool Gauges** (per configured pool):
-  - `xrpl_amm_reserve{pool="<id>", asset="<currency>"}` — pool reserve amount
-  - `xrpl_amm_lp_token_supply{pool="<id>"}` — outstanding LP tokens
-  - `xrpl_amm_trading_fee{pool="<id>"}` — pool trading fee (basis points)
-  - `xrpl_amm_tvl_drops{pool="<id>"}` — total value locked (XRP-denominated)
-
-  **Order Book Gauges** (per configured pair):
-  - `xrpl_orderbook_bid_depth{pair="<base>/<quote>"}` — total bid volume
-  - `xrpl_orderbook_ask_depth{pair="<base>/<quote>"}` — total ask volume
-  - `xrpl_orderbook_spread{pair="<base>/<quote>"}` — best bid-ask spread
-  - `xrpl_orderbook_offer_count{pair="<base>/<quote>", side="bid|ask"}` — number of offers
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/dex.go`
-
-**Note**: This is optional because it requires explicit configuration of which pools/pairs to track. Default configuration tracks no DEX data.
-
----
-
-## Task 11.8: Prometheus Alerting Rules
-
-**Objective**: Create production-ready alerting rules for the `xrpl_*` metrics
-exported by this receiver.
-
-> **Scope note — do not duplicate Phase 9.** Phase 9 already ships provisioned
-> **Grafana** alerting at
-> `docker/telemetry/grafana/provisioning/alerting/{rules,contactpoints,policies}.yaml`
-> — 13 rules in 5 groups, 2 contact points (`xrpld-default` Slack,
-> `xrpld-critical` Slack + email), and a nested notification policy keyed on
-> `severity = critical`. Four of the rules below overlap it:
->
-> | Rule here           | Addressed by (Phase 9)                            | Coverage                                                                                                         |
-> | ------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-> | `XRPLServerNotFull` | `NodeNotFull` (group `xrpld-node-state`)          | Full                                                                                                             |
-> | `XRPLLedgerStale`   | `ValidatedLedgerStale` (group `xrpld-consensus`)  | **Partial** — Phase 9: `ledgermaster_validated_ledger_age > 60` for 5m; the external shape is `> 30` for 1m      |
-> | `XRPLHighIOLatency` | `NodeStoreIOLatencyHigh` (group `xrpld-jobqueue`) | **Partial** — Phase 9: p95 of `ios_latency_milliseconds_bucket` **> 1000 ms for 10m**; external: **> 50 for 1m** |
-> | `XRPLStateFlapping` | `NodeStateFlapping` (group `xrpld-node-state`)    | Full                                                                                                             |
->
-> The remaining 8 (`XRPLAmendmentBlocked`, `XRPLNoPeers`,
-> `XRPLUnsupportedAmendmentMajority`, `XRPLLowPeerCount`, `XRPLHighLoadFactor`,
-> `XRPLSlowConsensus`, `XRPLValidatorListExpiring`, `XRPLClockDrift`) are
-> genuinely new. Note the two sets watch different metric surfaces — the Phase 9
-> rules fire on xrpld's own OTLP metrics, these on the receiver's `xrpl_*`
-> metrics — so if both are kept, dedupe the notification policy to avoid
-> double-paging on the same underlying condition.
->
-> `docker/telemetry/prometheus/` does not exist today. Prefer extending the
-> Phase 9 Grafana provisioning tree over introducing a second, Prometheus-native
-> alerting mechanism; if a `prometheus/` tree is added anyway, say explicitly in
-> its header which alerts it owns.
-
-**What to do**:
-
-- Create `docker/telemetry/prometheus/rippled-alerts.yml`:
-
-  **Tier 1 — Critical (page immediately):**
-
-  ```yaml
-  - alert: XRPLServerNotFull
-    expr: xrpl_server_state < 4
-    for: 15m
-
-  - alert: XRPLAmendmentBlocked
-    expr: xrpl_amendment_blocked == 1
-    for: 1m
-
-  - alert: XRPLNoPeers
-    expr: xrpl_peers_count == 0
-    for: 5m
-
-  - alert: XRPLLedgerStale
-    expr: xrpl_validated_ledger_age_seconds > 120
-    for: 2m
-
-  - alert: XRPLHighIOLatency
-    expr: xrpl_io_latency_ms > 100
-    for: 5m
-
-  - alert: XRPLUnsupportedAmendmentMajority
-    expr: xrpl_amendment_unsupported_majority == 1
-    for: 1m
-  ```
-
-  **Tier 2 — Warning (investigate within hours):**
-
-  ```yaml
-  - alert: XRPLLowPeerCount
-    expr: xrpl_peers_count < 10
-    for: 15m
-
-  - alert: XRPLHighLoadFactor
-    expr: xrpl_load_factor > 10
-    for: 10m
-
-  - alert: XRPLSlowConsensus
-    expr: xrpl_last_close_converge_time_seconds > 6
-    for: 5m
-
-  - alert: XRPLValidatorListExpiring
-    expr: (xrpl_validator_list_expiration_seconds - time()) < 86400
-    for: 1h
-
-  - alert: XRPLClockDrift
-    expr: xrpl_close_time_offset_seconds > 0
-    for: 5m
-
-  - alert: XRPLStateFlapping
-    expr: rate(xrpl_state_transitions_total{state="full"}[1h]) > 2
-    for: 30m
-  ```
-
-**Key files**:
-
-- New: `docker/telemetry/prometheus/rippled-alerts.yml`
-- Update: `docker/telemetry/prometheus/prometheus.yml` (add rule_files reference)
-
----
-
-## Task 11.9: New Grafana Dashboards
-
-**Objective**: Create 4 new dashboards for the data exported by the receiver.
-
-> **UID COLLISION — pick a different uid.** Phase 9 already ships
-> `docker/telemetry/grafana/dashboards/validator-health.json` with
-> **uid `validator-health`** (17 panels, backed by xrpld's own
-> `validation_agreement` / `validator_health` / `state_tracking` OTLP metrics).
-> Provisioning a second dashboard with the same uid makes Grafana overwrite one
-> with the other — whichever the provisioner loads last wins, silently. Use a
-> distinct uid such as `validator-health-external` (and a distinct filename), the
-> same way this task already disambiguates Fee Market as
-> `xrpld-fee-market-external` against Phase 9's `fee-market`. Also check
-> `peer-quality`, `fee-market`, `job-queue` and `node-health` before adding any
-> further uid.
-
-**What to do**:
-
-- **Validator Health** (`validator-health-external` — **not** `validator-health`,
-  see the collision note above):
-  - Server state timeline, state duration breakdown
-  - Proposer count trend, converge time trend, validation quorum
-  - Validator list expiration countdown
-  - Amendment voting status (majority/enabled/vetoed)
-
-- **Network Topology** (`xrpld-network-topology`):
-  - Peer count (inbound/outbound/cluster), peer version distribution
-  - Peer latency distribution (p50/p95/p99), diverged peer count
-  - Geographic distribution (if enriched with GeoIP)
-  - Peer uptime distribution
-
-- **Fee Market** (`xrpld-fee-market-external`):
-  - Current fee levels (open ledger, median, minimum), fee escalation timeline
-  - Queue depth vs. capacity, transactions per ledger
-  - Load factor breakdown (server/network/cluster/escalation)
-
-- **DEX & AMM Overview** (`xrpld-dex-amm`) (only populated when DEX collectors are configured):
-  - AMM pool TVL, reserve ratios, LP token supply
-  - Order book depth per pair, spread trends
-  - Trading fee revenue estimates
-
-**Key files**:
-
-- New: `docker/telemetry/grafana/dashboards/validator-health-external.json`
-  (**must not** reuse Phase 9's `validator-health.json` / uid `validator-health`)
-- New: `docker/telemetry/grafana/dashboards/network-topology.json`
-- New: `docker/telemetry/grafana/dashboards/fee-market-external.json`
-  (Phase 9 owns `fee-market.json` / uid `fee-market`)
-- New: `docker/telemetry/grafana/dashboards/dex-amm.json`
-
-> Filenames drop the legacy `dashboards/rippled-*` prefix: `145b1469d6` and
-> `25868f2740` renamed every dashboard to bare names with bare uids, so no
-> `dashboards/rippled-*.json` path exists in the tree.
-
----
-
-## Task 11.10: Integration with Phase 10 Validation
-
-**Objective**: Extend the Phase 10 validation suite to verify this receiver's metrics.
-
-**What to do**:
-
-- Update `docker/telemetry/workload/validate_telemetry.py`:
-  - Add assertions for all `xrpl_*` metrics produced by the receiver
-  - Verify metric labels have expected values
-  - Verify alerting rules fire correctly (inject a "bad" state and check alert)
-
-- Update `docker/telemetry/docker-compose.workload.yaml`:
-  - Add the custom OTel Collector build with the xrpld receiver
-  - Configure the receiver to poll one of the test nodes
-
-**Key files**:
-
-- Update: `docker/telemetry/workload/validate_telemetry.py`
-- Update: `docker/telemetry/docker-compose.workload.yaml`
-- Update: `docker/telemetry/workload/expected_metrics.json`
-
----
-
-## Task 11.11: Documentation
-
-**Objective**: Document the receiver, its metrics, deployment, and alerting.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-rippled-receiver/README.md`:
-  - Architecture overview (how the receiver fits into the OTel Collector)
-  - Configuration reference (all config options with defaults)
-  - Metric reference table (all exported metrics with types and labels)
-  - Deployment guide (building custom collector binary, docker-compose integration)
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add "Third-Party Metrics (OTel Collector Receiver)" section
-  - Add new Grafana dashboard reference (4 dashboards)
-  - Add alerting rules reference
-
-- Update `docs/telemetry-runbook.md`:
-  - Add "Third-Party Metrics Receiver" troubleshooting section
-  - Add alerting playbook (what to do for each Tier 1/Tier 2 alert)
-
----
-
-## Task 11.12: Alert Rules for External Dashboard Parity Metrics
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — 18 alert rules ported from the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 7 Tasks 7.9-7.16 (metrics), Phase 9 Tasks 9.11-9.13 (dashboards).
-> **Downstream**: None — terminal task in the parity chain.
-
-**Objective**: Add Grafana alerting rules for the Phase 7+ parity metrics (validation agreement, validator health, peer quality, state tracking, ledger economy). These complement Task 11.8's `xrpl_*` alerts by covering the internal metrics.
-
-> **4 of the 18 are addressed by Phase 9** — 2 fully, 2 only partially. Extend,
-> do not blindly re-create:
->
-> | Rule here          | Addressed by (Phase 9)                                                                      | Coverage                                                                                                                                                                    |
-> | ------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-> | Unhealthy State    | `NodeNotFull` (group `xrpld-node-state`)                                                    | Full                                                                                                                                                                        |
-> | High IO Latency    | `NodeStoreIOLatencyHigh` (group `xrpld-jobqueue`, p95 of `ios_latency_milliseconds_bucket`) | **Partial** — Phase 9 fires at p95 **> 1000 ms for 10m**; the rule below wants **> 50 for 1m** (20× tighter)                                                                |
-> | Job Queue Overflow | `JobQueueTxOverflow` (group `xrpld-jobqueue`, `jq_trans_overflow_total`)                    | Full                                                                                                                                                                        |
-> | Stale Ledger       | `ValidatedLedgerStale` (group `xrpld-consensus`, `ledgermaster_validated_ledger_age`)       | **Partial** — different metric: Phase 9 uses `ledgermaster_validated_ledger_age > 60` for 5m; the rule below uses `ledger_economy{metric="ledger_age_seconds"} > 30` for 1m |
->
-> The two **Partial** rows are not closed. Either re-baseline the Phase 9
-> thresholds or ship the tighter variants here — do not skip them as duplicates.
->
-> Remaining open work is **14 rules**, of which **3** (CPU High, Memory Critical,
-> Disk Warning) need `node_exporter`, which is not in the stack. Nothing else is
-> blocked: "Not Proposing" used to be listed as blocked on an unimplemented
-> `state_tracking` gauge, but that gauge **ships** — see the Exit Criteria note
-> below.
->
-> **Metric-name translation.** Names carry **no** `xrpld_` prefix
-> (`77f35c03db`), so as a rule of thumb read every `xrpld_<name>` below as plain
-> `<name>`. **Two shapes do not follow that rule:**
->
-> - **Multiplexed observable gauges.** Many readings are a `metric` **label
->   value** on a shared instrument, not a metric name. `xrpld_txq_count` is
->   `txq_metrics{metric="txq_count"}`; likewise `load_factor_metrics{…}`,
->   `nodestore_state{…}`, `cache_metrics{…}`. The rows below that already use the
->   `<instrument>{metric="…"}` form (`state_tracking`, `validator_health`,
->   `validation_agreement`, `server_info`, `peer_quality`, `load_factor_metrics`,
->   `ledger_economy`) are correct; only drop the prefix on those.
-> - **Unit-suffixed histograms** from `beast::insight`. `OTelCollectorImp` appends
->   the unit, so `xrpld_ios_latency_bucket` is really
->   `ios_latency_milliseconds_bucket` — the spelling used by
->   `node-health.json:577` and `ledger-data-sync.json:1353`.
-
-**Critical Group** (8 rules, eval interval 10s):
-
-| Rule                | Condition                                                        | For |
-| ------------------- | ---------------------------------------------------------------- | --- |
-| Agreement Below 90% | `xrpld_validation_agreement{metric="agreement_pct_24h"} < 90`    | 30s |
-| Not Proposing       | `xrpld_state_tracking{metric="state_value"} < 6`                 | 10s |
-| Unhealthy State     | `xrpld_state_tracking{metric="state_value"} < 4`                 | 10s |
-| Amendment Blocked   | `xrpld_validator_health{metric="amendment_blocked"} == 1`        | 1m  |
-| UNL Expiring        | `xrpld_validator_health{metric="unl_expiry_days"} < 14`          | 1h  |
-| High IO Latency     | `histogram_quantile(0.95, ios_latency_milliseconds_bucket) > 50` | 1m  |
-| High Load Factor    | `xrpld_load_factor_metrics{metric="load_factor"} > 1000`         | 1m  |
-| Peer Count Critical | `xrpld_server_info{metric="peers"} < 5`                          | 1m  |
-
-**Network Group** (3 rules, eval interval 10s):
-
-| Rule                      | Condition                                                         | For |
-| ------------------------- | ----------------------------------------------------------------- | --- |
-| Peer Drop >10%            | `delta(xrpld_server_info{metric="peers"}[30s]) / ... * 100 < -10` | 30s |
-| Peer Drop >30%            | Same formula, threshold -30                                       | 30s |
-| P90 Latency + Disconnects | `peer_latency_p90_ms > 500 AND rate(disconnects) > 0`             | 2m  |
-
-**Performance Group** (7 rules, eval interval 10s):
-
-| Rule                | Condition                                                    | For |
-| ------------------- | ------------------------------------------------------------ | --- |
-| CPU High            | Per-core CPU > 80% (requires node_exporter)                  | 2m  |
-| Memory Critical     | Memory usage > 90% (requires node_exporter)                  | 1m  |
-| Disk Warning        | Disk usage > 85% (requires node_exporter)                    | 2m  |
-| Job Queue Overflow  | `rate(xrpld_jq_trans_overflow_total[5m]) > 0`                | 1m  |
-| Upgrade Recommended | `xrpld_peer_quality{metric="peers_higher_version_pct"} > 60` | 1m  |
-| TX Rate Drop        | Transaction rate dropped > 50% in 5m window                  | 5m  |
-| Stale Ledger        | `xrpld_ledger_economy{metric="ledger_age_seconds"} > 30`     | 1m  |
-
-**Notification channel templates**: Slack and Email/SMTP already ship in Phase
-9's `contactpoints.yaml` (`xrpld-default`, `xrpld-critical`). Discord and
-PagerDuty templates remain open.
-
-**Key files** — extend the **Phase 9** provisioning tree. The
-`docker/telemetry/grafana/alerting/` directory named in the original spec has
-never existed in any commit; the real location is
-`docker/telemetry/grafana/provisioning/alerting/`:
-
-- Extend: `docker/telemetry/grafana/provisioning/alerting/rules.yaml` (add groups
-  alongside the existing `xrpld-consensus`, `xrpld-validator`, `xrpld-jobqueue`,
-  `xrpld-node-state`, `xrpld-overlay`)
-- Extend: `docker/telemetry/grafana/provisioning/alerting/contactpoints.yaml`
-  (add Discord / PagerDuty receivers)
-- Extend: `docker/telemetry/grafana/provisioning/alerting/policies.yaml`
-  (add routes; the root route and the `severity = critical` child already exist)
-
-**Exit Criteria**:
-
-- [ ] The 14 not-yet-shipped rules evaluate without errors in Grafana alerting UI
-- [ ] The 2 rules **fully** covered by Phase 9 (Unhealthy State, Job Queue
-      Overflow) are not duplicated; the 2 **partially** covered ones (High IO
-      Latency, Stale Ledger) are either re-baselined on the Phase 9 rule or shipped
-      as tighter variants — decision recorded either way
-- [ ] Critical rules fire within expected timeframe when conditions are met
-- [ ] Notification channel templates are documented (not hard-coded to any service)
-- [ ] `node_exporter` decision recorded for the 3 host-level rules (CPU, memory, disk)
-- [x] `state_tracking` gauge implemented (Task 7.12) before adding "Not Proposing"
-      — **prerequisite met upstream**, not Phase 11 work.
-      `MetricsRegistry::registerStateTrackingGauge()`
-      (`src/xrpld/telemetry/MetricsRegistry.cpp:1461-1510`) creates
-      `CreateDoubleObservableGauge("state_tracking", "Node state and mode tracking")`
-      at `:1466` and observes `state_value` (`:1497`) and
-      `time_in_current_state_seconds` (`:1502`). Already queried by
-      `validator-health.json:765,971` and `ledger-data-sync.json:869`, and
-      documented in
-      [09-data-collection-reference.md](./09-data-collection-reference.md)
-      § State Tracking. "Not Proposing" can be written now.
-
----
-
-## Task 11.13: Dual-Datasource Architecture Documentation
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Document the external dashboard's "fast path" pattern as a future optimization for real-time panels.
-
-**Pattern**: A lightweight Prometheus scrape endpoint (separate from OTLP pipeline) that polls critical metrics every 2-5s, bypassing the 10s OTLP metric reader interval and Prometheus scrape interval.
-
-**Use case**: Real-time state panels (server state, ledger age, peer count) where 10-15s latency is too slow for operational dashboards.
-
-**Decision**: Document as a future option, not implement now. The current 10s interval is acceptable for v1. The external dashboard achieves 2-5s freshness by polling RPC directly, which is what the Phase 11 receiver already does. Adding a separate scrape endpoint to xrpld would only be needed if sub-second metric freshness is required from the internal metrics pipeline.
-
-**What to document**:
-
-- Architecture comparison: OTLP pipeline (10-15s) vs. direct scrape (2-5s) vs. push gateway
-- When to consider: operator feedback indicating 10s is insufficient for alerting SLOs
-- How to implement if needed: add `/metrics` HTTP endpoint to xrpld with Prometheus client library
-- Trade-offs: additional port, additional dependency, duplication with OTLP metrics
-
-**Key files**:
-
-- Update: `OpenTelemetryPlan/09-data-collection-reference.md` (add "Future: Dual-Datasource Architecture" section)
-- Update: `docs/telemetry-runbook.md` (add brief note in performance tuning section)
-
-**Exit Criteria**:
-
-- [ ] Architecture comparison documented with clear trade-offs
-- [ ] Decision rationale recorded (why deferred, when to revisit)
-
----
-
-## Exit Criteria
-
-- [ ] Custom OTel Collector receiver builds and starts without errors
-- [ ] All `xrpl_*` metrics from server_info, get_counts, peers, validators, fee appear in Prometheus
-- [ ] Metrics update at configured poll interval (default 30s)
-- [ ] 4 new Grafana dashboards operational with data, none reusing a Phase 9 uid
-      (`validator-health`, `peer-quality`, `fee-market`, `job-queue`, `node-health`)
-- [ ] Prometheus alerting rules fire correctly for simulated failure conditions
-- [ ] DEX/AMM collector works when configured (optional — not required for base exit criteria)
-- [ ] Phase 10 validation suite passes with receiver metrics included
-- [ ] Receiver handles xrpld restart/unavailability gracefully (no crash, logs warning, retries)
-- [ ] Documentation complete: receiver README, metric reference, alerting playbook
-- [ ] Go receiver has unit tests with >80% coverage
-- [ ] The 14 not-yet-shipped Grafana alert rules for Phase 7+ parity metrics
-      evaluate correctly (Task 11.12); the other 4 of the 18 already ship in Phase 9
-- [ ] Dual-datasource architecture documented with trade-offs (Task 11.13)

OpenTelemetryPlan/Phase2_taskList.md

@@ -1,240 +0,0 @@
-# Phase 2: RPC Tracing Completion Task List
-
-> **Goal**: Complete RPC tracing coverage with unit tests, Grafana search filters, PathFind instrumentation, and config hardening. Build on the Phase 1c SpanGuard factory foundation to achieve production-quality RPC observability.
->
-> **Scope**: Unit tests for core telemetry, Grafana Tempo search filters, PathFind RPC tracing, config validation (`std::clamp`).
->
-> **Branch**: `pratik/otel-phase2-rpc-tracing` (from `pratik/otel-phase1c-rpc-integration`)
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                                                                                                        |
-| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| [03-implementation-strategy.md](./03-implementation-strategy.md) | Code structure and instrumentation patterns (replaces the deleted `04-code-samples.md` §4.4.2 / §4.5.3, removed by `d6450631bf`) |
-| [02-design-decisions.md](./02-design-decisions.md)               | W3C Trace Context (§2.5), span attributes (§2.4.2)                                                                               |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 2 tasks (§6.3), definition of done (§6.11.2)                                                                               |
-
----
-
-## Task 2.1: W3C Trace Context HTTP Header Extraction
-
-**Status**: DEFERRED → Phase 3
-
-**Reason**: W3C context propagation (`traceparent`/`tracestate` headers) requires a consumer — in Phase 2, RPC spans are entirely local to the node. Phase 3 introduces cross-node transaction tracing via protobuf context propagation, which is the first use case for extracted trace context. Implementing it here without a consumer would be dead code.
-
-**Implemented in**: `pratik/otel-phase3-tx-tracing` — `TraceContextPropagator.h/.cpp`
-
----
-
-## Task 2.2: Per-Category Span Creation
-
-**Status**: COMPLETE (superseded by Phase 1c design)
-
-**Original plan**: Add `XRPL_TRACE_PEER` and `XRPL_TRACE_LEDGER` macros.
-
-**Actual implementation**: Phase 1c replaced all tracing macros with the `SpanGuard::span(TraceCategory, prefix, name)` factory pattern. The `TraceCategory` enum (`Rpc`, `Transactions`, `Consensus`, `Peer`, `Ledger`) serves the same conditional-creation purpose without macros. No separate task needed — the factory already supports all categories.
-
----
-
-## Task 2.3: Add shouldTraceLedger() to Telemetry Interface
-
-**Objective**: The `Setup` struct has a `traceLedger` field but there's no corresponding virtual method. Add it for interface completeness.
-
-**What to do**:
-
-- Edit `include/xrpl/telemetry/Telemetry.h`:
-  - Add `virtual bool shouldTraceLedger() const = 0;`
-
-- Update all implementations:
-  - `src/libxrpl/telemetry/Telemetry.cpp` (TelemetryImpl, NullTelemetryOtel)
-  - `src/libxrpl/telemetry/NullTelemetry.cpp` (NullTelemetry)
-
-**Key modified files**:
-
-- `include/xrpl/telemetry/Telemetry.h`
-- `src/libxrpl/telemetry/Telemetry.cpp`
-- `src/libxrpl/telemetry/NullTelemetry.cpp`
-
----
-
-## Task 2.4: Unit Tests for Core Telemetry Infrastructure
-
-**Status**: COMPLETE
-
-**Objective**: Add unit tests for the core telemetry abstractions to validate correctness and catch regressions.
-
-**Implemented**:
-
-- `src/tests/libxrpl/telemetry/TelemetryConfig.cpp`:
-  - Test Setup defaults (all fields have correct initial values)
-  - Test `makeTelemetrySetup` config parser (empty section, full section, edge cases)
-  - Test `samplingRatio` clamping (values outside 0.0-1.0)
-
-- `src/tests/libxrpl/telemetry/SpanGuardFactory.cpp`:
-  - Test null guard methods are safe (setAttribute, setOk, setError, addEvent on null)
-  - Test category span returns null when telemetry disabled
-  - Test child/linked span null when no parent context
-  - Test move construction transfers ownership
-  - Test recordException safe on null guard
-  - Test discard() safe on null guard
-
-- `src/tests/libxrpl/telemetry/main.cpp` — GTest runner
-- `src/tests/libxrpl/CMakeLists.txt` — test target with optional OTel linking
-
----
-
-## Task 2.5: Enhance RPC Span Attributes
-
-**Status**: DEFERRED (low priority)
-
-**Reason**: The high-value attributes (`command`, `version`, `role`, `status`) are already set by Phase 1c. The remaining HTTP transport-level attributes (`http.method`, `net.peer.ip`, `http.status_code`) provide limited additional insight since:
-
-- `http.method` is always POST for JSON-RPC
-- `net.peer.ip` is debug-level info available in logs
-- `duration_ms` is redundant with span duration (OTel captures start/end time natively)
-
-These can be added later if dashboard queries specifically need them. The node health attributes (Task 2.8) provide far more operational value and were prioritized instead.
-
----
-
-## Task 2.6: Build Verification and Performance Baseline
-
-**Objective**: Verify the build succeeds with and without telemetry, and establish a performance baseline.
-
-**What to do**:
-
-1. Build with `telemetry=ON` and verify no compilation errors
-2. Build with `telemetry=OFF` and verify no regressions
-3. Run existing unit tests to verify no breakage
-4. Document any build issues in lessons.md
-
-**Verification Checklist**:
-
-- [ ] `conan install . --build=missing -o telemetry=True` succeeds
-- [ ] `cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -Dtelemetry=ON ..` configures correctly (there is no `default` preset; Conan writes `conan-release`)
-- [ ] Build succeeds with telemetry ON
-- [ ] Build succeeds with telemetry OFF
-- [ ] Existing tests pass with telemetry ON
-- [ ] Existing tests pass with telemetry OFF
-
----
-
-## Task 2.8: RPC Span Attribute Enrichment — Node Health Context
-
-**Status**: DROPPED.
-
-Node health (`amendment_blocked`, `server_state`) is not part of the telemetry surface. Operators consume the same data via the existing `server_info` / `server_state` RPC commands, so duplicating it on traces adds storage and cardinality cost without new value. The OTel C++ SDK 1.18.0 also does not support runtime updates to the resource, ruling out resource-level emission of these dynamic-by-nature flags.
-
----
-
-## Task 2.9: PathFind RPC Instrumentation
-
-**Status**: COMPLETE
-
-**Objective**: Trace the path_find and ripple_path_find RPC handlers to capture request latency and computation cost.
-
-**Spans added**:
-
-- `pathfind.request` — wraps `doPathFind()` and `doRipplePathFind()` RPC handlers
-- `pathfind.compute` — wraps `PathRequest::doUpdate()` (`pathfind_fast` attr)
-- `pathfind.update_all` — wraps `PathRequestManager::updateAll()` on ledger close (`pathfind_ledger_index`, `pathfind_num_requests` attrs; emitted only when active subscriptions exist)
-- `pathfind.discover` — wraps the entire per-source-asset loop in `PathRequest::findPaths()` (`pathfind_search_level`, `pathfind_num_paths` attrs). One span per RPC call instead of N (one per source asset). Trade-off: per-asset breakdown is lost; storage and cardinality bounded.
-
-**Attribute namespacing**: All pathfind attributes use the `pathfind_*` underscore form per the Phase 1c naming-spec rule 5.
-
-**New file**: `src/xrpld/rpc/detail/PathFindSpanNames.h`
-
-**Modified files**:
-
-- `src/xrpld/rpc/handlers/orderbook/PathFind.cpp`
-- `src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp`
-- `src/xrpld/rpc/detail/PathRequest.cpp`
-- `src/xrpld/rpc/detail/PathRequestManager.cpp`
-- `src/xrpld/rpc/detail/Pathfinder.cpp`
-
----
-
-## Task 2.10: RPC and PathFind Span Attribute Gap Fill
-
-**Status**: COMPLETE
-
-**Objective**: Wire up workflow-identifying attributes that enable filtering and grouping traces by request characteristics without drilling into child spans.
-
-**Attributes added**:
-
-| Span                | Attribute                    | Type   | Source                            |
-| ------------------- | ---------------------------- | ------ | --------------------------------- |
-| `rpc.http_request`  | `request_payload_size`       | int64  | `request.body().size()`           |
-| `rpc.process`       | `is_batch`                   | bool   | `method == "batch"` check         |
-| `rpc.process`       | `batch_size`                 | int64  | `params.size()` (only when batch) |
-| `rpc.ws_message`    | `command`                    | string | `jv[command]` or `jv[method]`     |
-| `rpc.command.*`     | `load_type`                  | string | `context.loadType.label()`        |
-| `pathfind.compute`  | `pathfind_dest_currency`     | string | `to_string(saDstAmount_.asset())` |
-| `pathfind.discover` | `pathfind_num_source_assets` | int64  | `sourceAssets.size()`             |
-
-_Note: `pathfind_dest_amount` was removed — the destination amount is a financial value excluded by the privacy policy (design §2.4.4)._
-
-**New attr keys**: `RpcSpanNames.h` (`isBatch`, `batchSize`, `loadType`), `PathFindSpanNames.h` (`destCurrency`, `numSourceAssets`).
-
-**Modified files**:
-
-- `src/xrpld/rpc/detail/RpcSpanNames.h`
-- `src/xrpld/rpc/detail/PathFindSpanNames.h`
-- `src/xrpld/rpc/detail/ServerHandler.cpp`
-- `src/xrpld/rpc/detail/RPCHandler.cpp`
-- `src/xrpld/rpc/detail/PathRequest.cpp`
-
----
-
-## Summary
-
-| Task | Description                                 | Status              | Notes                                                     |
-| ---- | ------------------------------------------- | ------------------- | --------------------------------------------------------- |
-| 2.1  | W3C Trace Context header extraction         | Deferred → Phase 3  | No consumer in Phase 2; needs cross-node tracing          |
-| 2.2  | Per-category span creation                  | Complete (Phase 1c) | Superseded by TraceCategory enum + SpanGuard              |
-| 2.3  | Add shouldTraceLedger() interface method    | Complete (Phase 1c) | Delivered in Phase 1c base branch                         |
-| 2.4  | Unit tests for core telemetry               | Complete            | TelemetryConfig + SpanGuardFactory tests                  |
-| 2.5  | Enhanced RPC span attributes (HTTP-level)   | Deferred            | Low value; span duration covers timing natively           |
-| 2.6  | Build verification and performance baseline | Complete            | Verified in CI on Phase 1c                                |
-| 2.7  | Grafana Tempo search filters                | Complete            | rpc-command, rpc-status, rpc-role filters                 |
-| 2.8  | RPC span attribute enrichment (node health) | Dropped             | Available via `server_info`/`server_state` RPC            |
-| 2.9  | PathFind RPC instrumentation                | Complete            | request, compute, update_all, discover                    |
-| 2.10 | RPC/PathFind span attribute gap fill        | Complete            | Batch detection, payload size, load cost, pathfind params |
-
-**Delivered in this branch**: Tasks 2.4, 2.7, 2.9, 2.10.
-**Deferred with rationale**: Tasks 2.1 (→Phase 3), 2.5 (low priority).
-**Dropped**: Task 2.8 (node health not duplicated on traces).
-**Superseded**: Task 2.2 (Phase 1c SpanGuard factory covers this).
-
----
-
-## Known Issues / Future Work
-
-### Thread safety of TelemetryImpl::stop() vs startSpan()
-
-`TelemetryImpl::stop()` resets `sdkProvider_` (a `std::shared_ptr`) without
-synchronization. `getTracer()` reads the same member from RPC handler threads.
-This is a data race if any thread calls `startSpan()` concurrently with `stop()`.
-
-**Current mitigation**: `Application::stop()` shuts down `serverHandler_`,
-`overlay_`, and `jobQueue_` before calling `telemetry_->stop()`, so no callers
-remain. See comments in `Telemetry.cpp:stop()` and `Application.cpp`.
-
-**TODO**: Add an `std::atomic<bool> stopped_` flag checked in `getTracer()` to
-make this robust against future shutdown order changes.
-
-### Macro incompatibility: XRPL_TRACE_SPAN vs XRPL_TRACE_SET_ATTR
-
-`XRPL_TRACE_SPAN` and `XRPL_TRACE_SPAN_KIND` declare `_xrpl_guard_` as a bare
-`SpanGuard`, but `XRPL_TRACE_SET_ATTR` and `XRPL_TRACE_EXCEPTION` call
-`_xrpl_guard_.has_value()` which requires `std::optional<SpanGuard>`. Using
-`XRPL_TRACE_SPAN` followed by `XRPL_TRACE_SET_ATTR` in the same scope would
-fail to compile.
-
-**Current mitigation**: No call site currently uses `XRPL_TRACE_SPAN` — all
-production code uses the conditional macros (`XRPL_TRACE_RPC`, `XRPL_TRACE_TX`,
-etc.) which correctly wrap the guard in `std::optional`.
-
-**TODO**: Either make `XRPL_TRACE_SPAN`/`XRPL_TRACE_SPAN_KIND` also wrap in
-`std::optional`, or document that `XRPL_TRACE_SET_ATTR` is only compatible with
-the conditional macros.

OpenTelemetryPlan/Phase3_taskList.md

@@ -1,571 +0,0 @@
-# Phase 3: Transaction Tracing Task List
-
-> **Goal**: Trace the full transaction lifecycle from RPC submission through peer relay, including cross-node context propagation via Protocol Buffer extensions. This is the WALK phase that demonstrates true distributed tracing.
->
-> **Scope**: Protocol Buffer `TraceContext` message, context serialization, PeerImp transaction instrumentation, NetworkOPs processing instrumentation, HashRouter visibility, and multi-node relay context propagation.
->
-> **Branch**: `pratik/otel-phase3-tx-tracing` (from `pratik/otel-phase2-rpc-tracing`)
-
-### Related Plan Documents
-
-| Document                                                                                          | Relevance                                                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow) | Authoritative protocol span-flow reference — replaces the deleted `04-code-samples.md` (TraceContext protobuf §4.4.1, PeerImp instrumentation §4.5.1, context serialization §4.4.2), removed by `d6450631bf` |
-| [01-architecture-analysis.md](./01-architecture-analysis.md)                                      | Transaction flow (§1.3), key trace points (§1.6)                                                                                                                                                             |
-| [06-implementation-phases.md](./06-implementation-phases.md)                                      | Phase 3 tasks (§6.4), definition of done (§6.11.3)                                                                                                                                                           |
-| [02-design-decisions.md](./02-design-decisions.md)                                                | Context propagation design (§2.5), attribute schema (§2.4.3)                                                                                                                                                 |
-
----
-
-## Task 3.1: Define TraceContext Protocol Buffer Message
-
-**Objective**: Add trace context fields to the P2P protocol messages so trace IDs can propagate across nodes.
-
-**What to do**:
-
-- Edit `include/xrpl/proto/xrpl.proto` (or `src/xrpld/proto/ripple.proto`, wherever the proto is):
-  - Add `TraceContext` message definition:
-    ```protobuf
-    message TraceContext {
-        bytes trace_id = 1;      // 16-byte trace identifier
-        bytes span_id = 2;       // 8-byte span identifier
-        uint32 trace_flags = 3;  // bit 0 = sampled
-        string trace_state = 4;  // W3C tracestate value
-    }
-    ```
-  - Add `optional TraceContext trace_context = 1001;` to:
-    - `TMTransaction`
-    - `TMProposeSet` (for Phase 4 use)
-    - `TMValidation` (for Phase 4 use)
-  - Use high field numbers (1001+) to avoid conflicts with existing fields
-
-- Regenerate protobuf C++ code
-
-**Key modified files**:
-
-- `include/xrpl/proto/xrpl.proto` (or equivalent)
-
-**Reference**:
-
-- `04-code-samples.md` §4.4.1 (TraceContext message definition) was deleted by
-  `d6450631bf`; the live definition is `include/xrpl/proto/xrpl.proto:101`
-  (`message TraceContext`), attached as field `1001` on the relevant messages
-- [02-design-decisions.md §2.5.2](./02-design-decisions.md) — Protocol buffer context propagation design
-
----
-
-## Task 3.2: Implement Protobuf Context Serialization
-
-**Objective**: Create utilities to serialize/deserialize OTel trace context to/from protobuf `TraceContext` messages.
-
-**What to do**:
-
-- Create `include/xrpl/telemetry/TraceContextPropagator.h` (extend from Phase 2 if exists, or add protobuf methods):
-  - Add protobuf-specific methods:
-    - `static Context extractFromProtobuf(protocol::TraceContext const& proto)` — reconstruct OTel context from protobuf fields
-    - `static void injectToProtobuf(Context const& ctx, protocol::TraceContext& proto)` — serialize current span context into protobuf fields
-  - Both methods guard behind `#ifdef XRPL_ENABLE_TELEMETRY`
-
-- Create/extend `src/libxrpl/telemetry/TraceContextPropagator.cpp`:
-  - Implement extraction: read trace_id (16 bytes), span_id (8 bytes), trace_flags from protobuf, construct `SpanContext`, wrap in `Context`
-  - Implement injection: get current span from context, serialize its TraceId, SpanId, and TraceFlags into protobuf fields
-
-**Key new/modified files**:
-
-- `include/xrpl/telemetry/TraceContextPropagator.h`
-- `src/libxrpl/telemetry/TraceContextPropagator.cpp`
-
-**Reference**:
-
-- `04-code-samples.md` §4.4.2 (full extract/inject implementation) was deleted by
-  `d6450631bf`. As shipped there is **no**
-  `src/libxrpl/telemetry/TraceContextPropagator.cpp`; extract/inject live on
-  `SpanGuard` (`include/xrpl/telemetry/SpanGuard.h:467` extract, `:480-491`
-  `injectCurrentContextToProtobuf`, implemented in
-  `src/libxrpl/telemetry/SpanGuard.cpp`) with the protocol-layer wrappers in
-  `src/xrpld/telemetry/PropagationHelpers.h:52` (`injectSpanContext`)
-
----
-
-## Task 3.3: Instrument PeerImp Transaction Handling
-
-**Objective**: Add trace spans to the peer-level transaction receive and relay path.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp`:
-  - In `onMessage(TMTransaction)` / `handleTransaction()`:
-    - Extract parent trace context from incoming `TMTransaction::trace_context` field (if present)
-    - Create `tx.receive` span as child of extracted context (or new root if none)
-    - Set attributes: `tx_hash`, `peer_id`, `tx_status`
-    - Create the span only after `HashRouter::shouldProcess()` accepts, so a dropped duplicate produces no span
-    - Wrap validation call with child span `tx.validate`
-    - Wrap relay with `tx.relay` span
-  - When relaying to peers:
-    - Inject current trace context into outgoing `TMTransaction::trace_context`
-    - Set `relay_count` attribute
-
-- Use `SpanGuard::span(TraceCategory::Transactions, "tx", "receive")` factory
-  (Phase 1c replaced macros with the SpanGuard factory pattern)
-
-> **Note**: The `tx.receive` guard is `.detached()` before being moved into the
-> `RcvCheckTx` job so its Scope is popped on the peer thread, not leaked to the
-> worker (else later peer messages would inherit this transaction's trace).
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-
-**Reference**:
-
-- [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow)
-  — the authoritative `tx.receive` / relay span-flow reference; replaces
-  `04-code-samples.md` §4.5.1, deleted by `d6450631bf`
-- [01-architecture-analysis.md §1.3](./01-architecture-analysis.md) — Transaction flow diagram
-- [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — tx.receive trace point
-
----
-
-## Task 3.4: Instrument NetworkOPs Transaction Processing
-
-**Objective**: Trace the transaction processing pipeline in NetworkOPs, covering both sync and async paths.
-
-**What to do**:
-
-- Edit `src/xrpld/app/misc/NetworkOPs.cpp`:
-  - In `processTransaction()`:
-    - Create `tx.process` span
-    - Set attributes: `tx_hash`, `tx_type`, `local` (whether from RPC or peer)
-    - Record whether sync or async path is taken
-    - `.detached()` the guard before storing it in `TransactionStatus::span`,
-      since it is applied on a batch worker thread — this pops the Scope on the
-      origin thread and stops later work inheriting this transaction's trace
-
-  - In `doTransactionAsync()`:
-    - Capture parent context before queuing
-    - Create `tx.queue` span with queue depth attribute
-    - Add event when transaction is dequeued for processing
-
-  - In `doTransactionSync()`:
-    - Create `tx.process_sync` span
-    - Record result (applied, queued, rejected)
-
-**Key modified files**:
-
-- `src/xrpld/app/misc/NetworkOPs.cpp`
-
-**Reference**:
-
-- [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — tx.validate and tx.process trace points
-- [02-design-decisions.md §2.4.3](./02-design-decisions.md) — Transaction attribute schema
-
----
-
-## Task 3.5: Instrument HashRouter for Dedup Visibility
-
-**Objective**: Make transaction deduplication visible in traces by recording HashRouter decisions as span attributes/events.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp` (in handleTransaction):
-  - After calling `HashRouter::shouldProcess()` or `addSuppressionPeer()`:
-    - Start the span here, not before, so only transactions this node will process are traced
-    - Record `tx_flags` showing current HashRouter state (SAVED, TRUSTED, etc.)
-    - Add `tx.first_seen` or `tx.duplicate` event
-
-- This is NOT a modification to HashRouter itself — just recording its decisions as span attributes in the existing PeerImp instrumentation from Task 3.3.
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp` (same changes as 3.3, logically grouped)
-
----
-
-## Task 3.6: Context Propagation in Transaction Relay
-
-**Status**: COMPLETE (transaction relay). Consensus proposal/validation
-propagation is deferred to Phase 4 — see "Planned (Phase 4)" below.
-
-**Objective**: Ensure trace context flows correctly when transactions are relayed between peers, creating linked spans across nodes.
-
-**What was done**:
-
-- **TX send side**: `NetworkOPs::apply()` now injects the tx.process span's trace
-  context into the outgoing `TMTransaction` protobuf before relay, using
-  `telemetry::injectSpanContext()`. The receiving node's `txReceiveSpan()` (already
-  wired in PeerImp) extracts the parent span_id and creates the tx.receive span
-  as a child of the sender's tx.process span.
-
-- **Edge cases**: Missing trace context (older peers) degrades gracefully to
-  standalone spans. Invalid/corrupted context is treated as absent. Trace
-  flags are propagated and respected.
-
-**New infrastructure**:
-
-- `SpanGuard::getTraceBytes()` — extracts raw trace_id/span_id/trace_flags
-  from a span without exposing OTel types. Safe to call from any thread.
-- `PropagationHelpers.h` — `injectSpanContext(SpanGuard&, proto)` bridge
-  between SpanGuard and protobuf TraceContext.
-- `TraceContextPropagator.h` — `injectToProtobuf(ctx, proto)` for
-  same-thread injection via OTel RuntimeContext.
-
-**Key modified files**:
-
-- `src/xrpld/app/misc/NetworkOPs.cpp` — tx relay injection
-- `include/xrpl/telemetry/SpanGuard.h` — `TraceBytes` struct, `getTraceBytes()`
-- `src/libxrpl/telemetry/SpanGuard.cpp` — `getTraceBytes()` implementation
-- `src/xrpld/telemetry/PropagationHelpers.h` — inject helpers (new file)
-
-**Planned (Phase 4 — not in this PR)**:
-
-The consensus proposal/validation propagation below is Phase 4 scope and is
-not implemented on this branch. It is listed here only to record the intended
-design.
-
-- **Proposal send/receive**: `RCLConsensus::Adaptor::propose()` injects the
-  current thread's active span context into the `TMProposeSet` protobuf via
-  `telemetry::injectToProtobuf()`. PeerImp creates a
-  `consensus.proposal.receive` span that extracts the sender's trace context
-  as parent (via `ConsensusReceiveTracing.h`).
-
-- **Validation send/receive**: `RCLConsensus::Adaptor::validate()` injects
-  the current thread's active span context into the `TMValidation` protobuf.
-  PeerImp creates a `consensus.validation.receive` span that extracts the
-  sender's trace context as parent.
-
-- Planned files: `src/xrpld/app/consensus/RCLConsensus.cpp` (send injection),
-  `src/xrpld/overlay/detail/PeerImp.cpp` (receive spans),
-  `src/xrpld/telemetry/ConsensusReceiveTracing.h` (receive span helpers,
-  new file).
-
-**Reference**:
-
-- [02-design-decisions.md §2.5](./02-design-decisions.md) — Context propagation design
-- Relay context injection pattern: `04-code-samples.md` §4.5.1 was deleted by
-  `d6450631bf`; the live pattern is `injectSpanContext()` in
-  `src/xrpld/telemetry/PropagationHelpers.h:52`, with the flow documented in
-  [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow)
-
----
-
-## Task 3.7: Build Verification and Testing
-
-**Objective**: Verify all Phase 3 changes compile and work correctly.
-
-**What to do**:
-
-1. Build with `telemetry=ON` — verify no compilation errors
-2. Build with `telemetry=OFF` — verify no regressions
-3. Run existing unit tests
-4. Verify protobuf regeneration produces correct C++ code
-5. Document any issues encountered
-
-**Verification Checklist**:
-
-- [ ] Protobuf changes generate valid C++
-- [ ] Build succeeds with telemetry ON
-- [ ] Build succeeds with telemetry OFF
-- [ ] Existing tests pass
-- [ ] No undefined symbols from new telemetry calls
-
----
-
-## Task 3.8: Transaction Span Peer Version Attribute
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — adds peer version context inspired by the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 2 (RPC span infrastructure must exist).
-> **Downstream**: Phase 10 (validation checks for this attribute).
-
-**Objective**: Add the relaying peer's xrpld version to `tx.receive` spans so operators can correlate transaction issues with peer version mismatches during network upgrades.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp`:
-  - In the `tx.receive` span block (after existing `peer_id` setAttribute call):
-    - Add `peer_version` (string) — from `this->getVersion()`
-    - Only set if `getVersion()` returns a non-empty string (avoid empty-string attributes)
-
-**New span attribute**:
-
-| Attribute      | Type   | Source               | Example         |
-| -------------- | ------ | -------------------- | --------------- |
-| `peer_version` | string | `peer->getVersion()` | `"xrpld-2.4.0"` |
-
-**Rationale**: Transaction relay is where version mismatches cause subtle serialization or validation bugs. Tracing "this tx came from a v2.3.0 peer" helps diagnose compatibility issues. The community dashboard tracks peer versions externally; this brings version awareness into the trace itself.
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-
-**Exit Criteria**:
-
-- [ ] `tx.receive` spans carry `peer_version` attribute with a non-empty version string
-- [ ] Attribute is omitted (not set to empty string) when `getVersion()` returns empty
-- [ ] Attribute visible in Tempo trace detail view
-
----
-
-## Task 3.9: Deterministic Transaction Trace ID
-
-> **Upstream**: Task 3.2 (protobuf serialization), Task 3.3 (PeerImp span exists).
-> **Downstream**: Phase 10 (workload validation can query by tx hash directly).
-> **Pattern**: Mirrors the consensus deterministic trace ID in Phase 4a
-> (`createDeterministicContext` in `RCLConsensus.cpp`), adapted for transactions.
-
-**Objective**: Derive the trace_id for transaction spans deterministically from the
-transaction hash so that all nodes handling the same transaction independently produce
-spans under the same trace_id — regardless of whether protobuf context propagation
-succeeds.
-
-**Why**: The current approach creates spans with random trace_ids and relies entirely
-on protobuf `TraceContext` propagation to link them. If any hop in the relay chain
-drops the context (older peers, message corruption, mixed-version networks), the trace
-splits and downstream spans become impossible to find. With deterministic trace_ids,
-correlation is guaranteed because every node derives the same trace_id from the same
-`txID`.
-
-**Approach — deterministic trace_id + protobuf span_id propagation**:
-
-1. Derive `trace_id = txHash[0:16]` (first 16 bytes of the 32-byte transaction hash).
-2. Generate a random 8-byte `span_id` per node (each node's span is unique within
-   the shared trace).
-3. Create the span under this deterministic context as parent.
-4. **Additionally**, if protobuf `TraceContext` is present in the incoming
-   `TMTransaction` message, extract the sender's `span_id` and use it as the span's
-   parent — this preserves parent-child ordering in the trace tree.
-5. If protobuf context is absent (older peer, first hop), the span still has the
-   correct deterministic `trace_id` — it appears as a sibling root in the same trace
-   rather than being lost.
-
-This gives the best of both worlds: guaranteed cross-node correlation via deterministic
-`trace_id`, plus parent-child relay ordering via protobuf `span_id` when available.
-
-**What to do**:
-
-- Create `createDeterministicTxContext(uint256 const& txHash)` utility function:
-  - Location: shared header or file-local in `PeerImp.cpp` and `NetworkOPs.cpp`
-    (or a shared telemetry utility if both need it).
-  - Pattern: identical to `createDeterministicContext(uint256 const& ledgerId)` in
-    `RCLConsensus.cpp` — take `txHash[0:16]` as trace_id, random span_id via
-    `default_prng()`, sampled flag set, `remote=false`.
-  - Guard behind `#ifdef XRPL_ENABLE_TELEMETRY`.
-
-  ```cpp
-  opentelemetry::context::Context
-  createDeterministicTxContext(uint256 const& txHash)
-  {
-      namespace trace = opentelemetry::trace;
-
-      // First 16 bytes of the 32-byte tx hash as trace ID.
-      trace::TraceId traceId(
-          opentelemetry::nostd::span<uint8_t const, 16>(txHash.data(), 16));
-
-      // Random span_id so each node's span is unique within the trace.
-      uint8_t spanIdBytes[8];
-      auto const rval = default_prng()();
-      std::memcpy(spanIdBytes, &rval, sizeof(spanIdBytes));
-      trace::SpanId spanId(
-          opentelemetry::nostd::span<uint8_t const, 8>(spanIdBytes, 8));
-
-      trace::SpanContext syntheticCtx(
-          traceId, spanId, trace::TraceFlags(1), /* remote = */ false);
-
-      return opentelemetry::context::Context{}.SetValue(
-          trace::kSpanKey,
-          opentelemetry::nostd::shared_ptr<trace::Span>(
-              new trace::DefaultSpan(syntheticCtx)));
-  }
-  ```
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp` — restructure `handleTransaction()`:
-  - **Move span creation after deserialization** (txID must be known first):
-    1. Deserialize `STTx` and get `txID` (existing code at line ~1382).
-    2. Create deterministic parent context: `auto detCtx = createDeterministicTxContext(txID)`.
-    3. If `m->has_trace_context()`: extract protobuf context via `extractFromProtobuf()`,
-       **combine** with deterministic trace_id — use the protobuf span_id as parent
-       to preserve relay ordering, but override trace_id with the deterministic one.
-    4. If no protobuf context: create span under `detCtx` directly.
-    5. Set all existing attributes (`hash`, `peerId`, `peerVersion`, etc.).
-
-  - **Combining deterministic trace_id with protobuf parent span_id**:
-    When both are available, construct a synthetic `SpanContext` with:
-    - `trace_id` = `txHash[0:16]` (deterministic)
-    - `span_id` = extracted from protobuf (sender's span_id → becomes parent)
-    - `trace_flags` = from protobuf
-    - `remote` = true (came from another node)
-
-    ```cpp
-    // Pseudo-code for the combined context:
-    auto detTraceId = trace::TraceId(txHash.data(), 16);
-    auto remoteSpanId = /* from extractFromProtobuf */;
-    auto remoteFlags = /* from extractFromProtobuf */;
-
-    trace::SpanContext combinedCtx(
-        detTraceId, remoteSpanId, remoteFlags, /* remote = */ true);
-    // Use as parent context for the new span.
-    ```
-
-- Edit `src/xrpld/app/misc/NetworkOPs.cpp` — update `processTransaction()`:
-  - `transaction->getID()` is already available at the top of the function.
-  - Create deterministic parent context from `txID`.
-  - Create `tx.process` span under this context.
-  - No protobuf context to extract here (NetworkOPs is intra-node), so
-    deterministic context alone is sufficient.
-
-- Add `trace_strategy` attribute to spans:
-  - Add `inline constexpr auto traceStrategy = "trace_strategy";`
-    to `TxSpanNames.h`.
-  - Set on each tx span: `span.setAttribute(tx_span::attr::traceStrategy, "deterministic")`.
-
-**Key new/modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp` — restructured span creation
-- `src/xrpld/app/misc/NetworkOPs.cpp` — deterministic context for tx.process
-- `src/xrpld/telemetry/TxSpanNames.h` — new `traceStrategy` attribute constant
-- New or shared utility for `createDeterministicTxContext()` (location TBD: could be
-  a shared header like `include/xrpl/telemetry/DeterministicContext.h`, or file-local
-  if only used in two places)
-
-**Interaction with existing tasks**:
-
-- **Task 3.3 (PeerImp instrumentation)**: The span creation in `handleTransaction()`
-  must be restructured — the span currently starts before `txID` is known. This task
-  moves it after deserialization.
-- **Task 3.6 (Relay context propagation)**: Protobuf injection at the relay site
-  remains the same — `injectToProtobuf()` serializes the current span's `span_id`.
-  The receiver extracts it and combines with the deterministic `trace_id`.
-- **Phase 4a (Consensus deterministic trace ID)**: This task follows the same pattern.
-  Consider extracting a shared utility (e.g., `createDeterministicContext(uint256)`)
-  that both consensus and transaction tracing use.
-
-**Exit Criteria**:
-
-- [ ] `tx.receive` and `tx.process` spans have deterministic trace_id = `txHash[0:16]`
-- [ ] All nodes handling the same transaction produce spans under the same trace_id
-- [x] Protobuf `span_id` propagation still works when available (parent-child ordering)
-- [ ] Missing protobuf context (old peer) degrades gracefully to sibling spans, not lost traces
-- [ ] `trace_strategy` attribute set to `"deterministic"` on all tx spans
-- [ ] Trace queryable by tx hash (truncate hash → trace_id → direct lookup in Tempo)
-
-**Deliverables implemented (not in original plan)**:
-
-- **`SpanGuard::txSpan()` factory method** (`include/xrpl/telemetry/SpanGuard.h`):
-  Two overloads for creating transaction spans with deterministic trace IDs:
-  - `txSpan(category, group, name, txHash)` — standalone span (deterministic
-    trace_id from `txHash[0:16]`, no parent span_id).
-  - `txSpan(category, group, name, txHash, parentCtx)` — child span (deterministic
-    trace_id combined with protobuf-extracted parent span_id for relay ordering).
-
-- **`TxTracing.h` helper functions** (`src/xrpld/telemetry/TxTracing.h`):
-  File-local helpers that wrap `SpanGuard::txSpan()` for the two main PeerImp call
-  sites:
-  - `txReceiveSpan(txHash, parentCtx)` — creates `tx.receive` span with
-    deterministic trace_id and optional protobuf parent context.
-  - `txProcessSpan(txHash)` — creates `tx.process` span with deterministic
-    trace_id only (no protobuf parent, used intra-node).
-  - **Note**: `TxTracing.h` includes `xrpl.pb.h` unconditionally (outside
-    `#ifdef XRPL_ENABLE_TELEMETRY`) because `protocol::TMTransaction` appears in
-    the function signatures regardless of telemetry build mode.
-
----
-
-## Task 3.10: TxQ Instrumentation
-
-**Status**: COMPLETE
-
-**Objective**: Trace the transaction queue lifecycle — enqueue decisions, direct apply, batch clear, ledger-close accept loop, per-tx apply, and cleanup.
-
-**Spans added**:
-
-- `txq.enqueue` — wraps `TxQ::apply()` with tx_hash attribute
-- `txq.apply_direct` — wraps `TxQ::tryDirectApply()` fast-path
-- `txq.batch_clear` — wraps `TxQ::tryClearAccountQueueUpThruTx()`
-- `txq.accept` — wraps `TxQ::accept()` ledger-close dequeue with queue_size attr
-- `txq.accept_tx` — per-tx span inside accept loop with tx_hash, ter_code,
-  retries_remaining attributes
-- `txq.cleanup` — wraps `TxQ::processClosedLedger()` with ledger_seq attribute
-
-**New file**: `src/xrpld/app/misc/detail/TxQSpanNames.h`
-
-**Modified file**: `src/xrpld/app/misc/detail/TxQ.cpp`
-
----
-
-## Task 3.11: TX and TxQ Span Attribute Gap Fill
-
-**Status**: COMPLETE
-
-**Objective**: Add workflow-identifying attributes to transaction spans so operators can filter by transaction type and see outcomes without off-chain correlation.
-
-**Attributes added**:
-
-| Span              | Attribute            | Type   | Source                                                                                                                     |
-| ----------------- | -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
-| `tx.process`      | `tx_type`            | string | `TxFormats::getInstance().findByType(stx->getTxnType())->getName()`                                                        |
-| `tx.process`      | `fee`                | int64  | `stx->getFieldAmount(sfFee).xrp().drops()`                                                                                 |
-| `tx.process`      | `sequence`           | int64  | `stx->getSeqProxy().value()`                                                                                               |
-| `tx.process`      | `tx_<account field>` | string | one per top-level `STI_ACCOUNT` field, raw r-address (`tx_account`, `tx_destination`, ...); keys in `TxAccountSpanNames.h` |
-| `tx.process`      | `ter_result`         | string | `transToken(e.result)` (set after batch application)                                                                       |
-| `tx.process`      | `applied`            | bool   | `e.applied` (set after batch application)                                                                                  |
-| `tx.receive`      | `tx_type`            | string | `TxFormats::getInstance().findByType(stx->getTxnType())->getName()`                                                        |
-| `txq.enqueue`     | `tx_type`            | string | same pattern as above                                                                                                      |
-| `txq.enqueue`     | `txq_status`         | string | `queued` / `applied_direct` / `applied` / `failed` / `rejected`                                                            |
-| `txq.enqueue`     | `ter_code`           | string | `transToken(directApplied->ter)` (set on the direct-apply path)                                                            |
-| `txq.enqueue`     | `fee_level_paid`     | int64  | `getFeeLevelPaid(view, *tx).value()`                                                                                       |
-| `txq.enqueue`     | `required_fee_level` | int64  | `getRequiredFeeLevel(...).value()`                                                                                         |
-| `txq.batch_clear` | `num_cleared`        | int64  | queued txs cleared ahead of the applying tx                                                                                |
-| `txq.cleanup`     | `expired_count`      | int64  | entries dropped for passed `LastLedgerSequence`                                                                            |
-| `txq.accept_tx`   | `txq_status`         | string | `applied` / `failed` / `retried`                                                                                           |
-| `txq.accept_tx`   | `ter_code`           | string | `transToken(txnResult)` (set before branching on the outcome)                                                              |
-| `txq.accept`      | `ledger_changed`     | bool   | set at end of accept loop                                                                                                  |
-
-**New attr keys**: `TxSpanNames.h` (`txType`, `fee`, `sequence`, `terResult`, `applied`), `TxQSpanNames.h` (`txType`).
-
-**Modified files**:
-
-- `src/xrpld/telemetry/TxSpanNames.h`
-- `src/xrpld/app/misc/detail/TxQSpanNames.h`
-- `src/xrpld/app/misc/NetworkOPs.cpp`
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-- `src/xrpld/app/misc/detail/TxQ.cpp`
-
----
-
-## Summary
-
-| Task | Description                         | New Files | Modified Files | Depends On |
-| ---- | ----------------------------------- | --------- | -------------- | ---------- |
-| 3.1  | TraceContext protobuf message       | 0         | 1              | Phase 2    |
-| 3.2  | Protobuf context serialization      | 1-2       | 0              | 3.1        |
-| 3.3  | PeerImp transaction instrumentation | 0         | 1              | 3.2        |
-| 3.4  | NetworkOPs transaction processing   | 0         | 1              | Phase 2    |
-| 3.5  | HashRouter dedup visibility         | 0         | 1              | 3.3        |
-| 3.6  | Relay context propagation           | 0         | 1-2            | 3.3, 3.5   |
-| 3.7  | Build verification and testing      | 0         | 0              | 3.1-3.6    |
-| 3.8  | TX span peer version attribute      | 0         | 1              | 3.3        |
-| 3.9  | Deterministic transaction trace ID  | 0-1       | 3              | 3.2, 3.3   |
-| 3.10 | TxQ instrumentation (6 spans)       | 1         | 1              | 3.4        |
-| 3.11 | TX/TxQ span attribute gap fill      | 0         | 5              | 3.3, 3.10  |
-
-**Parallel work**: Tasks 3.1 and 3.4 can start in parallel. Task 3.2 depends on 3.1. Tasks 3.3 and 3.5 depend on 3.2. Task 3.6 depends on 3.3 and 3.5. Task 3.8 depends on 3.3 (span must exist). Task 3.9 depends on 3.2 and 3.3. Task 3.10 depends on 3.4 (tx.process span must exist).
-
-**Exit Criteria** (from [06-implementation-phases.md §6.11.3](./06-implementation-phases.md)):
-
-- [x] Transaction traces span across nodes
-- [x] Trace context in Protocol Buffer messages
-- [ ] HashRouter deduplication visible in traces
-- [ ] <5% overhead on transaction throughput
-- [x] Deterministic trace_id: same trace_id for same tx across all nodes
-- [x] Protobuf span_id propagation preserves parent-child ordering when available
-
----
-
-## Known Issues / Future Work
-
-### Unused trace_state proto field
-
-The `TraceContext.trace_state` field (field 4) in `xrpl.proto` is reserved for
-W3C `tracestate` vendor-specific key-value pairs but is not read or written by
-`TraceContextPropagator`. Wire it when cross-vendor trace propagation is needed.
-No wire cost since proto `optional` fields are zero-cost when absent.

OpenTelemetryPlan/Phase5_IntegrationTest_taskList.md

@@ -1,221 +0,0 @@
-# Phase 5: Integration Test Task List
-
-> **Goal**: End-to-end verification of the complete telemetry pipeline using a
-> 6-node consensus network. Proves that RPC, transaction, and consensus spans
-> flow through the observability stack (otel-collector, Tempo, Prometheus,
-> Grafana) under realistic conditions.
->
-> **Scope**: Integration test script, manual testing plan, 6-node local network
-> setup, Tempo/Prometheus/Grafana verification.
->
-> **Branch**: `pratik/otel-phase5-docs-deployment`
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                  |
-| ---------------------------------------------------------------- | ------------------------------------------ |
-| [07-observability-backends.md](./07-observability-backends.md)   | Tempo, Grafana, Prometheus setup           |
-| [05-configuration-reference.md](./05-configuration-reference.md) | Collector config, Docker Compose           |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 5 tasks, definition of done          |
-| [Phase5_taskList.md](./Phase5_taskList.md)                       | Phase 5 main task list (5.6 = integration) |
-
----
-
-## Task IT.1: Create Integration Test Script
-
-**Objective**: Automated bash script that stands up a 6-node xrpld network
-with telemetry, exercises all span categories, and verifies data in
-Tempo/Prometheus.
-
-**What to do**:
-
-- Create `docker/telemetry/integration-test.sh`:
-  - Prerequisites check (docker, xrpld binary, curl, jq)
-  - Start observability stack via `docker compose`
-  - Generate 6 validator key pairs via temp standalone xrpld
-  - Generate 6 node configs + shared `validators.txt`
-  - Start 6 xrpld nodes in consensus mode (`--start`, no `-a`)
-  - Wait for all nodes to reach `"proposing"` state (120s timeout)
-
-**Key new file**: `docker/telemetry/integration-test.sh`
-
-**Verification**:
-
-- [ ] Script starts without errors
-- [ ] All 6 nodes reach "proposing" state
-- [ ] Observability stack is healthy (otel-collector, Tempo, Prometheus, Grafana)
-
----
-
-## Task IT.2: RPC Span Verification (Phase 2)
-
-**Objective**: Verify RPC spans flow through the telemetry pipeline.
-
-**What to do**:
-
-- Send `server_info`, `server_state`, `ledger` RPCs to node1 (port 5005)
-- Wait for batch export (5s)
-- Query Tempo API for:
-  - `rpc.request` spans (ServerHandler::onRequest)
-  - `rpc.process` spans (ServerHandler::processRequest)
-  - `rpc.command.server_info` spans (callMethod)
-  - `rpc.command.server_state` spans (callMethod)
-  - `rpc.command.ledger` spans (callMethod)
-- Verify `command` attribute present on `rpc.command.*` spans
-
-**Verification**:
-
-- [ ] Tempo shows `rpc.request` traces
-- [ ] Tempo shows `rpc.process` traces
-- [ ] Tempo shows `rpc.command.*` traces with correct attributes
-
----
-
-## Task IT.3: Transaction Span Verification (Phase 3)
-
-**Objective**: Verify transaction spans flow through the telemetry pipeline.
-
-**What to do**:
-
-- Get genesis account sequence via `account_info` RPC
-- Submit Payment transaction using genesis seed (`snoPBrXtMeMyMHUVTgbuqAfg1SUTb`)
-- Wait for consensus inclusion (10s)
-- Query Tempo API for:
-  - `tx.process` spans (NetworkOPsImp::processTransaction) on submitting node
-  - `tx.receive` spans (PeerImp::handleTransaction) on peer nodes
-- Verify `xrpl.tx.hash` attribute on `tx.process` spans
-- Verify `xrpl.peer.id` attribute on `tx.receive` spans
-
-**Verification**:
-
-- [ ] Tempo shows `tx.process` traces with `xrpl.tx.hash`
-- [ ] Tempo shows `tx.receive` traces with `xrpl.peer.id`
-
----
-
-## Task IT.4: Consensus Span Verification (Phase 4)
-
-**Objective**: Verify consensus spans flow through the telemetry pipeline.
-
-**What to do**:
-
-- Consensus runs automatically in 6-node network
-- Query Tempo API for:
-  - `consensus.proposal.send` (Adaptor::propose)
-  - `consensus.ledger_close` (Adaptor::onClose)
-  - `consensus.accept` (Adaptor::onAccept)
-  - `consensus.validation.send` (Adaptor::validate)
-- Verify attributes:
-  - `xrpl.consensus.mode` on `consensus.ledger_close`
-  - `proposers` on `consensus.accept`
-  - `xrpl.consensus.ledger.seq` on `consensus.validation.send`
-
-**Verification**:
-
-- [ ] Tempo shows `consensus.ledger_close` traces with `xrpl.consensus.mode`
-- [ ] Tempo shows `consensus.accept` traces with `proposers`
-- [ ] Tempo shows `consensus.proposal.send` traces
-- [ ] Tempo shows `consensus.validation.send` traces
-
----
-
-## Task IT.5: Spanmetrics Verification (Phase 5)
-
-**Objective**: Verify spanmetrics connector derives RED metrics from spans.
-
-**What to do**:
-
-- Query Prometheus for `traces_span_metrics_calls_total`
-- Query Prometheus for `traces_span_metrics_duration_milliseconds_count`
-- Verify Grafana loads at `http://localhost:3000`
-
-**Verification**:
-
-- [ ] Prometheus returns non-empty results for `traces_span_metrics_calls_total`
-- [ ] Prometheus returns non-empty results for duration histogram
-- [ ] Grafana UI accessible with dashboards visible
-
----
-
-## Task IT.6: Manual Testing Plan
-
-**Objective**: Document how to run tests manually for future reference.
-
-**What to do**:
-
-- Create `docker/telemetry/TESTING.md` with:
-  - Prerequisites section
-  - Single-node standalone test (quick verification)
-  - 6-node consensus test (full verification)
-  - Expected span catalog (all 11 span names with attributes)
-  - Verification queries (Tempo API, Prometheus API)
-  - Troubleshooting guide
-
-**Key new file**: `docker/telemetry/TESTING.md`
-
-**Verification**:
-
-- [ ] Document covers both single-node and multi-node testing
-- [ ] All 11 span names documented with source file and attributes
-- [ ] Troubleshooting section covers common failure modes
-
----
-
-## Task IT.7: Run and Verify
-
-**Objective**: Execute the integration test and validate results.
-
-**What to do**:
-
-- Run `docker/telemetry/integration-test.sh` locally
-- Debug any failures
-- Leave stack running for manual verification
-- Share URLs:
-  - Tempo: `http://localhost:3200`
-  - Grafana: `http://localhost:3000`
-  - Prometheus: `http://localhost:9090`
-
-**Verification**:
-
-- [ ] Script completes with all checks passing
-- [ ] Tempo UI shows xrpld service with all expected span names
-- [ ] Grafana dashboards load and show data
-
----
-
-## Task IT.8: Commit
-
-**Objective**: Commit all new files to Phase 5 branch.
-
-**What to do**:
-
-- Run `pcc` (pre-commit checks)
-- Commit 3 new files to `pratik/otel-phase5-docs-deployment`
-
-**Verification**:
-
-- [ ] `pcc` passes
-- [ ] Commit created on Phase 5 branch
-
----
-
-## Summary
-
-| Task | Description                   | New Files | Depends On |
-| ---- | ----------------------------- | --------- | ---------- |
-| IT.1 | Integration test script       | 1         | Phase 5    |
-| IT.2 | RPC span verification         | 0         | IT.1       |
-| IT.3 | Transaction span verification | 0         | IT.1       |
-| IT.4 | Consensus span verification   | 0         | IT.1       |
-| IT.5 | Spanmetrics verification      | 0         | IT.1       |
-| IT.6 | Manual testing plan           | 1         | --         |
-| IT.7 | Run and verify                | 0         | IT.1-IT.6  |
-| IT.8 | Commit                        | 0         | IT.7       |
-
-**Exit Criteria**:
-
-- [ ] All 6 xrpld nodes reach "proposing" state
-- [ ] All 11 expected span names visible in Tempo
-- [ ] Spanmetrics available in Prometheus
-- [ ] Grafana dashboards show data
-- [ ] Manual testing plan document complete

OpenTelemetryPlan/Phase5_taskList.md

@@ -1,250 +0,0 @@
-# Phase 5: Documentation & Deployment Task List
-
-> **Goal**: Production readiness — Grafana dashboards, spanmetrics pipeline, operator runbook, alert definitions, and final integration testing. This phase ensures the telemetry system is useful and maintainable in production.
->
-> **Scope**: Grafana dashboard definitions, OTel Collector spanmetrics connector, Prometheus integration, alert rules, operator documentation, and production-ready Docker Compose stack.
->
-> **Branch**: `pratik/otel-phase5-docs-deployment` (from `pratik/otel-phase4-consensus-tracing`)
-
-> **Note on attribute names**: the `xrpl.<domain>.<field>` keys shown below
-> (including the collector spanmetrics dimension examples) are written in the
-> older dotted form for readability — it mirrors how the fully qualified
-> attribute reads in a Tempo trace view. The implemented keys follow the
-> convention in [CONTRIBUTING.md](../CONTRIBUTING.md#telemetry-span-attribute-naming)
-> (underscore form, e.g. `command`, `rpc_status`); the `*SpanNames.h` constants
-> are the single source of truth, and the real collector dimensions must use
-> those exact underscore keys (the CI naming check enforces this).
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                                                  |
-| ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| [07-observability-backends.md](./07-observability-backends.md)   | Tempo setup (§7.1), Grafana dashboards (§7.6), alerts (§7.6.3)             |
-| [05-configuration-reference.md](./05-configuration-reference.md) | Collector config (§5.5), production config (§5.5.2), Docker Compose (§5.6) |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 5 tasks (§6.6), definition of done (§6.11.5)                         |
-
----
-
-## Task 5.1: Add Spanmetrics Connector to OTel Collector
-
-**Objective**: Derive RED metrics (Rate, Errors, Duration) from trace spans automatically, enabling Grafana time-series dashboards.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Add `spanmetrics` connector:
-    ```yaml
-    connectors:
-      spanmetrics:
-        histogram:
-          explicit:
-            buckets: [1ms, 5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 5s]
-        dimensions:
-          - name: command
-          - name: rpc_status
-          - name: consensus_phase
-          - name: tx_type
-    ```
-  - Add `prometheus` exporter:
-    ```yaml
-    exporters:
-      prometheus:
-        endpoint: 0.0.0.0:8889
-    ```
-  - Wire the pipeline:
-    ```yaml
-    service:
-      pipelines:
-        traces:
-          receivers: [otlp]
-          processors: [batch]
-          exporters: [debug, otlp/tempo, spanmetrics]
-        metrics:
-          receivers: [spanmetrics]
-          exporters: [prometheus]
-    ```
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Expose port `8889` on the collector for Prometheus scraping
-  - Add Prometheus service
-  - Add Prometheus as Grafana datasource
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
-**Key new files**:
-
-- `docker/telemetry/prometheus.yml` (Prometheus scrape config)
-- `docker/telemetry/grafana/provisioning/datasources/prometheus.yaml`
-
-**Reference**:
-
-- [POC_taskList.md §Next Steps](./POC_taskList.md) — Metrics pipeline for Grafana dashboards
-
----
-
-## Task 5.2: Create Grafana Dashboards
-
-**Objective**: Provide pre-built Grafana dashboards for RPC performance, transaction lifecycle, and consensus health.
-
-**What to do**:
-
-- Create `docker/telemetry/grafana/provisioning/dashboards/dashboards.yaml` (provisioning config)
-- Create dashboard JSON files:
-  1. **RPC Performance Dashboard** (`rpc-performance.json`):
-     - RPC request latency (p50/p95/p99) by command — histogram panel
-     - RPC throughput (requests/sec) by command — time series
-     - RPC error rate by command — bar gauge
-     - Top slowest RPC commands — table
-
-  2. **Transaction Overview Dashboard** (`transaction-overview.json`):
-     - Transaction processing rate — time series
-     - Transaction latency distribution — histogram
-     - Suppression rate (duplicates) — stat panel
-     - Transaction processing path (sync vs async) — pie chart
-
-  3. **Consensus Health Dashboard** (`consensus-health.json`):
-     - Consensus round duration — time series
-     - Phase duration breakdown (open/establish/accept) — stacked bar
-     - Proposals sent/received per round — stat panel
-     - Consensus mode distribution (proposing/observing) — pie chart
-
-- Store dashboards in `docker/telemetry/grafana/dashboards/`
-
-**Key new files**:
-
-- `docker/telemetry/grafana/provisioning/dashboards/dashboards.yaml`
-- `docker/telemetry/grafana/dashboards/rpc-performance.json`
-- `docker/telemetry/grafana/dashboards/transaction-overview.json`
-- `docker/telemetry/grafana/dashboards/consensus-health.json`
-
-**Reference**:
-
-- [07-observability-backends.md §7.6](./07-observability-backends.md) — Grafana dashboard specifications
-- [01-architecture-analysis.md §1.8.3](./01-architecture-analysis.md) — Dashboard panel examples
-
----
-
-## Task 5.3: Define Alert Rules
-
-**Objective**: Create alert definitions for key telemetry anomalies.
-
-**What to do**:
-
-- Create `docker/telemetry/grafana/provisioning/alerting/alerts.yaml`:
-  - **RPC Latency Alert**: p99 latency > 1s for any command over 5 minutes
-  - **RPC Error Rate Alert**: Error rate > 5% for any command over 5 minutes
-  - **Consensus Duration Alert**: Round duration > 10s (warn), > 30s (critical)
-  - **Transaction Processing Alert**: Processing rate drops below threshold
-  - **Telemetry Pipeline Health**: No spans received for > 2 minutes
-
-**Key new files**:
-
-- `docker/telemetry/grafana/provisioning/alerting/alerts.yaml`
-
-**Reference**:
-
-- [07-observability-backends.md §7.6.3](./07-observability-backends.md) — Alert rule definitions
-
----
-
-## Task 5.4: Production Collector Configuration
-
-**Objective**: Create a production-ready OTel Collector configuration with tail-based sampling and resource limits.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-collector-config-production.yaml`:
-  - Tail-based sampling policy:
-    - Always sample errors and slow traces
-    - 10% base sampling rate for normal traces
-    - Always sample first trace for each unique RPC command
-  - Resource limits:
-    - Memory limiter processor (80% of available memory)
-    - Queued retry for export failures
-  - TLS configuration for production endpoints
-  - Health check endpoint
-
-**Key new files**:
-
-- `docker/telemetry/otel-collector-config-production.yaml`
-
-**Reference**:
-
-- [05-configuration-reference.md §5.5.2](./05-configuration-reference.md) — Production collector config
-
----
-
-## Task 5.5: Operator Runbook
-
-**Objective**: Create operator documentation for managing the telemetry system in production.
-
-**What to do**:
-
-- Create `docs/telemetry-runbook.md`:
-  - **Setup**: How to enable telemetry in xrpld
-  - **Configuration**: All config options with descriptions
-  - **Collector Deployment**: Docker Compose vs. Kubernetes vs. bare metal
-  - **Troubleshooting**: Common issues and resolutions
-    - No traces appearing
-    - High memory usage from telemetry
-    - Collector connection failures
-    - Sampling configuration tuning
-  - **Performance Tuning**: Batch size, queue size, sampling ratio guidelines
-  - **Upgrading**: How to upgrade OTel SDK and Collector versions
-
-**Key new files**:
-
-- `docs/telemetry-runbook.md`
-
----
-
-## Task 5.6: Final Integration Testing
-
-**Objective**: Validate the complete telemetry stack end-to-end.
-
-**What to do**:
-
-1. Start full Docker stack (Collector, Tempo, Grafana, Prometheus)
-2. Build xrpld with `telemetry=ON`
-3. Run in standalone mode with telemetry enabled
-4. Generate RPC traffic and verify traces in Tempo
-5. Verify dashboards populate in Grafana
-6. Verify alerts trigger correctly
-7. Test telemetry OFF path (no regressions)
-8. Run full test suite
-
-**Verification Checklist**:
-
-- [ ] Docker stack starts without errors
-- [ ] Traces appear in Tempo with correct hierarchy
-- [ ] Grafana dashboards show metrics derived from spans
-- [ ] Prometheus scrapes spanmetrics successfully
-- [ ] Alerts can be triggered by simulated conditions
-- [ ] Build succeeds with telemetry ON and OFF
-- [ ] Full test suite passes
-
----
-
-## Summary
-
-| Task | Description                        | New Files | Modified Files | Depends On |
-| ---- | ---------------------------------- | --------- | -------------- | ---------- |
-| 5.1  | Spanmetrics connector + Prometheus | 2         | 2              | Phase 4    |
-| 5.2  | Grafana dashboards                 | 4         | 0              | 5.1        |
-| 5.3  | Alert definitions                  | 1         | 0              | 5.1        |
-| 5.4  | Production collector config        | 1         | 0              | Phase 4    |
-| 5.5  | Operator runbook                   | 1         | 0              | Phase 4    |
-| 5.6  | Final integration testing          | 0         | 0              | 5.1-5.5    |
-
-**Parallel work**: Tasks 5.1, 5.4, and 5.5 can run in parallel. Tasks 5.2 and 5.3 depend on 5.1. Task 5.6 depends on all others.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.11.5](./06-implementation-phases.md)):
-
-- [ ] Dashboards deployed and showing data
-- [ ] Alerts configured and tested
-- [ ] Operator documentation complete
-- [ ] Production collector config ready
-- [ ] Full test suite passes

OpenTelemetryPlan/Phase7_taskList.md

@@ -1,599 +0,0 @@
-# Phase 7: Native OTel Metrics Migration — Task List
-
-> **Goal**: Replace `StatsDCollector` with a native OpenTelemetry Metrics SDK implementation behind the existing `beast::insight::Collector` interface, eliminating the StatsD UDP dependency.
->
-> **Scope**: New `OTelCollectorImpl` class, `CollectorManager` config change, OTel Collector pipeline update, Grafana dashboard metric name migration, integration tests.
->
-> **Branch**: `pratik/otel-phase7-native-metrics` (from `pratik/otel-phase6-statsd`)
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 7 plan: motivation, architecture, exit criteria (§6.8)    |
-| [02-design-decisions.md](./02-design-decisions.md)                   | Collector interface design, beast::insight coexistence strategy |
-| [05-configuration-reference.md](./05-configuration-reference.md)     | `[insight]` and `[telemetry]` config sections                   |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Complete metric inventory that must be preserved                |
-
----
-
-## Task 7.1: Add OTel Metrics SDK to Build Dependencies
-
-**Objective**: Enable the OTel C++ Metrics SDK components in the build system.
-
-**What to do**:
-
-- Edit `conanfile.py`:
-  - Add OTel metrics SDK components to the dependency list when `telemetry=True`
-  - Components needed: `opentelemetry-cpp::metrics`, `opentelemetry-cpp::otlp_http_metric_exporter`
-
-- Edit `CMakeLists.txt` (telemetry section):
-  - Link `opentelemetry::metrics` and `opentelemetry::otlp_http_metric_exporter` targets
-
-**Key modified files**:
-
-- `conanfile.py`
-- `CMakeLists.txt` (or the relevant telemetry cmake target)
-
-**Reference**: [05-configuration-reference.md §5.3](./05-configuration-reference.md) — CMake integration
-
----
-
-## Task 7.2: Implement OTelCollector Class
-
-**Objective**: Create the core `OTelCollector` implementation that maps beast::insight instruments to OTel Metrics SDK instruments.
-
-**What to do**:
-
-- Create `include/xrpl/beast/insight/OTelCollector.h`:
-  - Public factory: `static std::shared_ptr<OTelCollector> New(std::string const& endpoint, std::string const& prefix, beast::Journal journal)`
-  - Derives from `StatsDCollector` (or directly from `Collector` — TBD based on shared code)
-
-- Create `src/libxrpl/beast/insight/OTelCollector.cpp` (~400-500 lines):
-  - **OTelCounterImpl**: Wraps `opentelemetry::metrics::Counter<int64_t>`. `increment(amount)` calls `counter->Add(amount)`.
-  - **OTelGaugeImpl**: Uses `opentelemetry::metrics::ObservableGauge<uint64_t>` with an async callback. `set(value)` stores value atomically; callback reads it during collection.
-  - **OTelMeterImpl**: Wraps `opentelemetry::metrics::Counter<uint64_t>`. `increment(amount)` calls `counter->Add(amount)`. Semantically identical to Counter but unsigned.
-  - **OTelEventImpl**: Wraps `opentelemetry::metrics::Histogram<double>`. `notify()` calls `histogram->Record(value.count())`. Declares its unit from `beast::insight::Unit`, which is what selects its bucket ladder: the histogram views in `Telemetry.cpp` match on unit, so a `ms` instrument gets the millisecond ladder and a `By` instrument the byte ladder. Bucket edges live in `include/xrpl/telemetry/HistogramBuckets.h` — do not restate them here. The millisecond ladder must contain every representable edge of the collector's spanmetrics ladder and may extend above it (jobs outlive spans); `.github/scripts/telemetry/check_bucket_parity.py` enforces that. An earlier version of this line specified `[1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000] ms` as "matching SpanMetrics" — true when written, then silently false once the collector ladder was extended on its own, which capped every quantile above 5s at a flat 5000.
-  - **OTelHookImpl**: Stores handler function. Called during periodic metric collection (same 1s pattern via PeriodicMetricReader).
-  - **OTelCollectorImp**: Main class.
-    - Creates `MeterProvider` with `PeriodicMetricReader` (1s export interval)
-    - Creates `OtlpHttpMetricExporter` pointing to `[telemetry]` endpoint
-    - Sets resource attributes (service.name, service.instance.id) matching trace exporter
-    - Implements all `make_*()` factory methods
-    - Prefixes metric names with `[insight] prefix=` value
-
-- Guard all OTel SDK includes with `#ifdef XRPL_ENABLE_TELEMETRY` to compile to `NullCollector` equivalents when telemetry disabled.
-
-**Key new files**:
-
-- `include/xrpl/beast/insight/OTelCollector.h`
-- `src/libxrpl/beast/insight/OTelCollector.cpp`
-
-**Key patterns to follow**:
-
-- Match `StatsDCollector.cpp` structure: private impl classes, intrusive list for metrics, strand-based thread safety
-- Match existing telemetry code style from `src/libxrpl/telemetry/Telemetry.cpp`
-- Use RAII for MeterProvider lifecycle (shutdown on destructor)
-
-**Reference**: [03-implementation-strategy.md](./03-implementation-strategy.md) —
-code style and patterns (`04-code-samples.md` was deleted by `d6450631bf`)
-
----
-
-## Task 7.3: Update CollectorManager
-
-**Objective**: Add `server=otel` config option to route metric creation to the new OTel backend.
-
-**What to do**:
-
-- Edit `src/xrpld/app/main/CollectorManager.cpp`:
-  - In the constructor, add a third branch after `server == "statsd"`:
-    ```cpp
-    else if (server == "otel")
-    {
-        // Read endpoint from [telemetry] section
-        auto const endpoint = get(telemetryParams, "endpoint",
-            "http://localhost:4318/v1/metrics");
-        std::string const& prefix(get(params, "prefix"));
-        collector_ = beast::insight::OTelCollector::New(
-            endpoint, prefix, journal);
-    }
-    ```
-  - This requires access to the `[telemetry]` config section — may need to pass it as a parameter or read from Application config.
-
-- Edit `src/xrpld/app/main/CollectorManager.h`:
-  - Add `#include <xrpl/beast/insight/OTelCollector.h>`
-
-**Key modified files**:
-
-- `src/xrpld/app/main/CollectorManager.cpp`
-- `src/xrpld/app/main/CollectorManager.h`
-
----
-
-## Task 7.4: Update OTel Collector Configuration
-
-**Objective**: Add a metrics pipeline to the OTLP receiver and remove the StatsD receiver dependency.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Remove `statsd` receiver (no longer needed when `server=otel`)
-  - Add metrics pipeline under `service.pipelines`:
-    ```yaml
-    metrics:
-      receivers: [otlp, spanmetrics]
-      processors: [batch]
-      exporters: [prometheus]
-    ```
-  - The OTLP receiver already listens on :4318 — it just needs to be added to the metrics pipeline receivers.
-  - Keep `spanmetrics` connector in the metrics pipeline so span-derived RED metrics continue working.
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Remove UDP :8125 port mapping from otel-collector service
-  - Update xrpld service config: change `[insight] server=statsd` to `server=otel`
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
-**Note**: Keep a commented-out `statsd` receiver block for operators who need backward compatibility.
-
----
-
-## Task 7.5: Pin Down Metric Names in Prometheus
-
-**Objective**: Fix the exported name of every beast::insight instrument, and point the Grafana dashboards at those names.
-
-**What to do**:
-
-- In `OTelCollector.cpp`, `formatName()` derives the OTel instrument name from the group and name beast::insight was given:
-  - beast::insight `makeGauge("LedgerMaster", "Validated_Ledger_Age")` → OTel instrument name: `ledgermaster_validated_ledger_age`
-  - `Groups` joins group and name with `.`; `formatName()` then lowercases and maps `.` and space to `_`
-  - No prefix is applied on this path. The service is identified by the `service.name` resource attribute, so `[insight] prefix` reaches only the startup log line
-
-- Verify in integration test that key Prometheus queries still return data:
-  - `ledgermaster_validated_ledger_age`
-  - `peer_finder_active_inbound_peers`
-  - `rpc_requests_total`
-
-**Key consideration**: OTel Prometheus exporter may normalize metric names differently than StatsD receiver. Test this early (Task 7.2) and adjust naming strategy if needed. The OTel SDK's Prometheus exporter adds `_total` suffix to counters and converts dots to underscores — match existing conventions.
-
----
-
-## Task 7.6: Update Grafana Dashboards
-
-**Objective**: Update the 3 StatsD dashboards if any metric names change due to OTLP export format differences.
-
-**What to do**:
-
-- If Task 7.5 confirms metric names are preserved exactly, no dashboard changes needed.
-- If OTLP export produces different names (e.g., `_total` suffix on counters), update:
-  - `docker/telemetry/grafana/dashboards/statsd-node-health.json`
-  - `docker/telemetry/grafana/dashboards/statsd-network-traffic.json`
-  - `docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json`
-- Rename dashboard titles from "StatsD" to "System Metrics" or similar (since they're no longer StatsD-sourced).
-
-**Key modified files**:
-
-- `docker/telemetry/grafana/dashboards/statsd-*.json` (3 files, conditionally)
-
----
-
-## Task 7.7: Update Integration Tests
-
-**Objective**: Verify the full OTLP metrics pipeline end-to-end.
-
-**What to do**:
-
-- Edit `docker/telemetry/integration-test.sh`:
-  - Update test config to use `[insight] server=otel`
-  - Verify metrics arrive in Prometheus via OTLP (not StatsD)
-  - Add check that StatsD receiver is no longer required
-  - Preserve all existing metric presence checks
-
-**Key modified files**:
-
-- `docker/telemetry/integration-test.sh`
-
----
-
-## Task 7.8: Update Documentation
-
-**Objective**: Update all plan docs, runbook, and reference docs to reflect the migration.
-
-**What to do**:
-
-- Edit `docs/telemetry-runbook.md`:
-  - Update `[insight]` config examples to show `server=otel`
-  - Update troubleshooting section (no more StatsD UDP debugging)
-
-- Edit `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Update Data Flow Overview diagram (remove StatsD receiver)
-  - Update Section 2 header from "StatsD Metrics" to "System Metrics (OTel native)"
-  - Update config examples
-
-- Edit `OpenTelemetryPlan/05-configuration-reference.md`:
-  - Add `server=otel` option to `[insight]` section docs
-
-- Edit `docker/telemetry/TESTING.md`:
-  - Update setup instructions to use `server=otel`
-
-**Key modified files**:
-
-- `docs/telemetry-runbook.md`
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `OpenTelemetryPlan/05-configuration-reference.md`
-- `docker/telemetry/TESTING.md`
-
----
-
-## Task 7.9: ValidationTracker — Validation Agreement Computation
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — the most valuable metric from the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 4 Task 4.8 (validation span attributes provide ledger hash context).
-> **Downstream**: Phase 9 (Validator Health dashboard), Phase 10 (validation checks), Phase 11 (agreement alert rules).
-
-**Objective**: Implement a stateful class that tracks whether our validator's validations agree with network consensus, maintaining rolling 1h and 24h windows with an 8-second grace period and 5-minute late repair window.
-
-**Architecture**:
-
-```
-consensus.validation.send ────> ValidationTracker ────> MetricsRegistry
-(records our validation         (reconciles after       (exports agreement
- for ledger X)                   8s grace period)        gauges every 10s)
-
-ledger.validate ──────────────> ValidationTracker
-(records which ledger           (marks ledger X as
- network validated)              agreed or missed)
-```
-
-**What to do**:
-
-- Create `src/xrpld/telemetry/ValidationTracker.h`:
-  - `recordOurValidation(ledgerHash, ledgerSeq)` — called when we send a validation
-  - `recordNetworkValidation(ledgerHash, seq)` — called when a ledger is fully validated
-  - `reconcile()` — called periodically; reconciles pending ledger events after 8s grace period
-  - Getters: `agreementPct1h()`, `agreementPct24h()`, `agreements1h()`, `missed1h()`, `agreements24h()`, `missed24h()`, `totalAgreements()`, `totalMissed()`, `totalValidationsSent()`, `totalValidationsChecked()`
-  - Thread-safety: atomics for counters, mutex for window deques
-
-- Create `src/xrpld/telemetry/detail/ValidationTracker.cpp`:
-  - Reconciliation logic: after 8s grace period, check if `weValidated && networkValidated && sameHash` → agreement; else missed
-  - Late repair: if a late validation arrives within 5 minutes, correct a false-positive miss
-  - Sliding window: `std::deque<WindowEvent>` evicts entries older than 1h/24h on each reconciliation pass
-  - Ring buffer of 1000 `LedgerEvent` structs for pending reconciliation
-
-- Add recording hooks (modifying Phase 4 code from Phase 7 branch):
-  - `RCLConsensus.cpp` `validate()`: call `tracker.recordOurValidation()`
-  - `LedgerMaster.cpp` fully-validated path: call `tracker.recordNetworkValidation()`
-
-**Key data structures**:
-
-```cpp
-struct LedgerEvent {
-    uint256 ledgerHash;
-    LedgerIndex seq;
-    TimePoint closeTime;
-    bool weValidated = false;
-    bool networkValidated = false;
-    bool reconciled = false;
-    bool agreed = false;
-};
-
-struct WindowEvent {
-    TimePoint time;
-    bool agreed;
-};
-```
-
-**Key new files**:
-
-- `src/xrpld/telemetry/ValidationTracker.h`
-- `src/xrpld/telemetry/detail/ValidationTracker.cpp`
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.h` (add ValidationTracker member)
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add gauge callback reading from tracker)
-- `src/xrpld/app/consensus/RCLConsensus.cpp` (add recording hooks)
-- `src/xrpld/app/ledger/detail/LedgerMaster.cpp` (add recording hook)
-
-**Exit Criteria**:
-
-- [ ] ValidationTracker correctly tracks agreement with 8s grace period
-- [ ] 5-minute late repair corrects false-positive misses
-- [ ] Thread-safe (atomics + mutex for window deques)
-- [ ] Rolling windows correctly evict stale entries
-- [ ] Unit tests: normal agreement, missed validation, late repair, window eviction
-
----
-
-## Task 7.10: Validator Health Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export amendment blocked, UNL health, and quorum data as a native OTel observable gauge.
-
-**What to do**:
-
-- In `MetricsRegistry.cpp` `registerAsyncGauges()`, add:
-
-```cpp
-validatorHealthGauge_ = meter_->CreateDoubleObservableGauge(
-    "validator_health", "Validator health indicators");
-```
-
-**Gauge label values**:
-
-| Label `metric=`     | Type   | Source                                            |
-| ------------------- | ------ | ------------------------------------------------- |
-| `amendment_blocked` | int64  | `app_.getOPs().isAmendmentBlocked()` → 0/1        |
-| `unl_blocked`       | int64  | `app_.getOPs().isUNLBlocked()` → 0/1              |
-| `unl_expiry_days`   | double | `app_.validators().expires()` → days until expiry |
-| `validation_quorum` | int64  | `app_.validators().quorum()`                      |
-
-### Sub-task 7.10a: Per-Validator Validation Count (Flag Ledger Window)
-
-**Objective**: Track how many ledgers each UNL validator has validated over
-the last 256 consecutive ledgers (one flag ledger window). This is the key
-UNL participation metric — validators consistently below threshold may be
-candidates for removal from the UNL.
-
-**What to do**:
-
-- Add a new observable gauge:
-
-```cpp
-validatorParticipationGauge_ = meter_->CreateInt64ObservableGauge(
-    "validator_participation",
-    "Per-validator validation count over the last 256 ledgers");
-```
-
-- The callback queries `app_.getValidations()` to get the trusted
-  validation set for each of the last 256 ledger hashes (from
-  `LedgerMaster::getValidatedLedger()` walking backwards). For each
-  validator public key in the UNL, count how many of those 256 ledgers
-  have a matching validation.
-
-- **Label dimensions**:
-  - `validator` — base58-encoded validator master public key
-  - `service_instance_id` — this node's identity (standard)
-
-- **Emission**: every flag ledger (256 ledgers, ~15 minutes) or on a
-  10-second async gauge callback with cached results (recompute only
-  at flag ledger boundaries).
-
-- **Data source**: `RCLValidations::getTrustedForLedger(hash, seq)` returns
-  `std::vector<std::shared_ptr<STValidation>>` with `getSignerPublic()`
-  for each. The UNL list is from `app_.getValidators().getTrustedMasterKeys()`.
-
-- **Dashboard panel**: Add a table panel to the Validator Health dashboard
-  showing `validator_participation` grouped by `validator` label,
-  with a threshold color (green >= 240, yellow >= 200, red < 200).
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] Gauge emits one time series per UNL validator
-- [ ] Values range 0-256 and update at flag ledger boundaries
-- [ ] Grafana table panel shows per-validator participation
-- [ ] Validators below 75% participation are highlighted in red
-
----
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] All 4 base label values emitted every 10s
-- [ ] `unl_expiry_days` is negative when expired, positive when active
-- [ ] Per-validator participation gauge emits at flag ledger boundaries
-- [ ] Values visible in Prometheus
-
----
-
-## Task 7.11: Peer Quality Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export peer health aggregates (latency P90, insane peers, version awareness) as a native OTel observable gauge.
-
-**What to do**:
-
-- In `MetricsRegistry.cpp` `registerAsyncGauges()`, add a callback that iterates `app_.overlay().foreach(...)` to:
-  - Collect per-peer latency values, sort, compute P90
-  - Count peers with `tracking_ == diverged` (insane)
-  - Compare peer `getVersion()` to own version for upgrade awareness
-
-**Gauge label values**:
-
-| Label `metric=`            | Type   | Source                                |
-| -------------------------- | ------ | ------------------------------------- |
-| `peer_latency_p90_ms`      | double | P90 from sorted peer latencies        |
-| `peers_insane_count`       | int64  | Peers with diverged tracking status   |
-| `peers_higher_version_pct` | double | % of peers on newer xrpld version     |
-| `upgrade_recommended`      | int64  | 1 if `peers_higher_version_pct > 60%` |
-
-**Implementation note**: The callback runs every 10s on the metrics reader thread. Iterating ~50-200 peers is acceptable overhead.
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] P90 latency computed correctly
-- [ ] Insane count matches `peers` RPC output
-- [ ] Version comparison handles format variations (e.g., "xrpld-2.4.0-rc1")
-
----
-
-## Task 7.12: Ledger Economy Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export fee, reserve, ledger age, and transaction rate as a native OTel observable gauge.
-
-**Gauge label values**:
-
-| Label `metric=`      | Type   | Source                                              |
-| -------------------- | ------ | --------------------------------------------------- |
-| `base_fee_xrp`       | double | Base fee from validated ledger fee settings (drops) |
-| `reserve_base_xrp`   | double | Account reserve from validated ledger (drops)       |
-| `reserve_inc_xrp`    | double | Owner reserve increment (drops)                     |
-| `ledger_age_seconds` | double | `now - lastValidatedCloseTime`                      |
-| `transaction_rate`   | double | Derived: tx count delta / time delta (smoothed)     |
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] Fee values match `server_info` RPC output
-- [ ] `ledger_age_seconds` increases monotonically between ledger closes
-- [ ] `transaction_rate` is smoothed (rolling average)
-
----
-
-## Task 7.13: State Tracking Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export extended state value (0-6 encoding combining OperatingMode + ConsensusMode) and time-in-current-state.
-
-**Gauge label values**:
-
-| Label `metric=`                 | Type   | Source                                          |
-| ------------------------------- | ------ | ----------------------------------------------- |
-| `state_value`                   | int64  | 0-6 encoding (see spec for mapping)             |
-| `time_in_current_state_seconds` | double | `now - lastModeChangeTime` from StateAccounting |
-
-**State value encoding**: 0=disconnected, 1=connected, 2=syncing, 3=tracking, 4=full, 5=validating (full + validating), 6=proposing (full + proposing).
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] `state_value` correctly combines OperatingMode and ConsensusMode
-- [ ] `time_in_current_state_seconds` resets on mode change
-
----
-
-## Task 7.14: Storage Detail and Sync Info Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export the NodeStore stored-bytes total and initial sync duration.
-
-**Gauge label values**:
-
-| Gauge Name       | Label `metric=`                 | Type   | Source                                               |
-| ---------------- | ------------------------------- | ------ | ---------------------------------------------------- |
-| `storage_detail` | `stored_object_bytes`           | int64  | `Database::getStoreSize()` — cumulative object bytes |
-| `sync_info`      | `initial_sync_duration_seconds` | double | Time from start to first FULL                        |
-
-`stored_object_bytes` is not a file size. `getStoreSize()` sums the object payloads
-this process has written, so it excludes NuDB's keys, bucket padding and log, and it
-resets when the process restarts while the files on disk do not. It is the same
-accessor `node_written_bytes` uses, so the two series are equal by construction and
-any write-amplification ratio built from the pair is a constant 1.0. Neither
-`Backend` nor `Database` exposes a file-size accessor, so no metric reports the
-store's on-disk size today.
-
-This label value was `nudb_bytes` when Phase 7 shipped it and was renamed in Phase 9,
-because the value comes from `Database` rather than the NuDB backend.
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] Cumulative stored object bytes reported (0 if NuDB not configured)
-- [ ] Sync duration captured once and remains stable after reaching FULL
-
----
-
-## Task 7.15: New Synchronous Counters
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Add 7 new event counters incremented at their respective instrumentation sites.
-
-| Counter Name                  | Increment Site                   | Source File           |
-| ----------------------------- | -------------------------------- | --------------------- |
-| `ledgers_closed_total`        | `onAccept()` in consensus        | RCLConsensus.cpp      |
-| `validations_sent_total`      | `validate()` in consensus        | RCLConsensus.cpp      |
-| `validations_checked_total`   | Network validation received      | LedgerMaster.cpp      |
-| `validation_agreements_total` | ValidationTracker reconciliation | ValidationTracker.cpp |
-| `validation_missed_total`     | ValidationTracker reconciliation | ValidationTracker.cpp |
-| `state_changes_total`         | `setMode()` in NetworkOPs        | NetworkOPs.cpp        |
-| `jq_trans_overflow_total`     | Job queue overflow path          | JobQueue.cpp          |
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp` (declarations), plus recording sites in RCLConsensus.cpp, LedgerMaster.cpp, NetworkOPs.cpp, JobQueue.cpp
-
-**Exit Criteria**:
-
-- [ ] All 7 counters monotonically increase during normal operation
-- [ ] Counter values match expected rates (e.g., ledgers_closed ≈ 1 per 3-5s)
-
----
-
-## Task 7.16: Validation Agreement Observable Gauge
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export rolling window agreement stats from `ValidationTracker` (Task 7.9).
-
-**Gauge label values**:
-
-| Gauge Name             | Label `metric=`     | Type   | Source                      |
-| ---------------------- | ------------------- | ------ | --------------------------- |
-| `validation_agreement` | `agreement_pct_1h`  | double | `tracker.agreementPct1h()`  |
-|                        | `agreements_1h`     | int64  | `tracker.agreements1h()`    |
-|                        | `missed_1h`         | int64  | `tracker.missed1h()`        |
-|                        | `agreement_pct_24h` | double | `tracker.agreementPct24h()` |
-|                        | `agreements_24h`    | int64  | `tracker.agreements24h()`   |
-|                        | `missed_24h`        | int64  | `tracker.missed24h()`       |
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.cpp`
-
-**Exit Criteria**:
-
-- [ ] Agreement percentages in range [0.0, 100.0]
-- [ ] Window stats stabilize after 1h/24h of operation
-
----
-
-## Summary Table
-
-| Task | Description                            | New Files | Modified Files | Depends On |
-| ---- | -------------------------------------- | --------- | -------------- | ---------- |
-| 7.1  | Add OTel Metrics SDK to build deps     | 0         | 2              | —          |
-| 7.2  | Implement OTelCollector class          | 2         | 0              | 7.1        |
-| 7.3  | Update CollectorManager config routing | 0         | 2              | 7.2        |
-| 7.4  | Update OTel Collector YAML and Docker  | 0         | 2              | 7.3        |
-| 7.5  | Preserve metric names in Prometheus    | 0         | 1              | 7.2        |
-| 7.6  | Update Grafana dashboards (if needed)  | 0         | 3              | 7.5        |
-| 7.7  | Update integration tests               | 0         | 1              | 7.4        |
-| 7.8  | Update documentation                   | 0         | 4              | 7.6        |
-| 7.9  | ValidationTracker (agreement tracking) | 2         | 4              | 7.2, P4.8  |
-| 7.10 | Validator health observable gauges     | 0         | 2              | 7.2        |
-| 7.11 | Peer quality observable gauges         | 0         | 2              | 7.2        |
-| 7.12 | Ledger economy observable gauges       | 0         | 2              | 7.2        |
-| 7.13 | State tracking observable gauges       | 0         | 2              | 7.2        |
-| 7.14 | Storage detail and sync info gauges    | 0         | 2              | 7.2        |
-| 7.15 | New synchronous counters               | 0         | 6              | 7.2        |
-| 7.16 | Validation agreement observable gauge  | 0         | 1              | 7.9        |
-
-**Parallel work**: Tasks 7.4 and 7.5 can run in parallel after 7.2/7.3 complete. Task 7.6 depends on 7.5's findings. Tasks 7.7 and 7.8 can run in parallel after 7.6. Tasks 7.10-7.14 can all run in parallel after 7.2. Task 7.15 depends on 7.2. Task 7.16 depends on 7.9. Task 7.9 depends on 7.2 and Phase 4 Task 4.8.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.8](./06-implementation-phases.md)):
-
-- [ ] All 255+ metrics visible in Prometheus via OTLP pipeline (no StatsD receiver)
-- [ ] `server=otel` is the default in development docker-compose
-- [ ] `server=statsd` still works as a fallback
-- [ ] Existing Grafana dashboards display data correctly
-- [ ] Integration test passes with OTLP-only metrics pipeline
-- [ ] No performance regression vs StatsD baseline (< 1% CPU overhead)
-- [ ] Deferred Task 6.1 (`|m` wire format) no longer relevant — Meter mapped to OTel Counter
-- [ ] ValidationTracker agreement % stabilizes after 1h under normal consensus
-- [ ] All new gauges and counters visible in Prometheus with non-zero values

OpenTelemetryPlan/Phase8_taskList.md

@@ -1,239 +0,0 @@
-# Phase 8: Log-Trace Correlation and Centralized Log Ingestion — Task List
-
-> **Goal**: Inject trace context (trace_id, span_id) into xrpld's Journal log output for log-trace correlation, and add OTel Collector filelog receiver to ingest logs into Grafana Loki for unified observability.
->
-> **Scope**: Two independent sub-phases — 8a (code change: trace_id in logs) and 8b (infra only: filelog receiver to Loki). No changes to the `beast::Journal` public API.
->
-> **Branch**: `pratik/otel-phase8-log-correlation` (from `pratik/otel-phase7-native-metrics`)
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                                      |
-| ---------------------------------------------------------------- | -------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 8 plan: motivation, architecture, exit criteria (§6.8.1) |
-| [07-observability-backends.md](./07-observability-backends.md)   | Loki backend recommendation, Grafana data source provisioning  |
-| [Phase7_taskList.md](./Phase7_taskList.md)                       | Prerequisite — native OTel metrics pipeline must be working    |
-| [05-configuration-reference.md](./05-configuration-reference.md) | `[telemetry]` config (trace_id injection toggle)               |
-
----
-
-## Task 8.1: Inject trace_id into Logs::format()
-
-**Objective**: Add OTel trace context to every log line that is emitted within an active, sampled span. The sampled flag matters because a span dropped by the `ParentBasedSampler` still carries its parent's ids, so emitting them would advertise a trace that was never exported.
-
-**What to do**:
-
-- Edit `src/libxrpl/basics/Log.cpp`:
-  - In `Logs::format()` (around line 346), after severity is appended, check for active OTel span. The implementation checks the context value directly to avoid the heap allocation that `GetSpan()` performs on the no-span path:
-    ```cpp
-    #ifdef XRPL_ENABLE_TELEMETRY
-    {
-        auto context = opentelemetry::context::RuntimeContext::GetCurrent();
-        auto spanValue = context.GetValue(opentelemetry::trace::kSpanKey);
-        if (opentelemetry::nostd::holds_alternative<
-                opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>>(spanValue))
-        {
-            auto span = opentelemetry::nostd::get<
-                opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>>(spanValue);
-            auto spanCtx = span->GetContext();
-            if (spanCtx.IsValid() && spanCtx.IsSampled())
-            {
-                char traceId[32], spanId[16];
-                spanCtx.trace_id().ToLowerBase16(
-                    opentelemetry::nostd::span<char, 32>{traceId});
-                spanCtx.span_id().ToLowerBase16(
-                    opentelemetry::nostd::span<char, 16>{spanId});
-                output += "trace_id=";
-                output.append(traceId, 32);
-                output += " span_id=";
-                output.append(spanId, 16);
-                output += ' ';
-            }
-        }
-    }
-    #endif
-    ```
-  - Add `#include` for OTel context headers, guarded by `#ifdef XRPL_ENABLE_TELEMETRY`
-
-- Edit `include/xrpl/basics/Log.h`:
-  - No changes needed — format() signature unchanged
-
-**Key modified files**:
-
-- `src/libxrpl/basics/Log.cpp`
-
-**Performance note**: The implementation checks the thread-local context value directly (avoiding the heap allocation that `GetSpan()` performs on the no-span path). On threads without an active span (~99% of log lines), the cost is a thread-local read + variant type check (~15-20ns). On the active-span path, an additional shared_ptr copy + `GetContext()` + `IsValid()`/`IsSampled()` adds ~50ns total. Overhead is negligible at typical logging rates.
-
----
-
-## Task 8.2: Add Loki to Docker Compose Stack
-
-**Objective**: Add Grafana Loki as a log storage backend in the development observability stack.
-
-**What to do**:
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Add Loki service:
-    ```yaml
-    loki:
-      image: grafana/loki:3.7.6
-      ports:
-        - "3100:3100"
-      command: -config.file=/etc/loki/local-config.yaml
-    ```
-  - Add Loki as a Grafana data source in provisioning
-
-- Create `docker/telemetry/grafana/provisioning/datasources/loki.yaml`:
-  - Configure Loki data source with derived fields linking `trace_id` to Tempo
-
-**Key new files**:
-
-- `docker/telemetry/grafana/provisioning/datasources/loki.yaml`
-
-**Key modified files**:
-
-- `docker/telemetry/docker-compose.yml`
-
----
-
-## Task 8.3: Add Filelog Receiver to OTel Collector
-
-**Objective**: Configure the OTel Collector to tail xrpld's log file and export to Loki.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Add `filelog` receiver:
-    ```yaml
-    receivers:
-      filelog:
-        include: [/var/log/xrpld/*/debug.log]
-        operators:
-          - type: regex_parser
-            regex: '^(?P<timestamp>\S+)\s+(?P<partition>\S+):(?P<severity>\S+)\s+(?:trace_id=(?P<trace_id>[a-f0-9]+)\s+span_id=(?P<span_id>[a-f0-9]+)\s+)?(?P<message>.*)$'
-            timestamp:
-              parse_from: attributes.timestamp
-              layout: "%Y-%m-%dT%H:%M:%S.%fZ"
-    ```
-  - Add logs pipeline:
-    ```yaml
-    service:
-      pipelines:
-        logs:
-          receivers: [filelog]
-          processors: [batch]
-          exporters: [otlp/loki]
-    ```
-  - Add Loki exporter:
-    ```yaml
-    exporters:
-      otlphttp/loki:
-        endpoint: http://loki:3100/otlp
-    ```
-
-- Mount xrpld's log directory into the collector container via docker-compose volume
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
----
-
-## Task 8.4: Configure Grafana Trace-to-Log Correlation
-
-**Objective**: Enable one-click navigation from Tempo traces to Loki logs in Grafana.
-
-**What to do**:
-
-- Edit Grafana Tempo data source provisioning to add `tracesToLogs` configuration:
-
-  ```yaml
-  tracesToLogs:
-    datasourceUid: loki
-    filterByTraceID: true
-    filterBySpanID: false
-    tags: ["partition", "severity"]
-  ```
-
-- Edit Grafana Loki data source provisioning to add `derivedFields` linking trace_id back to Tempo:
-  ```yaml
-  derivedFields:
-    - datasourceUid: tempo
-      matcherRegex: "trace_id=(\\w+)"
-      name: TraceID
-      url: "$${__value.raw}"
-  ```
-
-**Key modified files**:
-
-- `docker/telemetry/grafana/provisioning/datasources/loki.yaml`
-- `docker/telemetry/grafana/provisioning/datasources/` (Tempo data source file)
-
----
-
-## Task 8.5: Update Integration Tests
-
-**Objective**: Verify trace_id appears in logs and Loki correlation works.
-
-**What to do**:
-
-- Edit `docker/telemetry/integration-test.sh`:
-  - After sending RPC requests (which create spans), grep xrpld's log output for `trace_id=`
-  - Verify trace_id matches a trace visible in Tempo
-  - Optionally: query Loki via API to confirm log ingestion
-
-**Key modified files**:
-
-- `docker/telemetry/integration-test.sh`
-
----
-
-## Task 8.6: Update Documentation
-
-**Objective**: Document the log correlation feature in runbook and reference docs.
-
-**What to do**:
-
-- Edit `docs/telemetry-runbook.md`:
-  - Add "Log-Trace Correlation" section explaining how to use Grafana Tempo -> Loki linking
-  - Add LogQL query examples for filtering by trace_id
-
-- Edit `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add new section "3. Log Correlation" between SpanMetrics and StatsD sections
-  - Document the log format with trace_id injection
-  - Document Loki as a new backend
-
-- Edit `docker/telemetry/TESTING.md`:
-  - Add log correlation verification steps
-
-**Key modified files**:
-
-- `docs/telemetry-runbook.md`
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `docker/telemetry/TESTING.md`
-
----
-
-## Summary Table
-
-| Task | Description                                | Sub-Phase | New Files | Modified Files | Depends On |
-| ---- | ------------------------------------------ | --------- | --------- | -------------- | ---------- |
-| 8.1  | Inject trace_id into Logs::format()        | 8a        | 0         | 1              | Phase 7    |
-| 8.2  | Add Loki to Docker Compose stack           | 8b        | 1         | 1              | --         |
-| 8.3  | Add filelog receiver to OTel Collector     | 8b        | 0         | 2              | 8.1, 8.2   |
-| 8.4  | Configure Grafana trace-to-log correlation | 8b        | 0         | 2              | 8.3        |
-| 8.5  | Update integration tests                   | 8a + 8b   | 0         | 1              | 8.4        |
-| 8.6  | Update documentation                       | 8a + 8b   | 0         | 3              | 8.5        |
-
-**Parallel work**: Task 8.2 (Loki infra) can run in parallel with Task 8.1 (code change). Tasks 8.3-8.6 are sequential.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.8.1](./06-implementation-phases.md)):
-
-- [ ] Log lines within active, sampled spans contain `trace_id=<hex> span_id=<hex>`
-- [ ] Log lines outside spans have no trace context (no empty fields)
-- [ ] Loki ingests xrpld logs via OTel Collector filelog receiver
-- [ ] Grafana Tempo -> Loki one-click correlation works
-- [ ] Grafana Loki -> Tempo reverse lookup works via derived field
-- [ ] Integration test verifies trace_id presence in logs
-- [ ] No performance regression from trace_id injection (< 0.1% overhead)

OpenTelemetryPlan/Phase9_taskList.md

@@ -1,928 +0,0 @@
-<!-- cspell:ignore ISTOGRAM -->
-<!-- The all-caps macro name XRPL_METRIC_HISTOGRAM_RECORD trips cspell's
-     compound-word splitter, which emits the subword "ISTOGRAM"; ignore it here. -->
-
-# Phase 9: Internal Metric Instrumentation Gap Fill — Task List
-
-> **Status**: Complete for Tasks 9.1-9.13. Tasks 9.14-9.17 remain open by design
-> (see each task for the blocker).
->
-> **Goal**: Instrument xrpld to emit ~50+ metrics that exist in `get_counts`/`server_info`/TxQ/PerfLog but currently lack time-series export via the OTel or beast::insight pipelines.
->
-> **Scope**: Hybrid approach — extend `beast::insight` for metrics near existing registrations, use OTel Metrics SDK `ObservableGauge` callbacks for new categories (TxQ, PerfLog, CountedObjects).
->
-> **Branch**: `pratik/otel-phase9-metric-gap-fill` (from `pratik/otel-phase8-log-correlation`)
->
-> **Depends on**: Phase 7 (native OTel metrics pipeline) and Phase 8 (log-trace correlation)
-
-> **Note on metric names**: there is **no `xrpld_` prefix** on any emitted
-> metric. `77f35c03db` removed it and lowercased names, and
-> `OTelCollectorImp::formatName()`
-> (`src/libxrpl/beast/insight/OTelCollector.cpp:855-874`) adds no prefix at all —
-> it only lowercases the raw name and turns `.` and spaces into `_`. Earlier
-> revisions of this task list spelled every metric `xrpld_<name>`; those spellings
-> have been corrected in place to the emitted names, so the names below can be
-> pasted into Prometheus as written. Instruments created in
-> `src/xrpld/telemetry/MetricsRegistry.cpp` (35 of them) are the single source of
-> truth. `MetricsRegistry.h`'s Doxygen used to disagree on three histogram names;
-> those header comments were repaired in this change set (see Tasks 9.4 and 9.5),
-> so header and `.cpp` now agree.
->
-> **Two shapes do not simply lose the prefix**, so `xrpld_<name>` → `<name>` is
-> not a blanket rule:
->
-> - **Multiplexed observable gauges.** Most of the value names in these task
->   descriptions are a **`metric` label value** on a shared instrument, not a
->   standalone metric name — queue depth is `txq_metrics{metric="txq_count"}`, not
->   `txq_count`. The same applies to `nodestore_state`, `cache_metrics`,
->   `load_factor_metrics`, `server_info`, `db_metrics`, `validator_health`,
->   `peer_quality`, `state_tracking` and `ledger_economy`. Each task below names
->   its owning instrument.
-> - **Unit-suffixed histograms** coming through `beast::insight`.
->   `OTelCollectorImp` appends the unit to the name, so the `ios_latency`
->   histogram is `ios_latency_milliseconds_bucket` in Prometheus — not
->   `ios_latency_bucket`. Instruments created directly on `MetricsRegistry` keep
->   their literal name (`job_queued_us_bucket`, `rpc_method_us_bucket`) because
->   the unit is already in the instrument name.
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                      |
-| -------------------------------------------------------------------- | -------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 9 plan: motivation, architecture, exit criteria (§6.8.2) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Current metric inventory + future metrics section              |
-| [Phase7_taskList.md](./Phase7_taskList.md)                           | Prerequisite — OTel Metrics SDK and `OTelCollector` class      |
-| [Phase8_taskList.md](./Phase8_taskList.md)                           | Prerequisite — log-trace correlation                           |
-
-### Third-Party Consumer Context
-
-These metrics serve multiple external consumer categories identified during research:
-
-| Consumer Category         | Key Metrics They Need                                           |
-| ------------------------- | --------------------------------------------------------------- |
-| **Exchanges**             | Fee escalation levels, TxQ depth, settlement latency            |
-| **Payment Processors**    | Load factors, io_latency, transaction throughput                |
-| **Analytics Providers**   | NodeStore I/O, cache hit rates, counted objects                 |
-| **Validators/Operators**  | Per-job execution times, PerfLog RPC counters, consensus timing |
-| **Academic Researchers**  | Consensus performance time-series, fee market dynamics          |
-| **Institutional Custody** | Server health scores, reserve calculations, node availability   |
-
----
-
-## Task 9.1: NodeStore I/O Metrics
-
-**Objective**: Export node store read/write performance as time-series metrics.
-
-**What to do**:
-
-> **As shipped, this did _not_ go through `beast::insight`.** `Database.cpp` has
-> no insight members. The metrics are a single `nodestore_state`
-> `Int64ObservableGauge` on `MetricsRegistry`
-> (`src/xrpld/telemetry/MetricsRegistry.cpp:957-965`) whose callback reads
-> `Database`'s public accessors (`getFetchTotalCount()`, `getFetchHitCount()`,
-> `getStoreCount()`, `getFetchDurationUs()`, `getStoreDurationUs()`, …) and
-> multiplexes every value onto the `metric` label. Write-queue depth comes from
-> the new `include/xrpl/nodestore/WriteStats.h`.
-
-- Export the following as `nodestore_state{metric="…"}` label values:
-  - Gauge: `node_reads_total` (cumulative read operations)
-  - Gauge: `node_reads_hit` (fetches that found an object — not a cache hit; `fetchHitCount_` increments whatever served the fetch)
-  - Gauge: `node_writes` (cumulative write operations)
-  - Gauge: `node_written_bytes` (cumulative bytes written)
-  - Gauge: `node_read_bytes` (cumulative bytes read)
-  - Gauge: `node_reads_duration_us` (cumulative read time in microseconds)
-  - Gauge: `write_load` (current write load score)
-  - Gauge: `read_queue` (items in read queue)
-
-- These values are already computed in `Database::getCountsJson()`. The gauge
-  callback reads the same counters through `Database`'s public accessors.
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (the `nodestore_state` gauge)
-- `include/xrpl/nodestore/Database.h` (accessors; **not** `src/libxrpl/nodestore/Database.h`, which does not exist)
-- `include/xrpl/nodestore/WriteStats.h` (new — write-queue depth snapshot)
-
-**Derived Prometheus metrics**: `nodestore_state{metric="node_reads_total"}`,
-`nodestore_state{metric="node_reads_hit"}`, `nodestore_state{metric="write_load"}`,
-etc. There is **no** `xrpld_` prefix — `OTelCollectorImp::formatName()` adds none.
-
-**Grafana dashboard**: Add "NodeStore I/O" panel group to _Node Health_ dashboard.
-
----
-
-## Task 9.2: Cache Hit Rate Metrics
-
-**Objective**: Export SHAMap and ledger cache performance as time-series gauges.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks (via Phase 7's `OTelCollector`) for:
-  - `SLE_hit_rate` — SLE cache hit rate (0.0–1.0)
-  - `ledger_hit_rate` — Ledger object cache hit rate
-  - `AL_hit_rate` — AcceptedLedger cache hit rate
-  - `treenode_cache_size` — SHAMap TreeNode cache size (entries)
-  - `treenode_track_size` — Tracked tree nodes
-  - `fullbelow_size` — FullBelow cache size
-
-- The callback reads from the same sources as the `GetCounts` handler
-  (`src/xrpld/rpc/handlers/admin/status/GetCounts.cpp` — **not**
-  `src/xrpld/rpc/handlers/GetCounts.cpp`).
-
-- Create a centralized `MetricsRegistry` class that holds all OTel async gauge registrations, polled at 10-second intervals by the `PeriodicMetricReader`.
-
-**Key modified files**:
-
-- New: `src/xrpld/telemetry/MetricsRegistry.h` / `.cpp`
-- New: `src/xrpld/telemetry/MetricMacros.h` (the `XRPL_METRIC_*` call-site macros)
-- `src/xrpld/rpc/handlers/admin/status/GetCounts.cpp` (extract shared access methods)
-- `src/xrpld/app/main/Application.cpp` (register MetricsRegistry at startup)
-
-**Derived Prometheus metrics**: `cache_metrics{metric="SLE_hit_rate"}`,
-`cache_metrics{metric="ledger_hit_rate"}`, `cache_metrics{metric="treenode_cache_size"}`,
-etc. Label values are **case-sensitive** (`SLE_hit_rate`, `AL_size`, `AL_hit_rate`).
-
----
-
-## Task 9.3: Transaction Queue (TxQ) Metrics
-
-**Objective**: Export TxQ depth, capacity, and fee escalation levels as time-series.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for TxQ state (from
-  `src/xrpld/app/misc/TxQ.h` — **not** `src/xrpld/app/tx/detail/TxQ.h`):
-  - `txq_count` — Current transactions in queue
-  - `txq_max_size` — Maximum queue capacity
-  - `txq_in_ledger` — Transactions in current open ledger
-  - `txq_per_ledger` — Expected transactions per ledger
-  - `txq_reference_fee_level` — Reference fee level
-  - `txq_min_processing_fee_level` — Minimum fee to get processed
-  - `txq_med_fee_level` — Median fee level in queue
-  - `txq_open_ledger_fee_level` — Open ledger fee escalation level
-
-- Add to the `MetricsRegistry` (Task 9.2).
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add TxQ callbacks)
-- `src/xrpld/app/misc/TxQ.h` (expose metrics accessor if needed)
-
-**Derived Prometheus metrics**: `txq_metrics{metric="txq_count"}`,
-`txq_metrics{metric="txq_max_size"}`, `txq_metrics{metric="txq_open_ledger_fee_level"}`, etc.
-There is one instrument, `txq_metrics` (`MetricsRegistry.cpp:705`); each value above
-is a `metric` label value, not a metric name of its own.
-
-**Grafana dashboard**: New _Fee Market & TxQ_ dashboard (`fee-market`).
-
----
-
-## Task 9.4: PerfLog Per-RPC Method Metrics
-
-**Objective**: Export per-RPC-method call counts and latency as OTel metrics.
-
-**What to do**:
-
-- Register OTel instruments for PerfLog RPC counters (from `PerfLogImp.cpp`):
-  - Counter: `rpc_method_started_total{method="<name>"}` — calls started
-  - Counter: `rpc_method_finished_total{method="<name>"}` — calls completed
-  - Counter: `rpc_method_errored_total{method="<name>"}` — calls errored
-  - Histogram: `rpc_method_us{method="<name>"}` — execution time distribution
-
-- Use OTel `Counter<uint64_t>` and `Histogram<double>` instruments with the
-  `method` attribute label. The RPC instruments carry **only** `method`
-  (`MetricsRegistry.cpp:436-475`) — the `handler` label belongs to the job
-  instruments (Task 9.5), not these.
-
-> **Naming**: the instrument is `rpc_method_us` — declared as
-> `kRpcMethodDurationUs` at `MetricsRegistry.cpp:96` and used both to register the
-> explicit-bucket view and to create the instrument. `MetricsRegistry.h`'s Doxygen
-> comment used to read `rpc_method_duration_us`; **that was fixed in this change**
-> (`MetricsRegistry.h:789`), so header and `.cpp` now agree and there is no
-> caveat left. The prefix `xrpld_` in the original spec is not emitted by anything.
->
-> Same for the job histograms in Task 9.5: `job_queued_us` / `job_running_us`.
-
-- Hook into the existing PerfLog callback mechanism rather than adding new instrumentation points.
-
-**Key modified files**:
-
-- `src/xrpld/perflog/detail/PerfLogImp.cpp` (add OTel instrument updates alongside existing JSON counters)
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (register instruments)
-
-**Derived Prometheus metrics**: `rpc_method_started_total{method="server_info"}`, `rpc_method_us_bucket{method="ledger"}`, etc.
-
-**Grafana dashboard**: Add "Per-Method RPC Breakdown" panel group to _RPC Performance_ dashboard.
-
----
-
-## Task 9.5: PerfLog Per-Job-Type Metrics
-
-**Objective**: Export per-job-type queue and execution metrics.
-
-**What to do**:
-
-- Register OTel instruments for PerfLog job counters. All five carry **two**
-  labels — `job_type` and `handler` — so producers sharing a job type stay
-  distinguishable (`MetricsRegistry.h:794-818`, recorded at
-  `MetricsRegistry.cpp:498,518,527,548,553`). `handler` is the sanitised
-  `addJob` name; `sanitiseHandler()` folds dynamic names into a bounded domain
-  of exactly 44 values, so cardinality stays fixed.
-  - Counter: `job_queued_total{job_type="<name>",handler="<name>"}` — jobs queued
-  - Counter: `job_started_total{job_type="<name>",handler="<name>"}` — jobs started
-  - Counter: `job_finished_total{job_type="<name>",handler="<name>"}` — jobs completed
-  - Histogram: `job_queued_us{job_type="<name>",handler="<name>"}` — time spent waiting in queue
-  - Histogram: `job_running_us{job_type="<name>",handler="<name>"}` — execution time distribution
-
-> **Naming**: the instruments are `job_queued_us` / `job_running_us`
-> (`kJobQueuedDurationUs` / `kJobRunningDurationUs`, `MetricsRegistry.cpp:94-95`).
-> `MetricsRegistry.h`'s Doxygen comments used to read
-> `job_queued_duration_us` / `job_running_duration_us`; **both were fixed in this
-> change** (`MetricsRegistry.h:810,815`), so there is no header/`.cpp` divergence
-> left to work around.
-
-- Hook into PerfLog's existing job tracking alongside Task 9.4.
-
-**Key modified files**:
-
-- `src/xrpld/perflog/detail/PerfLogImp.cpp`
-- `src/xrpld/telemetry/MetricsRegistry.cpp`
-
-**Derived Prometheus metrics**: `job_queued_total{job_type="ledgerData",handler="ProcessLData"}`, `job_running_us_bucket{job_type="transaction",handler="…"}`, etc.
-
-**Grafana dashboard**: New _Job Queue Analysis_ dashboard (`job-queue`).
-
----
-
-## Task 9.6: Counted Object Instance Metrics
-
-**Objective**: Export live instance counts for key internal object types.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for `CountedObject<T>` instance counts:
-  - `object_count{type="xrpl::Transaction"}` — live Transaction objects
-  - `object_count{type="xrpl::Ledger"}` — live Ledger objects
-  - `object_count{type="xrpl::NodeObject"}` — live NodeObject instances
-  - `object_count{type="xrpl::STTx"}` — serialized transaction objects
-  - `object_count{type="xrpl::STLedgerEntry"}` — serialized ledger entries
-  - `object_count{type="xrpl::InboundLedger"}` — ledgers being fetched
-  - `object_count{type="xrpl::Pathfinder"}` — active pathfinding computations
-  - `object_count{type="xrpl::PathRequest"}` — active path requests
-  - `object_count{type="xrpl::HashRouter::Entry"}` — hash router entries (the type is
-    `HashRouter::Entry`; there is no `HashRouterEntry` type)
-
-- The `CountedObject` template already tracks these via atomic counters. The callback just reads the current counts.
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add counted object callbacks)
-- `include/xrpl/basics/CountedObject.h` (may need static accessor for iteration)
-
-**Derived Prometheus metrics**: `object_count{type="xrpl::Transaction"}`, `object_count{type="xrpl::NodeObject"}`, etc.
-The `type` label value is `beast::typeName<Object>()` — the fully-qualified
-demangled C++ type name (`CountedObject.h:109`), not a short word.
-
-**Grafana dashboard**: Add "Object Instance Counts" panel to _Node Health_ dashboard.
-
----
-
-## Task 9.7: Fee Escalation & Load Factor Metrics
-
-**Objective**: Export the full load factor breakdown as time-series.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for load factors (from `NetworkOPs.cpp` line ~2694):
-  - `load_factor` — combined transaction cost multiplier
-  - `load_factor_server` — server + cluster + network contribution
-  - `load_factor_local` — local server load only
-  - `load_factor_net` — network-wide load estimate
-  - `load_factor_cluster` — cluster peer load
-  - `load_factor_fee_escalation` — open ledger fee escalation
-  - `load_factor_fee_queue` — queue entry fee level
-
-- These overlap with some existing StatsD metrics but provide finer granularity (individual factor breakdown vs. combined value).
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp`
-- `src/xrpld/app/misc/NetworkOPs.cpp` (expose load factor accessors if needed)
-
-**Derived Prometheus metrics**: `load_factor_metrics{metric="load_factor"}`,
-`load_factor_metrics{metric="load_factor_fee_escalation"}`, etc. There is one
-instrument, `load_factor_metrics` (`MetricsRegistry.cpp:785`); every value listed
-above is a `metric` label value, not a metric name of its own.
-
-**Grafana dashboard**: Add "Load Factor Breakdown" panel to _Fee Market & TxQ_ dashboard.
-
----
-
-## Task 9.7a: push_metrics.py Parity — Missing Observable Gauges
-
-**Objective**: Fill the remaining metric gaps between the external `push_metrics.py` script (in `ripplex-ansible`) and the internal OTel `MetricsRegistry` observable gauges. After this task, all metrics collected by `push_metrics.py` that CAN be collected internally are covered.
-
-**What was done**:
-
-- Extended existing `cacheHitRateGauge_` callback with `AL_size` (AcceptedLedger cache size)
-- Extended existing `nodeStoreGauge_` callback with 4 new metrics from `getCountsJson()`:
-  - `node_reads_duration_us` (JSON string — uses `std::stoll(asString())`)
-  - `read_request_bundle` (native JSON int)
-  - `read_threads_running` (native JSON int)
-  - `read_threads_total` (native JSON int)
-- Added new `server_info` Int64ObservableGauge with 8 metrics:
-  - `server_state` — operating mode as int (0=DISCONNECTED .. 4=FULL)
-  - `uptime` — seconds since server start
-  - `peers` — total peer count
-  - `validated_ledger_seq` — validated ledger sequence (atomic read)
-  - `ledger_current_index` — current open ledger sequence
-  - `peer_disconnects_resources` — cumulative resource-related disconnects
-  - `last_close_proposers` — from `getConsensusInfo()["previous_proposers"]`
-  - `last_close_converge_time_ms` — from `getConsensusInfo()["previous_mseconds"]`
-- Added new `build_info` Int64ObservableGauge (info-style, value=1 with `version` label)
-- Added new `complete_ledgers` Int64ObservableGauge parsing comma-separated ranges into `{bound, index}` pairs
-- Added new `db_metrics` Int64ObservableGauge with 4 metrics:
-  - `db_kb_total`, `db_kb_ledger`, `db_kb_transaction` (SQLite stat queries)
-  - `historical_perminute` (historical ledger fetch rate)
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.h` (4 new gauge members, updated ASCII diagram)
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (4 new callback registrations, 2 callback extensions)
-
-**Not implementable inside xrpld**:
-
-- `connection_count_51233/51234` — OS-level port connection counts from external shell script (`get_connection.sh`)
-
-**Derived Prometheus metrics**: `server_info{metric="server_state"}`, `build_info{version="2.4.0"}`, `complete_ledgers{bound="start",index="0"}`, `db_metrics{metric="db_kb_total"}`, etc.
-
-**Grafana dashboard**: New panels added to _Node Health_ dashboard (`node-health.json`).
-
----
-
-## Task 9.8: New Grafana Dashboards
-
-**Objective**: Create Grafana dashboards for the new metric categories.
-
-**What to do**:
-
-- Create 2 new dashboards:
-  1. **Fee Market & TxQ** (`fee-market`) — TxQ depth/capacity, fee levels, load factor breakdown, fee escalation timeline
-  2. **Job Queue Analysis** (`job-queue`) — Per-job-type rates, queue wait times, execution times, job queue depth
-
-- Update 2 existing dashboards:
-  1. **Node Health** (`node-health`) — Add NodeStore I/O panels, cache hit rate panels, object instance counts
-  2. **RPC Performance** (`rpc-performance`) — Add per-method RPC breakdown panels
-
-> Tasks 9.11-9.13 add two more new dashboards (`validator-health`,
-> `peer-quality`), so Phase 9's total is **4 new + 2 updated**.
-
-**Key modified files** (filenames and uids after the `dashboards/rippled-*` →
-bare rename in `145b1469d6` and `25868f2740` — the
-`dashboards/rippled-*.json` paths no longer exist):
-
-- New: `docker/telemetry/grafana/dashboards/fee-market.json` (uid `fee-market`)
-- New: `docker/telemetry/grafana/dashboards/job-queue.json` (uid `job-queue`)
-- `docker/telemetry/grafana/dashboards/node-health.json` (uid `node-health`)
-- `docker/telemetry/grafana/dashboards/rpc-performance.json` (uid `rpc-performance`)
-
----
-
-## Task 9.9: Update Documentation
-
-**Objective**: Update telemetry reference docs with all new metrics.
-
-**What to do**:
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`: ✅ done
-  - Add new section for OTel SDK-exported metrics (NodeStore, cache, TxQ, PerfLog, CountedObjects, load factors) — §5b + "Phase 9: OTel SDK-Exported Metrics (MetricsRegistry)"
-  - Update Grafana dashboard reference table (add 4 new dashboards) — "New Grafana Dashboards (Phase 9)" / "Updated Grafana Dashboards (Phase 9)"
-  - Add Prometheus query examples for new metrics
-
-- Update `docs/telemetry-runbook.md`:
-  - ✅ Alerting section covering the provisioned rules and how to wire a receiver
-  - ✅ Troubleshooting entries for new metric categories
-  - ❌ **Still open**: dashboard guides for **six** dashboards — `fee-market`,
-    `job-queue`, `ledger-data-sync`, `overlay-traffic-detail`, `peer-quality` and
-    `validator-health`. The runbook's dashboard reference records the gap
-    verbatim: "Nine dashboards have a reference section below. `fee-market`,
-    `job-queue`, `ledger-data-sync`, `overlay-traffic-detail`, `peer-quality`, and
-    `validator-health` are provisioned but not yet documented here — their panel
-    descriptions carry the same six-heading reference format, so open the panel
-    info icon in Grafana until a section is written." (15 provisioned − 6
-    undocumented = 9 documented.) Also still open: the Validation Agreement
-    explainer (8s grace / 5m late repair)
-
-- Provision Grafana alert rules (`docker/telemetry/grafana/provisioning/alerting/`) — **as shipped**:
-  - **13 rules in 5 groups**: `xrpld-consensus` (`LedgerHistoryMismatch`,
-    `LedgerCloseStalled`, `ValidatedLedgerStale`), `xrpld-validator`
-    (`ValidationsMissed`, `ValidationsNotChecked`), `xrpld-jobqueue`
-    (`JobQueueTxOverflow`, `JobQueueLatencyHigh`, `NodeStoreIOLatencyHigh`),
-    `xrpld-node-state` (`NodeStateFlapping`, `NodeNotFull`), `xrpld-overlay`
-    (`ManifestJobQueueConvoy`, `ManifestFloodInbound`, `PeerResourceDisconnects`)
-  - **2 contact points** — `xrpld-default` (Slack) and `xrpld-critical`
-    (Slack + email) — and a **nested** notification policy: root →
-    `xrpld-default`, child route `severity = critical` → `xrpld-critical`.
-    Auto-loaded via the existing `provisioning/` mount (no docker-compose change)
-  - 3 rules are `severity: critical`, 10 are `severity: warning`
-  - Alerting operator docs (per-alert meaning, tuning, receiver wiring) now live in the Alerting section of `docs/telemetry-runbook.md`
-
-**Key modified files**:
-
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `docs/telemetry-runbook.md`
-- `docker/telemetry/grafana/provisioning/alerting/{rules,contactpoints,policies}.yaml` (new)
-- `docs/telemetry-runbook.md` (Alerting section added)
-
----
-
-## Task 9.10: Integration Tests
-
-**Objective**: Verify all new metrics appear in Prometheus after a test workload.
-
-**What to do**:
-
-- ❌ **Not done on this branch**: extend the telemetry integration test to
-  start xrpld with `[telemetry] enabled=1` / `[insight] server=otel`, drive RPC
-  and transaction load, query Prometheus for each new metric family and assert
-  non-zero values. The end-to-end metric assertions live in the **Phase 10**
-  harness (`docker/telemetry/workload/expected_metrics.json`), not here.
-
-- ✅ **Done**: unit tests for the `MetricsRegistry` class —
-  `src/tests/libxrpl/telemetry/MetricsRegistry.cpp` (**18** GTest cases —
-  `grep -cE '\bTEST(_F|_P)?\s*\(' src/tests/libxrpl/telemetry/MetricsRegistry.cpp`
-  = 18, and the four bullets below sum to 4 + 3 + 5 + 6 = 18):
-  - Callback registration / deregistration and shutdown ordering —
-    `async_gauges_start_after_start_is_safe`,
-    `async_gauges_before_start_does_not_break_start`,
-    `async_gauges_respect_the_compile_time_guard`, `destructor_calls_stop`
-  - Graceful behaviour when telemetry is disabled — `disabled_construction`,
-    `disabled_start_stop`, `disabled_recording_methods`
-  - Label sanitisation and mean scaling — `MetricsRegistrySanitiseHandler` (5
-    cases, incl. `output_domain_is_exactly_44_values`) and
-    `MetricsRegistryScaledMean` (6 cases)
-  - ❌ Not covered: asserting metric values match `get_counts` JSON output —
-    that needs a live `Application`, so it is left to the Phase 10 harness
-
-**Key files**:
-
-- `src/tests/libxrpl/telemetry/MetricsRegistry.cpp` (new). The originally
-  planned `src/test/telemetry/MetricsRegistry_test.cpp` was **never created** —
-  Phase 9 tests are GTest under `src/tests/libxrpl/`, per project convention.
-- `src/tests/libxrpl/telemetry/MetricMacros.cpp`, `GetMeter.cpp` (new — cover
-  the `XRPL_METRIC_*` macros and meter lookup)
-
----
-
-## Task 9.11: Validator Health Dashboard (External Dashboard Parity)
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — dashboards for Phase 7 metrics inspired by the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 7 Tasks 7.9-7.16 (metrics must be emitting).
-> **Downstream**: Phase 10 (dashboard load checks), Phase 11 (alert rules reference these panels).
-
-**Objective**: Create a Grafana dashboard for validation agreement, amendment/UNL health, and state tracking.
-
-**Dashboard**: `validator-health.json`
-
-| Panel                      | Type       | PromQL                                                   |
-| -------------------------- | ---------- | -------------------------------------------------------- |
-| Agreement % (1h)           | stat       | `validation_agreement{metric="agreement_pct_1h"}`        |
-| Agreement % (24h)          | stat       | `validation_agreement{metric="agreement_pct_24h"}`       |
-| Agreements vs Missed (1h)  | bargauge   | `agreements_1h` and `missed_1h` side by side             |
-| Agreements vs Missed (24h) | bargauge   | `agreements_24h` and `missed_24h` side by side           |
-| Validation Rate            | stat       | `rate(validations_sent_total[5m]) * 60`                  |
-| Validations Checked Rate   | stat       | `rate(validations_checked_total[5m]) * 60`               |
-| Amendment Blocked          | stat       | `validator_health{metric="amendment_blocked"}`           |
-| UNL Expiry (days)          | stat       | `validator_health{metric="unl_expiry_days"}`             |
-| Validation Quorum          | stat       | `validator_health{metric="validation_quorum"}`           |
-| State Value Timeline       | timeseries | `state_tracking{metric="state_value"}`                   |
-| Time in Current State      | stat       | `state_tracking{metric="time_in_current_state_seconds"}` |
-| State Changes Rate         | stat       | `rate(state_changes_total[1h])`                          |
-| Ledgers Closed Rate        | stat       | `rate(ledgers_closed_total[5m]) * 60`                    |
-
-**Dashboard conventions**: `$node` template variable for `service_instance_id` filtering, dark theme, matching existing panel sizes and color schemes.
-
-**Key new files**: `docker/telemetry/grafana/dashboards/validator-health.json`
-(uid `validator-health`). The name reached its current form in **two** renames:
-`dashboards/rippled-validator-health.json` → `xrpld-validator-health.json`
-(`145b1469d6`, the `dashboards/rippled-*` → `xrpld-*` pass), then
-`xrpld-validator-health.json` → `validator-health.json` (`25868f2740`, which
-dropped the `xrpld-` prefix).
-
-**Exit Criteria**:
-
-- [x] Dashboard ships **17** panels (4 more than the 13 planned above) across 3
-      rows — Validation Agreement, Validation Rates, Server State & Consensus
-- [ ] All panels render with non-zero data during normal operation — needs a live
-      stack; the Phase 10 harness asserts the dashboard _loads_, not that panels
-      are non-empty
-- [x] `$node` filter works correctly for multi-node deployments — `node`
-      template variable present (filters on `service_instance_id`), alongside
-      `service_name`, `deployment_environment`, `xrpl_network_type`,
-      `xrpl_work_item`, `xrpl_branch`, `xrpl_node_role`
-- [x] Amendment blocked and UNL expiry panels use color thresholds
-      (red=blocked/expiring) — 11 `thresholds` blocks in the dashboard JSON
-
----
-
-## Task 9.12: Peer Quality Dashboard (External Dashboard Parity)
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Create a Grafana dashboard for peer health aggregates.
-
-**Dashboard**: `peer-quality.json`
-
-| Panel                  | Type       | PromQL                                                                  |
-| ---------------------- | ---------- | ----------------------------------------------------------------------- |
-| P90 Peer Latency       | timeseries | `peer_quality{metric="peer_latency_p90_ms"}`                            |
-| Insane/Diverged Peers  | stat       | `peer_quality{metric="peers_insane_count"}`                             |
-| Higher Version Peers % | stat       | `peer_quality{metric="peers_higher_version_pct"}`                       |
-| Upgrade Recommended    | stat       | `peer_quality{metric="upgrade_recommended"}`                            |
-| Resource Disconnects   | timeseries | `server_info{metric="peer_disconnects_resources"}`                      |
-| Inbound vs Outbound    | bargauge   | `peer_finder_active_inbound_peers`, `peer_finder_active_outbound_peers` |
-
-> `overlay_peer_disconnects_charges` (the name in the original spec) is **not a
-> real instrument** — nothing registers it. The shipped panel reads
-> `server_info{metric="peer_disconnects_resources"}` instead. Peer-finder gauge
-> names are lowercase: `GroupImp::makeName()` + `OTelCollectorImp::formatName()`
-> turn the `"Peer_Finder"` group into `peer_finder_<name>` with no prefix.
-
-**Key new files**: `docker/telemetry/grafana/dashboards/peer-quality.json`
-(uid `peer-quality`). Two renames, same as Task 9.11:
-`dashboards/rippled-peer-quality.json` → `xrpld-peer-quality.json`
-(`145b1469d6`), then `xrpld-peer-quality.json` → `peer-quality.json`
-(`25868f2740`).
-
-**Exit Criteria**:
-
-- [x] All 6 panels present — P90 Peer Latency, Insane/Diverged Peers, Higher
-      Version Peers %, Upgrade Recommended, Inbound vs Outbound Peers, Resource
-      Disconnects — across 3 rows, with the `$node` template variable
-- [ ] All 6 panels render with data — needs a live stack
-- [x] P90 latency panel is a `timeseries` (shows trend over time)
-- [x] Upgrade recommended panel uses color threshold (red=1, green=0) — 5
-      `thresholds` blocks in the dashboard JSON
-
----
-
-## Task 9.13: Ledger Economy Dashboard Panels (External Dashboard Parity)
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Add "Ledger Economy" row to the existing `node-health.json` dashboard.
-
-| Panel                | Type       | PromQL                                        |
-| -------------------- | ---------- | --------------------------------------------- |
-| Base Fee (drops)     | stat       | `ledger_economy{metric="base_fee_xrp"}`       |
-| Reserve Base (drops) | stat       | `ledger_economy{metric="reserve_base_xrp"}`   |
-| Reserve Inc (drops)  | stat       | `ledger_economy{metric="reserve_inc_xrp"}`    |
-| Ledger Age           | stat       | `ledger_economy{metric="ledger_age_seconds"}` |
-| Transaction Rate     | timeseries | `ledger_economy{metric="transaction_rate"}`   |
-
-**Key modified files**: `docker/telemetry/grafana/dashboards/node-health.json`
-
-**Exit Criteria**:
-
-- [x] 5 new panels present in the existing dashboard — a "Ledger Economy" row
-      with 5 `ledger_economy` queries is on `node-health.json`
-- [ ] Fee values match `server_info` RPC output — needs a live comparison
-- [ ] Transaction rate shows smooth trend (not spiky) — needs a live run
-
----
-
-## Task 9.14: Overlay Traffic Accounting Defects (Documentation Only)
-
-> **Status**: DOCUMENTED, NOT FIXED. Reference: [09 §6.0-§6.2](./09-data-collection-reference.md#6-known-issues)
-
-**Objective**: Record four pre-existing overlay traffic-accounting defects so
-dashboard readers are not misled. All four originate in `develop`-owned overlay
-files, so **no code fix lands on this branch**.
-
-| #   | Defect                                 | Effect                                                                                    | Fix location (NOT this branch)                   |
-| --- | -------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| 1   | `mtCLUSTER` missing from `kTypeLookup` | `overhead_cluster_*` always zero; 8 panels flatline; cluster traffic counted as `unknown` | `TrafficCount.cpp:11-27`                         |
-| 2   | Stale `Total` header comment           | Claims uncategorized traffic is excluded; it is included                                  | `TrafficCount.h:28-31`                           |
-| 3   | `SquelchIgnored` reported with size 0  | `squelch_ignored_bytes_*` always zero, inconsistent with `SquelchSuppressed`              | `OverlayImpl.cpp:1460,1489` (+ signature change) |
-| 4   | In/out byte-basis asymmetry            | `_bytes_in` vs `_bytes_out` not comparable under compression                              | `PeerImp.cpp:1079` vs `:313`                     |
-
-**Why deferred**: Defect 3 requires widening the two
-`OverlayImpl::updateSlotAndSquelch` overloads — a public signature change on
-shared overlay code. Defects 1 and 4 need `TrafficCount.cpp` and `PeerImp.cpp`
-edits that are not telemetry-owned. Routing them through the telemetry chain
-would hide overlay changes from overlay reviewers and couple them to a 12-PR
-merge timeline.
-
-> **Constraint narrowed.** The blanket "no telemetry change may touch
-> `TrafficCount.{h,cpp}`" no longer holds for the header: the telemetry chain
-> already edits `TrafficCount.h` — Phase 6's `77f35c03db` fixed the
-> `Category::GetFetchPack` label from `"getobject_Fetch Pack_get"` to
-> `"getobject_Fetch_Pack_get"` at `TrafficCount.h:285`, the sole difference from
-> `develop`. Defect 2 (the stale `Total` header comment, `TrafficCount.h:28-31`)
-> is therefore **unblocked** and can land here. Defects **1, 3 and 4** stay
-> blocked: defect 1 needs `TrafficCount.cpp`'s `kTypeLookup`, defect 3 needs the
-> `OverlayImpl` signature change, and defect 4 needs `PeerImp.cpp:1079` vs `:313`
-> to agree on a byte basis (compressed vs uncompressed) — a change to overlay
-> accounting semantics, not telemetry.
-
-**Key modified files**: `OpenTelemetryPlan/09-data-collection-reference.md` only.
-
-**Exit Criteria**:
-
-- [x] Each defect documented with file:line evidence in `09` §6
-- [x] `overhead_cluster_*` documented as "no data", not "no cluster traffic"
-- [ ] Defect 2 (stale `Total` header comment, `TrafficCount.h:28-31`) fixed on
-      this branch — it is **unblocked** (the chain already edits
-      `TrafficCount.h`) but the comment is still uncorrected
-- [ ] Follow-up overlay-owned branch raised for the three still-blocked code
-      fixes (defects 1, 3, 4)
-- [ ] Re-baseline any threshold keyed on `unknown_bytes_in` when defect 1 lands
-
----
-
-## Task 9.15: Peer Keepalive and Discovery Instrumentation
-
-> **Status**: NOT IMPLEMENTED. The instruments themselves are still to be
-> written; the _permission_ question is settled. Reference:
-> [09 §6.3](./09-data-collection-reference.md#63-peer-keepalive-and-discovery-traffic-gaps-not-implemented)
->
-> **Blocker cleared.** This task used to be held "awaiting a decision on whether
-> `XRPL_METRIC_*` call sites may be added to
-> `src/xrpld/overlay/detail/PeerImp.cpp` from this branch". That decision is
-> de facto **yes** — `PeerImp.cpp` already carries **7** such call sites on this
-> branch (`:2723`, `:2741`, `:2925`, `:2928`, `:2931`, `:2947`, `:2954`, of which
-> three are `XRPL_METRIC_HISTOGRAM_RECORD` — `:2925`, `:2928`, `:2931` — and four
-> are labelled counters — `:2723`, `:2741`, `:2947`, `:2954`). Note that
-> `grep -c XRPL_METRIC src/xrpld/overlay/detail/PeerImp.cpp` returns 8: the eighth
-> hit is the `cspell:ignore` explanation comment at `PeerImp.cpp:2`, not a call
-> site. What remains is the implementation work below, not an approval.
-
-**Objective**: Make peer keepalive and peer-discovery health observable. Today
-`mtPING`, `mtSTATUS_CHANGE` and `mtENDPOINTS` are byte counters only.
-
-| Proposed metric                 | Type      | Labels                           | Record site                                         |
-| ------------------------------- | --------- | -------------------------------- | --------------------------------------------------- |
-| `peer_ping_rtt_ms`              | Histogram | none (see note)                  | `PeerImp.cpp:1150-1163`, where the EWMA is computed |
-| `peer_ping_timeouts_total`      | Counter   | `reason="timeout"\|"bad_cookie"` | `PeerImp.cpp:762` and `:1146`                       |
-| `peer_endpoints_received_total` | Counter   | `result="accepted"\|"malformed"` | `PeerImp.cpp:1265-1270`                             |
-
-**Design notes / open questions**:
-
-- A histogram needs an explicit bucket view: the SDK default tops out at 10000,
-  and these are milliseconds. Follow the µs-ladder precedent in
-  `MetricsRegistry.cpp` (see [09 § GetObject Request Path](./09-data-collection-reference.md#getobject-request-path-synchronous-countershistograms)).
-- `peer_id` as a label is unbounded cardinality — rejected. A bounded
-  `peer_role`-style label is the alternative if per-peer attribution is needed.
-- Splitting `mtPING` out of `Category::Base` is a `TrafficCount.cpp` change and
-  therefore still blocked with Task 9.14 defect 1. (The `.h` half of that
-  constraint no longer applies — see Task 9.14.)
-- Per the runbook's "Adding a New Metric" contract, `_total` is reserved for
-  monotonic counters; a histogram takes no suffix.
-
-**Key files (if approved)**: `src/xrpld/overlay/detail/PeerImp.cpp`,
-`09-data-collection-reference.md`, `docs/telemetry-runbook.md` § Metric Reference,
-`docker/telemetry/grafana/dashboards/peer-quality.json`, and
-`docker/telemetry/workload/expected_metrics.json` (**Phase 10 branch**).
-
-**Exit Criteria**:
-
-- [x] Decision recorded on editing `PeerImp.cpp` from the telemetry chain — yes;
-      7 `XRPL_METRIC_*` call sites already ship in `PeerImp.cpp`
-- [ ] Three instruments emitting, with an explicit histogram bucket view
-- [ ] Rows added to `09` §5b, runbook § Metric Reference, and `expected_metrics.json`
-- [ ] Peer Quality dashboard panels follow the Task 9.12 conventions (`$node`, Title Case, legend dimensions)
-- [ ] `check_otel_naming.py` passes (Rules D and E cover the new labels)
-
----
-
-## Task 9.16: PeerFinder Slot and Cache Metrics
-
-> **Status**: NOT IMPLEMENTED. Reference: [09 §6.5](./09-data-collection-reference.md#65-peerfinder-slot-and-cache-metrics-not-implemented)
-
-**Objective**: Export the PeerFinder slot counts and discovery-cache sizes.
-Only 2 of ~17 available readings are exported today.
-
-**What to do**: Extend the existing `Stats` struct in
-`src/libxrpl/peerfinder/PeerfinderManager.cpp:227-236` with gauges for the
-`Counts` accessors listed in [09 §6.5](./09-data-collection-reference.md#65-peerfinder-slot-and-cache-metrics-not-implemented)
-(slot caps and frees, attempt counts, handshake pipeline depth, fixed-peer state,
-network reachability), plus `Livecache::size()` and `Bootcache::size()`.
-
-**Pipeline constraint**: `PeerfinderManager.cpp` is in `libxrpl`, which **cannot**
-use the `XRPL_METRIC_*` macros. These must go through `beast::insight` —
-arrow **B**, not **C**. Naming follows `GroupImp::makeName()` +
-`OTelCollectorImp::formatName()`, so the `"Peer_Finder"` group yields
-`peer_finder_<name>` lowercased.
-
-**Known obstacle**: `Livecache` and `Bootcache` hold no collector reference, so
-their sizes must either be read through the existing `Manager` hook or have a
-collector plumbed in.
-
-**Exit Criteria**:
-
-- [ ] Slot caps exported so utilization (`active / max`) is computable
-- [ ] Both cache sizes exported
-- [ ] "Inbound vs Outbound" panel on `peer-quality` extended to show utilization %
-- [ ] Rows added to `09` §2.1, runbook § Metric Reference, `expected_metrics.json` (Phase 10)
-
----
-
-## Task 9.17: Peer Span Coverage (Deferred to Phase 11)
-
-> **Status**: NOT IMPLEMENTED — design only, pending approval. Reference:
-> [09 §6.4](./09-data-collection-reference.md#64-peer-span-coverage-gap-not-implemented)
-> and [02 §2.3.2](./02-design-decisions.md#232-complete-span-catalog)
-
-**Objective**: Close the gap between the `02` §2.3.2 span catalog and what
-actually emits. `peer.connect`, `peer.disconnect`, `peer.message.send` and
-`peer.message.receive` were catalogued from the start and never built; 11 of 13
-protocol message families have no spans.
-
-**Scope warning**: This is larger than Tasks 9.14-9.16 combined and changes the
-span-family inventory asserted in `09` §1.1 (**41** emitted families) and in
-`docker/telemetry/workload/expected_spans.json` (**40** catalogued — `rpc.ws_upgrade`
-has no entry). `trace_peer` is also **on by default** and already flagged as
-high-volume, so adding per-message spans has a volume cost that needs measuring
-before commitment.
-
-**Exit Criteria**:
-
-- [x] `02` §2.3.2 marked Live / Not built / Renamed against the real inventory
-- [ ] User approval to proceed with span implementation
-- [ ] Volume impact measured under `trace_peer=1` before any span is added
-
----
-
-## Exit Criteria
-
-- [ ] All ~50 new metrics visible in Prometheus via OTLP pipeline — every
-      instrument is registered in `MetricsRegistry.cpp`, but end-to-end
-      visibility is asserted only by the Phase 10 harness
-- [x] `MetricsRegistry` class registers/deregisters cleanly with OTel SDK —
-      `src/tests/libxrpl/telemetry/MetricsRegistry.cpp`
-      (`async_gauges_start_after_start_is_safe`,
-      `async_gauges_before_start_does_not_break_start`,
-      `async_gauges_respect_the_compile_time_guard`, `destructor_calls_stop`)
-- [x] Async gauge callbacks execute at 10s intervals —
-      `MetricsRegistry::initExporterAndProvider`, `readerOpts.export_interval_millis = 10000`.
-      (The "without performance impact" half is unmeasured — see below.)
-- [x] 4 new Grafana dashboards operational (Fee Market, Job Queue, Validator
-      Health, Peer Quality) — all four JSONs are under
-      `docker/telemetry/grafana/dashboards/`
-- [x] 2 existing dashboards updated with new panel groups — `node-health`
-      (NodeStore I/O, Caches, Server Info, Complete Ledgers & DB, Ledger
-      Economy, Job Queue Concurrency Limits rows) and `rpc-performance`
-      (per-method section)
-- [ ] Integration test validates all new metric families are non-zero — not on
-      this branch; lives in the Phase 10 harness (`expected_metrics.json`)
-- [ ] No performance regression (< 0.5% CPU overhead from new callbacks) — not
-      measured; needs the Phase 10 benchmark suite
-- [x] Documentation updated with full new metric inventory —
-      `09-data-collection-reference.md` §5b + "Phase 9: OTel SDK-Exported
-      Metrics (MetricsRegistry)" + "Phase 7+: External Dashboard Parity Metrics"
-- [x] Validator Health dashboard ships (17 panels, 4 more than the 13 planned)
-- [x] Peer Quality dashboard ships (6 panels)
-- [x] Ledger Economy panels added to node-health dashboard (5 panels in a
-      "Ledger Economy" row)
-- [x] Provisioned Grafana alerting: 13 rules / 5 groups, 2 contact points,
-      nested notification policy
-- [ ] Tasks 9.14-9.17 closed — **open by design**: 9.14 documented-not-fixed
-      (defects 1, 3 and 4 still blocked; defect 2 unblocked but not yet fixed),
-      9.15 and 9.16 not implemented, 9.17 deferred pending approval and volume
-      measurement
-
----
-
-## Appendix: Alerting Design
-
-> Design for the provisioned Grafana alert rules (Task 9.9a). Previously a standalone spec; merged here so the phase plan is self-contained.
-
-**Date:** 2026-07-06
-**Branch:** `pratik/otel-phase9-metric-gap-fill` (PR #6513)
-**Status:** Approved
-
-### Purpose
-
-Phase 9 exports ~68 internal xrpld metrics and ships Grafana dashboards for
-them. This adds the missing operator-facing piece: **provisioned Grafana alert
-rules** that fire on the health-critical metrics phase 9 introduces. The
-phase-9 task list already lists "alerting rules" as a phase-9 deliverable
-(Task 9.9), so this closes that gap.
-
-Scope is deliberately narrow — the three subsystems whose failure is
-node-fatal: **consensus/ledger health, validator health, job queue**. RPC/API
-health is explicitly out of scope.
-
-### Why phase 9 (not phase 11)
-
-Every metric these alerts fire on is _born_ in phase 9
-(`ledger_history_mismatch_total`, `ledgers_closed_total`,
-`validation_missed_total`, `validations_checked_total`,
-`jq_trans_overflow_total`, `job_queued_us_bucket` — the histogram instrument is
-`job_queued_us` (`MetricsRegistry.cpp:94`), so the Prometheus bucket series is
-`job_queued_us_bucket`, not `job_queued_duration_us_bucket`). Alerts
-belong with the metrics they watch, and this is where the dependency lives.
-
-### Delivery
-
-Provisioned YAML, version-controlled — matching the existing datasource /
-dashboard provisioning pattern. No docker-compose change: the Grafana service
-already mounts `./grafana/provisioning:/etc/grafana/provisioning:ro`, and
-Grafana auto-loads `provisioning/alerting/*.yaml`.
-
-New files under `docker/telemetry/grafana/provisioning/alerting/`:
-
-| File                 | Purpose                                                                                                                                                                                                                      |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `contactpoints.yaml` | **Two** contact points: `xrpld-default` (Slack) and `xrpld-critical` (Slack + email).                                                                                                                                        |
-| `policies.yaml`      | **Nested** notification policy: root route → `xrpld-default`; child route matching `severity = critical` → `xrpld-critical` (`repeat_interval: 1h` vs the root's `4h`). Both grouped by `alertname` + `service_instance_id`. |
-| `rules.yaml`         | **13** alert rules across **5** groups (below).                                                                                                                                                                              |
-
-Plus the Alerting section of `docs/telemetry-runbook.md` — operator runbook:
-what each alert means, likely causes, and how to point the contact point at a
-real receiver.
-
-### Alert rules
-
-All rules target Prometheus datasource `uid: prometheus`. Each rule uses the
-Grafana rule shape: query (A) → reduce (B, last value) → threshold (C). All
-`rate()`/`histogram_quantile()` expressions aggregate with
-`sum by (service_instance_id)` (or `+ le`) so **each node alerts independently**.
-Alert rules run headless, so they cannot use the dashboards' `$node` template
-variables — they match all series and group by `service_instance_id` instead.
-
-All 5 groups evaluate at `interval: 1m`. Metric names carry **no** `xrpld_`
-prefix — `OTelCollectorImp::formatName()` adds none.
-
-The **Threshold** column is the rule's refId `C` evaluator, read straight from
-`rules.yaml` — it is the firing condition, so it is load-bearing, not decoration.
-
-| Group              | Alert                   | Expression (refId A)                                                                                      | Threshold (refId C)                               | `for` | severity |
-| ------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----- | -------- |
-| `xrpld-consensus`  | LedgerHistoryMismatch   | `sum by (service_instance_id) (increase(ledger_history_mismatch_total[15m]))`                             | `gt [0]`                                          | 2m    | critical |
-| `xrpld-consensus`  | LedgerCloseStalled      | `rate(ledgers_closed_total)` decayed to ≈0                                                                | `lt [0.001]`                                      | 3m    | critical |
-| `xrpld-consensus`  | ValidatedLedgerStale    | `max by (service_instance_id) (ledgermaster_validated_ledger_age < 1209600)`                              | `gt [60]` (seconds)                               | 5m    | critical |
-| `xrpld-validator`  | ValidationsMissed       | miss **ratio**, gated on send activity — see the expression below the table                               | `gt [0.1]`                                        | 15m   | warning  |
-| `xrpld-validator`  | ValidationsNotChecked   | `rate(validations_checked_total)` ≈0                                                                      | `lt [0.001]`                                      | 5m    | warning  |
-| `xrpld-jobqueue`   | JobQueueTxOverflow      | `sum by (service_instance_id) (increase(jq_trans_overflow_total[15m]))`                                   | `gt [0]`                                          | 2m    | warning  |
-| `xrpld-jobqueue`   | JobQueueLatencyHigh     | `histogram_quantile(0.99, sum by (le, service_instance_id) (rate(job_queued_us_bucket[5m])))`             | `gt [1000000]` (µs = 1s)                          | 5m    | warning  |
-| `xrpld-jobqueue`   | NodeStoreIOLatencyHigh  | `histogram_quantile(0.95, sum by (le, service_instance_id) (rate(ios_latency_milliseconds_bucket[10m])))` | `gt [1000]` (ms)                                  | 10m   | warning  |
-| `xrpld-node-state` | NodeStateFlapping       | state-transition rate over the node-state series                                                          | `gt [3]` (transitions)                            | 15m   | warning  |
-| `xrpld-node-state` | NodeNotFull             | operating mode below FULL                                                                                 | `lt [4]` (FULL = 4)                               | 15m   | warning  |
-| `xrpld-overlay`    | ManifestJobQueueConvoy  | `sum by (service_instance_id) (jobq_manifest_waiting)`                                                    | `gt [3]` (waiting jobs)                           | 10m   | warning  |
-| `xrpld-overlay`    | ManifestFloodInbound    | inbound manifest byte rate                                                                                | `gt [524288]` (B/s = 512 **KiB**/s, not 512 kB/s) | 10m   | warning  |
-| `xrpld-overlay`    | PeerResourceDisconnects | `sum by (service_instance_id) (increase(server_info{metric="peer_disconnects_resources"}[30m]))`          | `gt [5]`                                          | 5m    | warning  |
-
-**`ValidationsMissed` is a gated ratio, not `rate(...) > 0`.** The raw-rate shape
-is the pre-fix version and it fires on **every non-validating node**:
-`ValidationTracker` counts a miss whenever `weValidated && networkValidated` is
-not both true, and a non-validator never sets `weValidated`, so its measured
-ratio is exactly **1.0**. No threshold can separate "not a validator" from
-"validator disagreeing", hence the `and on (...)` activity gate. The shipped
-expression is:
-
-- numerator: `sum by (service_instance_id) (rate(validation_missed_total[15m]))`
-- denominator: `clamp_min(` that same numerator `+ sum by (service_instance_id) (rate(validation_agreements_total[15m])), 1e-9)`
-- gate: `and on (service_instance_id) (sum by (service_instance_id) (rate(validations_sent_total[15m])) > 0)`
-- evaluator: `gt [0.1]` — i.e. >10% disagreement among nodes that do validate
-
-3 rules are `severity: critical`, 10 are `severity: warning`.
-
-Each rule carries labels `severity` and `category`
-and annotations `summary` + `description` (with `{{ $labels.service_instance_id }}`
-and `{{ $values.B.Value }}` interpolation).
-
-#### Threshold rationale
-
-- **LedgerCloseStalled `< 0.001` for 3m**: healthy nodes close a ledger every
-  ~3-5s; a 5m rate decaying to ~0 means the node is stuck. The epsilon (not
-  exact `0`) avoids float rate-noise suppressing the alert.
-- **JobQueueLatencyHigh 1s p99**: `gt [1000000]` µs = 1s. A default starting
-  point, easy to tune — jobs queued >1s at p99 indicate the node is saturated.
-- **ValidationsMissed `> 0.1` on a gated ratio**, not `> 0` on a raw rate: the
-  raw rate is permanently nonzero (ratio 1.0) on non-validators, so a `> 0` rule
-  pages on every non-validating node in the fleet. See the note above the
-  rationale list.
-- **ManifestFloodInbound 524288 B/s**: an earlier 50 kB/s threshold produced ~41
-  sustained 5-minute samples on healthy nodes; 512 KiB/s clears normal
-  manifest-exchange peaks.
-- Remaining `gt [0]` rules (`LedgerHistoryMismatch`, `JobQueueTxOverflow`) sit on
-  true error counters where any sustained nonzero rate is actionable.
-
-### Non-goals / YAGNI
-
-- No per-alert silencing schedules, no mute timings.
-- No RPC/API or fee-market alerts (dashboards cover those visually). Overlay
-  alerts _were_ added during implementation — the `xrpld-overlay` group carries
-  three (manifest convoy, manifest flood, peer resource disconnects).
-- Two contact points and a two-level policy tree shipped; deeper routing
-  (Discord, PagerDuty, per-team splits) is left to the operator.
-
-### Verification
-
-1. `yamllint` (or `python -c yaml.safe_load`) on all three YAML files.
-2. `docker compose -f docker/telemetry/docker-compose.yml config -q` still parses.
-3. Optional live check: start stack, `GET /api/v1/provisioning/alert-rules`
-   returns the 13 rules; Grafana logs show no provisioning errors.
-4. Code-review pass (subagent) against phase conventions before commit.

README.md

@@ -54,7 +54,6 @@ Here are some good places to start learning the source code:
 | `./docs`   | Source documentation files and doxygen config. |
 | `./cfg`    | Example configuration files.                   |
 | `./src`    | Source code.                                   |
-| `./crates` | Rust source code.                              |
 
 Some of the directories under `src` are external repositories included using
 git-subtree. See those directories' README files for more details.

bin/check-nix-store-refs.sh

@@ -1,111 +0,0 @@
-#!/usr/bin/env bash
-# Fail if a binary under <path> records a /nix/store path it resolves at run
-# time. See docs/build/nix.md#prebuilt-packages for why that matters.
-#
-# <path> is a file or a directory. macOS: nothing may reference the store, so
-# point it at whole trees. Linux: the toolchain always writes the store into
-# PT_INTERP and RUNPATH, so only at what cmake/PatchNixBinary.cmake retargets.
-#
-# Only Mach-O / ELF is inspected. Static archives hold store paths in debug info
-# alone; the scripts in a Conan cache are all git hook samples and autotools
-# scratch, 36 false positives to 0 real.
-#
-# Usage: bin/check-nix-store-refs.sh <path>
-
-set -euo pipefail
-
-if [ "$#" -ne 1 ]; then
-    echo "usage: $0 <path>" >&2
-    exit 2
-fi
-
-if [ ! -e "$1" ]; then
-    echo "$0: no such path: $1" >&2
-    exit 2
-fi
-
-case "$(uname -s)" in
-    Darwin)
-        format=Mach-O
-        recorded_paths=macho_recorded_paths
-        tool=otool
-        ;;
-    Linux)
-        format=ELF
-        recorded_paths=elf_recorded_paths
-        tool=readelf
-        ;;
-    *)
-        echo "Unsupported OS - skipping the Nix store reference check."
-        exit 0
-        ;;
-esac
-
-# `pipefail` would catch this too, but only as a bare nonzero exit.
-if ! command -v "${tool}" >/dev/null; then
-    echo "$0: ${tool} not found; cannot inspect binaries" >&2
-    exit 2
-fi
-
-# Both list what the file records. `ldd` would answer what this machine resolves
-# now, which is wrong both ways: store paths for a correctly patched binary,
-# silence for a store RUNPATH that resolves nowhere.
-
-# `name` covers LC_ID_DYLIB and LC_LOAD*_DYLIB, `path` covers LC_RPATH.
-macho_recorded_paths() {
-    otool -l "$1" | sed -nE 's#^ *(name|path) ([^ ]*).*#\2#p'
-}
-
-# RPATH and RUNPATH are colon-separated.
-elf_recorded_paths() {
-    readelf -ldW "$1" |
-        sed -nE \
-            -e 's#.*program interpreter: ([^]]*)\].*#\1#p' \
-            -e 's#.*\((RPATH|RUNPATH|NEEDED)\).*\[([^]]*)\].*#\2#p' |
-        tr ':' '\n'
-}
-
-checked=0
-skipped=0
-leaked=0
-
-while IFS= read -r file; do
-    case "$(file -b "${file}" 2>/dev/null)" in
-        *"${format}"*) ;;
-        *)
-            skipped=$((skipped + 1))
-            continue
-            ;;
-    esac
-    checked=$((checked + 1))
-
-    # Filter after extracting, or a search path starting elsewhere ($ORIGIN)
-    # hides the rest. `sed` not `grep`: grep calls "no matches" a failure, and
-    # the `|| true` that would need masks a broken pipeline too.
-    refs="$("${recorded_paths}" "${file}" | sed -n '\#^/nix/store/#p' | sort -u)"
-    if [ -n "${refs}" ]; then
-        leaked=$((leaked + 1))
-        echo "::error file=${file}::references the Nix store at run time"
-        echo "${file}"
-        echo "${refs}" | sed 's/^/    /'
-    fi
-done < <(find "$1" -type f \( -perm -u+x -o -name '*.dylib' -o -name '*.so*' \))
-
-echo "$1: checked ${checked}, skipped ${skipped}, ${leaked} with Nix store references."
-
-if [ "${leaked}" -ne 0 ]; then
-    cat >&2 <<'EOF'
-
-Fixes, in order of preference:
-  - A Conan package built before this check existed: drop it
-    (`conan remove '<name>/*'`) and rebuild.
-  - A binary that should have been retargeted to the system loader: check that
-    cmake/PatchNixBinary.cmake ran for it.
-  - Link the macOS system library instead of the Nix one - see
-    libresolvSystemStub in nix/darwin.nix.
-  - No system library exists (libstdc++): link it statically.
-  - None of the above: pin the toolchain into the package ID, following
-    `user.package:libc_version` in conan/profiles/ci.
-EOF
-    exit 1
-fi

bin/check-tools.sh

@@ -15,14 +15,10 @@
 #   - Windows: the core build tools only (CMake, Conan, Git, Python).
 #              MSVC is expected to be provided separately and is not checked here.
 #
-# Some tools (clang-format, clang-tidy, doxygen, gcovr, gh, git-cliff, gpg,
-# pre-commit, run-clang-tidy) are present in our Linux CI images and in local
-# development setups, but not in the macOS CI environment. They are checked
-# everywhere except when running in CI on macOS.
-#
-# Tools that Nix also exposes under a version-suffixed name (`clang-tidy-22`,
-# `g++-15`, ...) are probed under both names: a suffixed name can break while
-# the plain one still works (see mkVersionedToolLinks in nix/packages.nix).
+# Some tools (clang-format, doxygen, gcovr, gh, git-cliff, gpg, pre-commit,
+# run-clang-tidy) are present in our Linux CI images and in local development
+# setups, but not in the macOS CI environment. They are checked everywhere
+# except when running in CI on macOS.
 #
 # Environment variables:
 #   CI                      if set, skip the tools above when on macOS.
@@ -30,27 +26,14 @@
 
 set -uo pipefail
 
-# Version suffixes of the Nix tool links, tracking nix/packages.nix.
-gcc_version=15
-llvm_version=22
-
 missing=()
 checked=0
 
-# tool_path <name>
-# Fully resolved path of a tool, so the snapshots record which derivation
-# provides it. Prints nothing when it isn't on PATH.
-tool_path() {
-    local path
-    path="$(command -v "$1" 2>/dev/null)" || return 0
-    readlink -f "${path}" 2>/dev/null || printf '%s' "${path}"
-}
-
 # check <name> [probe-command...]
 # Runs the probe (default: "<name> --version"), capturing both stdout and
-# stderr, and prints three lines: the status and name, the first non-blank line
-# of the probe output (its version, or the error when it failed), and the tool's
-# resolved path. Records <name> as missing if it is not found or exits non-zero.
+# stderr, and prints one aligned line: the status, the name, and the first
+# non-blank line of the probe output (its version). Records <name> as missing
+# if the command is not found or exits non-zero.
 check() {
     local name="$1"
     shift
@@ -60,17 +43,14 @@ check() {
     fi
 
     checked=$((checked + 1))
-    local output version path
-    path="$(tool_path "${name}")"
+    local output version
     if output="$("${probe[@]}" 2>&1)"; then
-        printf '  ✅ %s\n' "${name}"
+        version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
+        printf '  [ ok ] %-20s %s\n' "${name}" "${version}"
     else
-        printf '  ❌ %s\n' "${name}"
+        printf '  [MISS] %s\n' "${name}"
         missing+=("${name}")
     fi
-    version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
-    printf '     %s\n' "${version:-(no output)}"
-    printf '     %s\n' "${path:-(not found)}"
 }
 
 case "$(uname -s)" in
@@ -102,9 +82,7 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     echo "Development tooling:"
     check ccache
     check clang
-    check "clang-${llvm_version}"
     check clang++
-    check "clang++-${llvm_version}"
     check ClangBuildAnalyzer
     check curl
     check file
@@ -123,14 +101,7 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     # setups, but not in the macOS CI environment. So check them everywhere
     # except when running in CI on macOS.
     if [ "${os}" = "linux" ] || [ -z "${CI:-}" ]; then
-        check clang-apply-replacements
-        check "clang-apply-replacements-${llvm_version}"
         check clang-format
-        check "clang-format-${llvm_version}"
-        # clang-tidy leads --version with the LLVM banner, not the version.
-        tidy_probe="--version | grep -m1 -oE 'LLVM version [0-9.]+'"
-        check clang-tidy sh -c "clang-tidy ${tidy_probe}"
-        check "clang-tidy-${llvm_version}" sh -c "clang-tidy-${llvm_version} ${tidy_probe}"
         check dot
         check doxygen
         check gcovr
@@ -141,7 +112,6 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
         # pre-commit, or its alternative implementation prek
         check pre-commit sh -c 'pre-commit --version || prek --version'
         check run-clang-tidy run-clang-tidy --help
-        check "run-clang-tidy-${llvm_version}" "run-clang-tidy-${llvm_version}" --help
     fi
 fi
 
@@ -156,9 +126,8 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     check cargo-audit cargo audit --version
     check cargo-llvm-cov cargo llvm-cov --version
     check cargo-nextest cargo nextest --version
-    check clippy-driver
+    check clippy clippy-driver --version
     check rust-analyzer
-    check rust-nightly rust-nightly run rustc --version
     check rustc
     check rustfmt
 fi
@@ -169,11 +138,7 @@ if [ "${os}" = "linux" ]; then
     echo
     echo "GCC toolchain:"
     check gcc
-    check "gcc-${gcc_version}"
     check g++
-    check "g++-${gcc_version}"
-    check cpp
-    check "cpp-${gcc_version}"
     check gcov
 
     echo
@@ -198,9 +163,9 @@ else
     checked=$((checked + 1))
     tmp_clone="$(mktemp -d)"
     if git clone --depth 1 https://github.com/XRPLF/actions.git "${tmp_clone}/actions" >/dev/null 2>&1; then
-        printf '  ✅ git clone over HTTPS\n'
+        printf '  [ ok ] git clone over HTTPS\n'
     else
-        printf '  ❌ git clone over HTTPS\n'
+        printf '  [MISS] git clone over HTTPS\n'
         missing+=("git-https-clone")
     fi
     rm -rf "${tmp_clone}"
@@ -208,9 +173,9 @@ fi
 
 echo
 if [ "${#missing[@]}" -eq 0 ]; then
-    echo "✅ All ${checked} checked tools are present and runnable."
+    echo "All ${checked} checked tools are present and runnable."
 else
-    echo "❌ Missing or non-functional tools (${#missing[@]} of ${checked}):" >&2
+    echo "Missing or non-functional tools (${#missing[@]} of ${checked}):" >&2
     for tool in "${missing[@]}"; do
         echo "  - ${tool}" >&2
     done

bin/pre-commit/check_rust_coverage_attrs.py

@@ -1,149 +0,0 @@
-#!/usr/bin/env python3
-"""
-Check that Rust unit tests stay out of the coverage report.
-
-cargo-llvm-cov instruments the test code along with everything else, so a test
-module that is not excluded counts its own body as covered and inflates the
-reported number. Excluding it takes two attributes:
-
-  * every `#[cfg(test)]` module carries
-    `#[cfg_attr(coverage_nightly, coverage(off))]`;
-  * every crate root (lib.rs, main.rs) carries
-    `#![cfg_attr(coverage_nightly, feature(coverage_attribute))]`, which the
-    attribute above needs in order to compile.
-
-Both are inert outside the coverage job: cargo-llvm-cov defines
-`coverage_nightly` only when it runs on a nightly toolchain.
-
-The crate-root gate is checked even in a crate that has no tests yet, because
-that is what lets the first test module added later carry the attribute without
-a build failure. Missing it is a hard error, so it cannot go unnoticed; a
-missing `coverage(off)` fails open, which is why this check exists.
-
-Matching is on exact attribute text, which works because `cargo fmt` runs over
-the whole workspace in the hook ahead of this one: rustfmt puts every attribute
-on its own line and normalizes what is inside it, turning `#[cfg( test )]`
-and `#[cfg(test,)]` alike into `#[cfg(test)]`. So there is nothing here that
-parses Rust. The price is that a cfg this file does not spell out literally --
-`all(test, ...)`, `any(test, ...)`, `not(test)` -- is reported rather than
-classified, on the grounds that guessing at coverage semantics is how a check
-like this ends up quietly wrong.
-
-Usage: ./bin/pre-commit/check_rust_coverage_attrs.py <file1> <file2> ...
-
-Exit status is non-zero if any violation is found.
-"""
-
-import re
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-CRATE_ROOTS = {"lib.rs", "main.rs"}
-
-FEATURE_ATTR = "#![cfg_attr(coverage_nightly, feature(coverage_attribute))]"
-COVERAGE_OFF_ATTR = "#[cfg_attr(coverage_nightly, coverage(off))]"
-CFG_TEST_ATTR = "#[cfg(test)]"
-
-# Any other cfg that mentions `test`. String literals are blanked before this
-# runs, so `feature = "test"` does not read as the `test` cfg.
-RE_CFG_MENTIONS_TEST = re.compile(r"^#\[cfg\(.*\btest\b.*\)\]$")
-RE_STRING = re.compile(r'"(?:[^"\\]|\\.)*"')
-RE_MOD = re.compile(r"^(?:pub(?:\([^)]*\))?\s+)?mod\s+([A-Za-z_]\w*)")
-
-
-@dataclass(frozen=True)
-class Finding:
-    line: int
-    label: str
-    message: str
-
-
-def _check_module(attrs: list[str], line: int, name: str) -> list[Finding]:
-    """Findings for one module, given the attributes attached to it."""
-    if COVERAGE_OFF_ATTR in attrs:
-        return []  # excluded from coverage; which cfg gates it does not matter
-    if CFG_TEST_ATTR in attrs:
-        return [
-            Finding(
-                line,
-                "missing-coverage-off",
-                f"`mod {name}` is #[cfg(test)] but not excluded from coverage; "
-                f"add {COVERAGE_OFF_ATTR}",
-            )
-        ]
-    unclassified = [
-        attr for attr in attrs if RE_CFG_MENTIONS_TEST.match(RE_STRING.sub('""', attr))
-    ]
-    if unclassified:
-        return [
-            Finding(
-                line,
-                "unclassified-cfg",
-                f"`mod {name}` is gated on {unclassified[0]}, which this check "
-                f"cannot tell apart from a module that ships in the library; "
-                f"add {COVERAGE_OFF_ATTR} if it is test-only, or teach this "
-                f"check the cfg if it is not",
-            )
-        ]
-    return []
-
-
-def _check_test_modules(lines: list[str]) -> list[Finding]:
-    """Findings for every test module that is not excluded from coverage."""
-    findings: list[Finding] = []
-    attrs: list[str] = []
-    attrs_line = 0
-    for number, raw in enumerate(lines, start=1):
-        stripped = raw.strip()
-        # Blank lines and comments are allowed between an attribute and its item.
-        if not stripped or stripped.startswith("//"):
-            continue
-        if stripped.startswith("#["):
-            if not attrs:
-                attrs_line = number
-            attrs.append(stripped)
-            continue
-        module = RE_MOD.match(stripped)
-        if module is not None and attrs:
-            findings += _check_module(attrs, attrs_line, module.group(1))
-        attrs = []
-    return findings
-
-
-def _check_crate_root(name: str, lines: list[str]) -> list[Finding]:
-    """A finding if a crate root is missing the coverage_attribute feature gate."""
-    if name not in CRATE_ROOTS:
-        return []
-    if any(line.strip() == FEATURE_ATTR for line in lines):
-        return []
-    return [
-        Finding(
-            1,
-            "missing-feature-gate",
-            f"crate root is missing {FEATURE_ATTR}",
-        )
-    ]
-
-
-def check_source(name: str, text: str) -> list[Finding]:
-    """Findings for one file's contents; `name` is its base name (lib.rs, ...)."""
-    lines = text.splitlines()
-    return _check_crate_root(name, lines) + _check_test_modules(lines)
-
-
-def check_file(path: Path) -> list[Finding]:
-    return check_source(path.name, path.read_text(encoding="utf-8"))
-
-
-def main() -> int:
-    total = 0
-    for path in (Path(name) for name in sys.argv[1:]):
-        for finding in check_file(path):
-            total += 1
-            print(f"{path}:{finding.line}: {finding.label}: {finding.message}")
-    return 1 if total else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bin/pre-commit/fix_gtest_names.py

@@ -1,144 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-Rewrites gtest names to the required style in this project: the suite name is
-CamelCase, the test-case name is snake_case.
-
-    TEST(SuiteName, test_case_name)
-
-The gtest `DISABLED_` prefix is kept verbatim on either name.
-
-Both conversions fold acronyms the way a reader expects:
-`SetAndResetAccountTxnID` -> `set_and_reset_account_txn_id`, not
-`set_and_reset_account_txn_i_d`.
-
-The first argument of `TEST_F`, `TEST_P`, `TYPED_TEST` and `TYPED_TEST_P` is a
-fixture class rather than a free identifier, so rewriting it here would leave
-the class it names behind. Those are reported for a human to rename (clang-tidy
-checks the class declaration itself, via readability-identifier-naming).
-
-Usage: ./bin/pre-commit/fix_gtest_names.py <file1> <file2> ...
-"""
-
-import re
-import sys
-from collections import Counter
-from pathlib import Path
-
-# A test-case definition, `MACRO(SuiteOrFixture, TestName)`, anchored at the
-# start of a line so that commented-out definitions and project macros that
-# merely look similar (`TEST_EXPECT(...)`) are left alone. The `\s*` between
-# arguments allows for a definition clang-format wrapped over several lines.
-PATTERN = re.compile(
-    r"(?P<head>^[ \t]*(?P<macro>TYPED_TEST_P|TYPED_TEST|TEST_F|TEST_P|TEST)\s*\(\s*)"
-    r"(?P<suite>\w+)(?P<mid>\s*,\s*)(?P<name>\w+)(?P<tail>\s*\))",
-    re.MULTILINE,
-)
-
-# The macros whose first argument names a fixture class, not a free identifier.
-FIXTURE_MACROS = ("TEST_F", "TEST_P", "TYPED_TEST", "TYPED_TEST_P")
-
-DISABLED = "DISABLED_"
-
-ACRONYM_BOUNDARY = re.compile(r"([A-Z]+)([A-Z][a-z])")
-WORD_BOUNDARY = re.compile(r"([a-z\d])([A-Z])")
-
-
-def _split_disabled(name: str) -> tuple[str, str]:
-    """Splits off gtest's `DISABLED_` prefix, which is kept verbatim."""
-    if name.startswith(DISABLED):
-        return DISABLED, name[len(DISABLED) :]
-    return "", name
-
-
-def snake_case(name: str) -> str:
-    """Returns the name in snake_case, leaving acronyms whole.
-
-    `SetAndResetAccountTxnID` -> `set_and_reset_account_txn_id`,
-    `parseStatRSSkB` -> `parse_stat_rs_sk_b`.
-    """
-    prefix, core = _split_disabled(name)
-    core = ACRONYM_BOUNDARY.sub(r"\1_\2", core)
-    return prefix + WORD_BOUNDARY.sub(r"\1_\2", core).lower()
-
-
-def camel_case(name: str) -> str:
-    """Returns the name in CamelCase, capitalizing each underscored word.
-
-    Only the letters that have to change are touched, so acronyms survive: a
-    conversion that went via snake_case would turn `SHAMapTest` into
-    `ShaMapTest`, whereas here it is already CamelCase and stays put.
-    `json_value` -> `JsonValue`, `parseStatRSSkB` -> `ParseStatRSSkB`.
-    """
-    prefix, core = _split_disabled(name)
-    return prefix + "".join(w[:1].upper() + w[1:] for w in core.split("_") if w)
-
-
-def _corrected(match: re.Match) -> tuple[str, str]:
-    """Returns the suite and test-case names this definition should end up with."""
-    suite = match["suite"]
-    return (
-        suite if match["macro"] in FIXTURE_MACROS else camel_case(suite),
-        snake_case(match["name"]),
-    )
-
-
-def fix_source(text: str) -> tuple[str, list[str]]:
-    """Returns the corrected text and one `line: message` report per bad name."""
-    # gtest joins the suite and test names into one class name, so two test
-    # cases whose joined names agree cannot coexist: `TEST(a, b_c)` and
-    # `TEST(a_b, c)` both define `a_b_c_Test`. A rename that would introduce
-    # such a clash is reported for a human instead of applied.
-    joined = Counter("_".join(_corrected(m)) for m in PATTERN.finditer(text))
-    reports = []
-
-    def rewrite(match: re.Match) -> str:
-        suite, name = match["suite"], match["name"]
-        new_suite, new_name = _corrected(match)
-        line = text.count("\n", 0, match.start()) + 1
-
-        if match["macro"] in FIXTURE_MACROS and camel_case(suite) != suite:
-            reports.append(
-                f"{line}: fixture '{suite}' is not CamelCase: rename the class "
-                f"to '{camel_case(suite)}' by hand"
-            )
-        if (new_suite, new_name) == (suite, name):
-            return match[0]
-        if joined[f"{new_suite}_{new_name}"] > 1:
-            reports.append(
-                f"{line}: cannot rename '{suite}, {name}' to '{new_suite}, "
-                f"{new_name}': another test case already generates that name"
-            )
-            return match[0]
-        if new_suite != suite:
-            reports.append(f"{line}: renamed suite '{suite}' to '{new_suite}'")
-        if new_name != name:
-            reports.append(f"{line}: renamed test case '{name}' to '{new_name}'")
-        return match["head"] + new_suite + match["mid"] + new_name + match["tail"]
-
-    return PATTERN.sub(rewrite, text), reports
-
-
-def fix_names(path: Path) -> bool:
-    """Corrects one file's gtest names, reporting each on stdout."""
-    original = path.read_text(encoding="utf-8")
-    fixed, reports = fix_source(original)
-    for report in reports:
-        print(f"{path}:{report}")
-    if fixed != original:
-        path.write_text(fixed, encoding="utf-8")
-    return not reports
-
-
-def main() -> int:
-    files = [Path(f) for f in sys.argv[1:]]
-    success = True
-
-    for path in files:
-        success &= fix_names(path)
-
-    return 0 if success else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bin/pre-commit/test_fix_gtest_names.py

@@ -1,259 +0,0 @@
-#!/usr/bin/env python3
-"""
-Tests for fix_gtest_names.py.
-
-Run directly (no test framework needed):
-    ./bin/pre-commit/test_fix_gtest_names.py
-or under pytest:
-    pytest bin/pre-commit/test_fix_gtest_names.py
-"""
-
-import sys
-import textwrap
-
-from fix_gtest_names import camel_case, fix_source, snake_case
-
-
-def dedent(text: str) -> str:
-    """Removes a fixture's common indentation and its leading newline.
-
-    Lets fixtures be written as indented triple-quoted here-docs while keeping
-    honest 1-based line numbers.
-    """
-    return textwrap.dedent(text).lstrip("\n")
-
-
-def fixed(text: str) -> str:
-    return fix_source(dedent(text))[0]
-
-
-def reports(text: str) -> list[str]:
-    return fix_source(dedent(text))[1]
-
-
-# --- conversion --------------------------------------------------------------
-
-
-def test_snake_case_conversion() -> None:
-    assert snake_case("BadInputs") == "bad_inputs"
-    assert snake_case("mulDiv") == "mul_div"
-    assert snake_case("already_snake") == "already_snake"
-    assert snake_case("base64") == "base64"
-
-
-def test_snake_case_keeps_acronyms_whole() -> None:
-    assert snake_case("SetAndResetAccountTxnID") == "set_and_reset_account_txn_id"
-    assert snake_case("XRPToIOU") == "xrp_to_iou"
-    assert snake_case("STAmountMath") == "st_amount_math"
-
-
-def test_camel_case_conversion() -> None:
-    assert camel_case("json_value") == "JsonValue"
-    assert camel_case("mulDiv") == "MulDiv"
-    assert camel_case("scope") == "Scope"
-    assert camel_case("base64") == "Base64"
-
-
-def test_camel_case_leaves_acronyms_alone() -> None:
-    # A snake_case round-trip would give `ShaMapTest` / `ParseStatmRsSkB` here.
-    assert camel_case("SHAMapTest") == "SHAMapTest"
-    assert camel_case("parseStatmRSSkB") == "ParseStatmRSSkB"
-    assert camel_case("XRPAmount") == "XRPAmount"
-    assert camel_case("CSPRNG") == "CSPRNG"
-
-
-def test_disabled_prefix_preserved() -> None:
-    assert snake_case("DISABLED_FooBar") == "DISABLED_foo_bar"
-    assert snake_case("DISABLED_foo_bar") == "DISABLED_foo_bar"
-    assert snake_case("DISABLED_") == "DISABLED_"
-    assert camel_case("DISABLED_foo_bar") == "DISABLED_FooBar"
-    assert camel_case("DISABLED_") == "DISABLED_"
-
-
-# --- what counts as a test definition ---------------------------------------
-
-
-def test_all_macros_recognized() -> None:
-    code = """
-    TEST(Suite, oneName)
-    TEST_F(Fixture, twoName)
-    TEST_P(Fixture, threeName)
-    TYPED_TEST(Fixture, fourName)
-    TYPED_TEST_P(Fixture, fiveName)
-    """
-    assert fixed(code) == dedent("""
-        TEST(Suite, one_name)
-        TEST_F(Fixture, two_name)
-        TEST_P(Fixture, three_name)
-        TYPED_TEST(Fixture, four_name)
-        TYPED_TEST_P(Fixture, five_name)
-        """)
-
-
-def test_conforming_definitions_untouched() -> None:
-    code = """
-    TEST(AccountSet, bad_inputs)
-    TEST_F(MutexMakeTest, default_constructor)
-    TEST(SHAMap, DISABLED_slow_path)
-    """
-    assert reports(code) == []
-    assert fixed(code) == dedent(code)
-
-
-def test_lookalikes_ignored() -> None:
-    code = """
-    // TEST(Suite, notATest)
-    TEST_EXPECT(someCall())
-    TEST_EXPECTS(amount == value, amount.getText())
-    INSTANTIATE_TEST_SUITE_P(Prefix, Fixture, testValues());
-    auto x = TEST(Suite, notATest);
-    TYPED_TEST_SUITE(Fixture, MyTypes);
-    """
-    assert reports(code) == []
-    assert fixed(code) == dedent(code)
-
-
-def test_indented_and_wrapped_definitions() -> None:
-    code = """
-    namespace ripple {
-        TEST(Suite, indentedName)
-    }
-    TEST_F(
-        SomeVeryLongFixtureName,
-        wrappedName)
-    """
-    assert fixed(code) == dedent("""
-        namespace ripple {
-            TEST(Suite, indented_name)
-        }
-        TEST_F(
-            SomeVeryLongFixtureName,
-            wrapped_name)
-        """)
-
-
-# --- rewriting --------------------------------------------------------------
-
-
-def test_only_the_two_names_are_rewritten() -> None:
-    code = """
-    TEST(mulDiv, mulDiv)
-    {
-        auto const mulDiv = 1;  // mulDiv stays
-    }
-    """
-    assert fixed(code) == dedent("""
-        TEST(MulDiv, mul_div)
-        {
-            auto const mulDiv = 1;  // mulDiv stays
-        }
-        """)
-
-
-def test_suite_name_camel_cased() -> None:
-    code = """
-    TEST(json_value, limits)
-    TEST(scope, ScopeExit)
-    """
-    assert reports(code) == [
-        "1: renamed suite 'json_value' to 'JsonValue'",
-        "2: renamed suite 'scope' to 'Scope'",
-        "2: renamed test case 'ScopeExit' to 'scope_exit'",
-    ]
-    assert fixed(code) == dedent("""
-        TEST(JsonValue, limits)
-        TEST(Scope, scope_exit)
-        """)
-
-
-def test_fixture_reported_but_not_renamed() -> None:
-    # The first argument names a class, so only a human (or clang-tidy) can
-    # rename it; the test-case name is still fixed.
-    code = """
-    TEST_F(my_fixture, someTest)
-    """
-    assert reports(code) == [
-        "1: fixture 'my_fixture' is not CamelCase: rename the class to "
-        "'MyFixture' by hand",
-        "1: renamed test case 'someTest' to 'some_test'",
-    ]
-    assert fixed(code) == dedent("""
-        TEST_F(my_fixture, some_test)
-        """)
-
-
-def test_reports_carry_line_numbers() -> None:
-    code = """
-    #include <foo.h>
-
-    TEST(Suite, firstName)
-
-    TEST(Suite, secondName)
-    """
-    assert reports(code) == [
-        "3: renamed test case 'firstName' to 'first_name'",
-        "5: renamed test case 'secondName' to 'second_name'",
-    ]
-
-
-# --- collisions -------------------------------------------------------------
-
-
-def test_collision_reported_and_not_applied() -> None:
-    # Both would define `Suite_mul_div_Test`.
-    code = """
-    TEST(Suite, mulDiv)
-    TEST(Suite, mul_div)
-    """
-    assert reports(code) == [
-        "1: cannot rename 'Suite, mulDiv' to 'Suite, mul_div': another test "
-        "case already generates that name"
-    ]
-    assert fixed(code) == dedent(code)
-
-
-def test_collision_between_converging_suites() -> None:
-    # Both suites camel-case to `SuiteA`, so both would define
-    # `SuiteA_one_test_Test`.
-    code = """
-    TEST(SuiteA, oneTest)
-    TEST(Suite_a, one_test)
-    """
-    assert [r.split(":")[1].strip() for r in reports(code)] == [
-        "cannot rename 'SuiteA, oneTest' to 'SuiteA, one_test'",
-        "cannot rename 'Suite_a, one_test' to 'SuiteA, one_test'",
-    ]
-    assert fixed(code) == dedent(code)
-
-
-def test_same_name_in_different_suites_is_not_a_collision() -> None:
-    code = """
-    TEST(SuiteOne, mulDiv)
-    TEST(SuiteTwo, mulDiv)
-    """
-    assert fixed(code) == dedent("""
-        TEST(SuiteOne, mul_div)
-        TEST(SuiteTwo, mul_div)
-        """)
-
-
-def main() -> int:
-    tests = sorted(
-        (name, fn)
-        for name, fn in globals().items()
-        if name.startswith("test_") and callable(fn)
-    )
-    failed = 0
-    for name, fn in tests:
-        try:
-            fn()
-            print(f"PASS {name}")
-        except AssertionError as exc:
-            failed += 1
-            print(f"FAIL {name}: {exc!r}")
-    print(f"\n{len(tests) - failed}/{len(tests)} passed")
-    return 1 if failed else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

cfg/xrpld-example.cfg

@@ -488,17 +488,6 @@
 #   Must be a number between 100 and 1000, defaults to 250
 #
 #
-# [max_subscriptions_per_connection]
-#
-#   Maximum number of account, real-time account, and account-history
-#   subscriptions a single client connection may hold at once. Bounds the
-#   per-connection state torn down when the connection disconnects. Book
-#   subscriptions are tracked separately and are not counted here.
-#
-#   Defaults to 100000 if not set; large enough for legitimate power users
-#   such as block explorers.
-#
-#
 # [overlay]
 #
 #   Controls settings related to the peer to peer overlay.
@@ -549,45 +538,6 @@
 #       only be used for local testing and debugging. Do not disable
 #       on mainnet.
 #
-#   max_untrusted_count = <number>
-#
-#       The number of manifests the server keeps for validators it does not
-#       list, and the number it sends and processes in a single peer protocol
-#       message. Once the server holds this many, a manifest for a new
-#       unlisted validator is rejected, so peer gossip cannot grow the cache
-#       without end.
-#
-#       This option can take any value between 50 and 1000, inclusive. If
-#       the option is not present the server uses its built-in value.
-#
-#       The current default (which is subject to change) is 300.
-#
-#   max_trusted_count = <number>
-#
-#       The number of manifests for listed validators to allow for when
-#       sizing peer protocol messages. Manifests for listed validators are
-#       never dropped, whether sending or receiving, because doing so would
-#       delay a validator key change reaching this server. Set this above the
-#       number of validators the server lists.
-#
-#       Together the two counts above set the largest manifest message the
-#       server accepts: bigger messages are discarded without reading them,
-#       and without penalising the sender. Raising either means the server
-#       accepts and sends bigger messages than a peer using the defaults, and
-#       those peers will discard what this server sends. Lowering either below
-#       what peers send makes this server discard their manifest messages,
-#       which it does without recording anything.
-#
-#       This option can take any value between 50 and 1000, inclusive. If
-#       the option is not present the server uses its built-in value.
-#
-#       The current default (which is subject to change) is 300.
-#
-#       NOTE: These two options (max_untrusted_count and max_trusted_count)
-#       are transitional. They exist to bound manifest-message size and cache
-#       growth during the network upgrade. They may be removed in a future
-#       release once the fleet has upgraded, and should not be relied upon as
-#       stable configuration.
 #
 # [transaction_queue] EXPERIMENTAL
 #
@@ -1094,8 +1044,8 @@
 #                           Default is 100.
 #
 #       back_off_milliseconds
-#                           Number of milliseconds to wait between online_delete
-#                           SQL deletion batches to allow other functions
+#                           Number of milliseconds to wait between
+#                           online_delete batches to allow other functions
 #                           to catch up.
 #                           Default is 100.
 #
@@ -1109,22 +1059,10 @@
 #                           The online delete process checks periodically
 #                           that xrpld is still in sync with the network,
 #                           and that the validated ledger is less than
-#                           'age_threshold_seconds' old, and that all
-#                           recent ledgers are available. If not, then continue
+#                           'age_threshold_seconds' old. If not, then continue
 #                           sleeping for this number of seconds and
 #                           checking until healthy.
-#                           Default is 2.
-#
-#       max_waiting_ledgers
-#                           The maximum number of ledgers that may be validated
-#                           while online deletion is waiting for the node to get
-#                           fully synced with the rest of the network. If more than
-#                           this number of ledgers are validated while waiting, then
-#                           online deletion gives up on the current ledger and tries
-#                           again later. Note this only affects situations that cause
-#                           rotation to wait, such as going out of sync, or missing
-#                           ledgers. Forward progress is not penalized. Minimum is 64.
-#                           Default is the online_delete value.
+#                           Default is 5.
 #
 #   Notes:
 #       The 'node_db' entry configures the primary, persistent storage.
@@ -1267,10 +1205,10 @@
 #
 #     "server"
 #
-#       Choice of server to send metrics to, either "statsd" or "otel".
-#
-#       "statsd" sends UDP packets to a StatsD daemon, which must be running
-#       while xrpld is running. More information on StatsD is available here:
+#       Choice of server to send metrics to. Currently the only choice is
+#       "statsd" which sends UDP packets to a StatsD daemon, which must be
+#       running while xrpld is running. More information on StatsD is
+#       available here:
 #           https://github.com/b/statsd_spec
 #
 #       When server=statsd, these additional keys are used:
@@ -1281,13 +1219,6 @@
 #       "prefix"  A string prepended to each collected metric. This is used
 #                 to distinguish between different running instances of xrpld.
 #
-#       "otel" exports the same metrics over OTLP instead, and needs a build
-#       with telemetry compiled in. The [telemetry] section below owns the
-#       export destination and the resource attributes, so "address" and
-#       "prefix" do not apply. An "endpoint" key is read on this path but
-#       only appears in a startup log line; it does not change where metrics
-#       are sent.
-#
 #     If this section is missing, or the server type is unspecified or unknown,
 #     statistics are not collected or reported.
 #
@@ -1690,212 +1621,3 @@ validators.txt
 # set to ssl_verify to 0.
 [ssl_verify]
 1
-#-------------------------------------------------------------------------------
-#
-# 11. Telemetry (OpenTelemetry Tracing)
-#
-#-------------------------------------------------------------------------------
-#
-# Enables distributed tracing via OpenTelemetry. This section only has an
-# effect if tracing was compiled in: build with CMake -Dtelemetry=ON (or Conan
-# -o telemetry=True), and build it out with -Dtelemetry=OFF (or
-# -o telemetry=False), which reduces all tracing code to no-ops. The option is
-# currently ON so that CI compiles the telemetry code paths; OFF is the
-# intended default once this feature is merged, so pass the value you want
-# rather than relying on the default.
-#
-# Note that -DXRPL_ENABLE_TELEMETRY=OFF does NOT work: XRPL_ENABLE_TELEMETRY is
-# a compile definition added by the build, not a CMake option, so it disables
-# nothing. CMake only lists it at the end of configuration under
-# "Manually-specified variables were not used by the project".
-#
-# [telemetry]
-#
-# enabled=0
-#
-#   Enable or disable telemetry at runtime. Default: 0 (disabled).
-#
-# service_name=xrpld
-#
-#   OTel resource attribute `service.name`. Default: xrpld.
-#   The node's network ID (from [network_id]) is automatically added
-#   as the `xrpl.network.id` and `xrpl.network.type` resource attributes.
-#
-# service_instance_id=<node_public_key>
-#
-#   OTel resource attribute `service.instance.id`, which tells one node's
-#   telemetry apart from another's. Normally left unset: the node identity
-#   is not known when telemetry is constructed, so the server fills this in
-#   with its own Base58 node public key later during startup. Set it only
-#   to pin a stable instance name of your own choosing; doing so suppresses
-#   the node-public-key fallback.
-#   Default: the node's Base58 public key.
-#
-#   SET THIS EXPLICITLY IF YOU USE THE METRICS PIPELINE. The node-public-key
-#   fallback only reaches traces: the metrics resource is built during
-#   startup, before the node key is known, and cannot be changed afterwards.
-#   With this key unset, metrics export with an empty service.instance.id and
-#   the per-node filter on the Grafana dashboards has nothing to split on.
-#
-# traces_endpoint=http://localhost:4318/v1/traces
-#
-#   The OTLP/HTTP endpoint spans are exported to. The server sends trace
-#   data as protobuf-encoded HTTP POST requests to this URL. The full URL
-#   including the signal path is used verbatim; no other endpoint is
-#   derived from it.
-#   Default: http://localhost:4318/v1/traces.
-#
-#   beast::insight metrics ([insight] server=otel) do not follow this
-#   setting; they use metrics_endpoint below.
-#
-#   The scheme of this URL is what decides whether the connection is
-#   encrypted, and it is matched exactly: only a lower-case https:// URL
-#   gives TLS. Because of that, setting tls_client_cert requires this URL
-#   to start with https:// — including leaving it at the default above,
-#   which makes xrpld fail to start rather than export without the client
-#   identity it was configured with.
-#
-# --- TLS settings for the OTLP exporter connection ---
-#
-# use_tls=0
-#
-#   Whether to hand tls_ca_cert to the exporter as its CA bundle. TLS is
-#   selected by the scheme of traces_endpoint, not by this key; setting it
-#   to 1 only supplies a custom CA file for verifying the collector.
-#   Default: 0 (no CA file is passed, so the exporter keeps its own
-#   default trust store).
-#
-# tls_ca_cert=
-#
-#   Path to a PEM-encoded CA certificate bundle for verifying the
-#   collector's certificate. Only used when use_tls=1, and passed to the
-#   exporter unchanged. The path is not checked while the config is parsed,
-#   so a missing or unreadable file surfaces as an export failure at
-#   runtime rather than as a startup error.
-#   Default: empty (system CA store).
-#
-#   Leaving this empty stays valid and selects the system CA store. A path
-#   that is set is checked like the client paths below: with enabled=1 and
-#   use_tls=1, one that does not exist or cannot be read makes xrpld fail
-#   to start.
-#
-# tls_client_cert=
-#
-#   Path to this node's PEM-encoded client certificate, presented to the
-#   collector for mutual TLS (mTLS). Requires use_tls=1. Leave empty
-#   for one-way (server-only) TLS. Default: empty.
-#
-#   To enable mTLS, both tls_client_cert and tls_client_key must be
-#   specified. If only one is provided, xrpld will fail to start. Providing
-#   them while use_tls=0 also fails to start, rather than being ignored.
-#   traces_endpoint and metrics_endpoint must both be https:// URLs, because
-#   that scheme is what makes each exporter present the certificate at all.
-#   With use_tls=1 each path is opened at startup, so one that does not
-#   exist or cannot be read fails to start too, rather than failing later
-#   as an opaque TLS handshake error. All four checks apply only when
-#   enabled=1; with telemetry disabled these settings are read but never
-#   validated.
-#
-# tls_client_key=
-#
-#   Path to the PEM-encoded private key for tls_client_cert. Required
-#   whenever tls_client_cert is set. Requires use_tls=1, and must be
-#   readable. All three conditions are enforced exactly as described under
-#   tls_client_cert above: when enabled=1, breaking any one of them makes
-#   xrpld fail to start.
-#   Default: empty.
-#
-#   Head sampling is intentionally fixed at 1.0 (sample everything) and is
-#   not configurable. A per-node sampling ratio would let nodes make
-#   divergent keep/drop decisions for the same distributed trace, producing
-#   broken/partial traces. A ParentBasedSampler ensures spans inheriting a
-#   remote parent honor the upstream decision. Reduce volume at the collector
-#   via tail sampling instead; for node-local post-hoc dropping use
-#   SpanGuard::discard() in code.
-#
-# trace_rpc=1
-#
-#   Enable tracing for JSON-RPC and WebSocket API request handling —
-#   command parsing, execution, and response serialization. Default: 1.
-#
-# trace_transactions=1
-#
-#   Enable tracing for the transaction lifecycle — submission, validation,
-#   application to ledgers, and final disposition. Default: 1.
-#
-# trace_consensus=1
-#
-#   Enable tracing for the consensus round lifecycle — proposals,
-#   validations, mode changes, and ledger acceptance. Default: 1.
-#
-# trace_peer=1
-#
-#   Enable tracing for peer-to-peer protocol messages — overlay message
-#   send/receive, peer handshakes, and routing. High volume; enabled
-#   by default. Default: 1.
-#
-# trace_ledger=1
-#
-#   Enable tracing for ledger close and accept operations — ledger
-#   building, state hashing, and write-back to the node store. Default: 1.
-#
-# consensus_trace_strategy=deterministic
-#
-#   How the consensus round span picks its trace id. Two values are
-#   accepted, and anything else makes xrpld fail to start.
-#
-#   deterministic (the default, and the value to use): the trace id comes
-#   from the previous ledger hash, so every validator of a round reports
-#   into one trace and the round can be read end to end across nodes.
-#
-#   random: experimental only, and not used. Each node invents its own
-#   trace id, so a single round arrives as one separate trace per node.
-#   Those traces can only be lined up by hand through the
-#   consensus_ledger_id span attribute.
-#
-# --- Batch processor tuning ---
-#
-# batch_size=512
-#
-#   Maximum number of spans exported in a single batch. Must be at least 1
-#   and must not exceed max_queue_size. Default: 512.
-#
-# batch_delay_ms=5000
-#
-#   Maximum delay (milliseconds) before a partial batch is flushed.
-#   Must be at least 1. Default: 5000 (5 seconds).
-#
-# max_queue_size=2048
-#
-#   Maximum number of spans queued in memory before drops occur. Must be
-#   at least 1 and at least as large as batch_size. Default: 2048.
-#
-# --- Metric export ---
-#
-# metrics_endpoint=http://localhost:4318/v1/metrics
-#
-#   The OTLP/HTTP endpoint metrics are sent to, including the signal path.
-#   Used verbatim and independent of the trace endpoint, so the two signals
-#   can go to different collectors, or to one whose OTLP paths are not the
-#   defaults.
-#   Default: http://localhost:4318/v1/metrics.
-#
-#   The scheme decides encryption here exactly as it does for
-#   traces_endpoint, so setting tls_client_cert requires this URL to start
-#   with https:// as well — including leaving it at the default above.
-#   Overriding only traces_endpoint therefore makes xrpld fail to start,
-#   rather than export metrics without the client identity.
-#
-# metric_export_interval_ms=1000
-#
-#   Gap in milliseconds between two metric exports. Must be greater than 0.
-#   Default: 1000 (1 second), which matches the scrape rate the shipped
-#   dashboards assume.
-#
-# metric_export_timeout_ms=500
-#
-#   How long in milliseconds one metric export may run before it is
-#   cancelled. Must be greater than 0 and below metric_export_interval_ms;
-#   xrpld fails to start otherwise.
-#   Default: 500 (half a second).
-#

cmake/PatchNixBinary.cmake

@@ -2,10 +2,9 @@
    Patch executables to run in non-Nix environments.
 
    The Nix toolchain links binaries against an ELF interpreter (loader)
-   that lives in the Nix store, so the resulting binaries don't run elsewhere
-   (including once installed from the .deb package). `patch_nix_binary` resets
-   the interpreter to the system default loader and drops the rpath, once the
-   binary has been linked.
+   that lives in the Nix store, so the resulting binaries don't run elsewhere.
+   `patch_nix_binary` adds a POST_BUILD step that resets the interpreter
+   to the system default loader and drops the rpath.
 
    This runs by default for Nix-toolchain builds (determined by whether the compiler resolves under /nix/store/).
    Those builds are where binaries get a Nix-store loader.
@@ -53,38 +52,13 @@ function(patch_nix_binary target)
     if(NOT PATCH_NIX_BINARIES)
         return()
     endif()
-
-    set(patch_command
-        "${PATCHELF_COMMAND}"
-        --set-interpreter
-        "${DEFAULT_LOADER_PATH}"
-        --remove-rpath
-        "$<TARGET_FILE:${target}>"
+    add_custom_command(
+        TARGET ${target}
+        POST_BUILD
+        COMMAND
+            "${PATCHELF_COMMAND}" --set-interpreter "${DEFAULT_LOADER_PATH}"
+            --remove-rpath "$<TARGET_FILE:${target}>"
+        COMMENT "Patching ${target}: set default loader, remove rpath"
+        VERBATIM
     )
-    set(comment "Patching ${target}: set default loader, remove rpath")
-
-    # POST_BUILD is the cheap way to do this: it runs only when the binary is
-    # relinked. It is also only available in the directory that defined the
-    # target, so for a target from elsewhere (e.g. a FetchContent subproject)
-    # fall back to a custom target that runs after the binary is linked. That
-    # one runs on every build, which is harmless because patchelf is idempotent.
-    get_target_property(target_source_dir ${target} SOURCE_DIR)
-    if("${target_source_dir}" STREQUAL "${CMAKE_CURRENT_SOURCE_DIR}")
-        add_custom_command(
-            TARGET ${target}
-            POST_BUILD
-            COMMAND ${patch_command}
-            COMMENT "${comment}"
-            VERBATIM
-        )
-    else()
-        add_custom_target(
-            ${target}-patch-nix
-            ALL
-            COMMAND ${patch_command}
-            COMMENT "${comment}"
-            VERBATIM
-        )
-        add_dependencies(${target}-patch-nix ${target})
-    endif()
 endfunction()

cmake/XrplCompiler.cmake

@@ -120,10 +120,7 @@ if(MSVC)
             _SILENCE_ALL_CXX17_DEPRECATION_WARNINGS
             $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:_CRTDBG_MAP_ALLOC>
     )
-    target_link_libraries(
-        common
-        INTERFACE -errorreport:none -machine:X64 -ignore:4099
-    )
+    target_link_libraries(common INTERFACE -errorreport:none -machine:X64)
 else()
     target_compile_options(
         common
@@ -269,50 +266,10 @@ elseif(use_lld)
     )
     if("${LD_VERSION}" MATCHES "LLD")
         target_link_libraries(common INTERFACE -fuse-ld=lld)
-        # remembered for the linker flag probe below
-        set(fuse_ld_flag "-fuse-ld=lld")
     endif()
     unset(LD_VERSION)
 endif()
 
-# Linker warnings are errors where we control the toolchain and the dependencies: CI and the Nix dev shell.
-# On non-Nix macOS we suppress the deployment target warning: an old Conan profile may not pin os.version.
-# Only the new Apple linker understands the flag, so probe the actual linker (lld may be selected above).
-if(is_macos OR is_linux)
-    if(is_ci OR is_nix_compiler)
-        if(is_macos)
-            set(fatal_warnings_flag "-Wl,-fatal_warnings")
-        else()
-            set(fatal_warnings_flag "-Wl,--fatal-warnings")
-        endif()
-        message(
-            STATUS
-            "Treating all linker warnings as errors (${fatal_warnings_flag})"
-        )
-        target_link_options(common INTERFACE "${fatal_warnings_flag}")
-        unset(fatal_warnings_flag)
-    elseif(is_macos)
-        set(silence_flag "-Wl,-deployment_target_mismatches,suppress")
-        set(probe_flags ${fuse_ld_flag} "${silence_flag}")
-        include(CheckLinkerFlag)
-        check_linker_flag(
-            CXX
-            "${probe_flags}"
-            have_deployment_target_mismatches
-        )
-        if(have_deployment_target_mismatches)
-            message(
-                STATUS
-                "Silencing macOS deployment target mismatch warnings (${silence_flag})"
-            )
-            target_link_options(common INTERFACE "${silence_flag}")
-        endif()
-        unset(probe_flags)
-        unset(silence_flag)
-    endif()
-endif()
-unset(fuse_ld_flag)
-
 if(assert)
     foreach(var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
         string(REGEX REPLACE "[-/]DNDEBUG" "" ${var_} "${${var_}}")

cmake/XrplCore.cmake

@@ -51,8 +51,6 @@ target_compile_options(
 
 target_link_libraries(xrpl.libpb PUBLIC protobuf::libprotobuf gRPC::grpc++)
 
-add_dependencies(tidy_prerequisites xrpl.libpb)
-
 # TODO: Clean up the number of library targets later.
 add_library(xrpl.imports.main INTERFACE)
 
@@ -80,19 +78,6 @@ include(target_link_modules)
 # Level 01
 add_module(xrpl beast)
 target_link_libraries(xrpl.libxrpl.beast PUBLIC xrpl.imports.main)
-# OTelCollector in beast/insight uses the OTel Metrics SDK when telemetry is
-# enabled. Link the Conan-provided umbrella target rather than individual
-# component targets: the OTel package's per-component dependency graph is
-# under-declared (e.g. the OTLP client references sdk::common symbols without
-# declaring the edge), so naming components directly reorders the static-link
-# line into an unresolvable state. The umbrella carries the full, internally
-# consistent graph the package authors validated.
-if(telemetry)
-    target_link_libraries(
-        xrpl.libxrpl.beast
-        PUBLIC opentelemetry-cpp::opentelemetry-cpp
-    )
-endif()
 
 include(GitInfo)
 add_module(xrpl git)
@@ -219,43 +204,9 @@ target_link_libraries(
         xrpl.libxrpl.conditions
 )
 
-# Telemetry module — OpenTelemetry distributed tracing support.
-# Sources: include/xrpl/telemetry/ (headers), src/libxrpl/telemetry/ (impl).
-# When telemetry=ON, links the Conan-provided umbrella target
-# opentelemetry-cpp::opentelemetry-cpp (individual component targets like
-# ::api, ::sdk are not available in the Conan package).
-#
-# Declared before its consumers (consensus, tx) because add_module isolates
-# each module's headers: a module can only include xrpl/telemetry/ headers if
-# it links this target, and the target must already exist at that point.
-#
-# Links xrpl.libxrpl.protocol and xrpl.libxrpl.core PUBLICLY: ValidationTracker.h
-# takes LedgerIndex and MetricMacros.h takes ServiceRegistry, both in interfaces.
-# TxAccountSpanNames.cpp also reads the SField table from xrpl.libxrpl.protocol.
-add_module(xrpl telemetry)
-target_link_libraries(
-    xrpl.libxrpl.telemetry
-    PUBLIC
-        xrpl.libxrpl.basics
-        xrpl.libxrpl.beast
-        xrpl.libxrpl.config
-        xrpl.libxrpl.core
-        xrpl.libxrpl.protocol
-)
-if(telemetry)
-    # Telemetry owns both the trace and (as of the direct-metrics API) the
-    # metrics pipeline. Link the umbrella target: it supplies the trace and
-    # metrics SDK components with the correct static-link ordering, which
-    # naming components individually does not (the package under-declares
-    # inter-component dependencies).
-    target_link_libraries(
-        xrpl.libxrpl.telemetry
-        PUBLIC opentelemetry-cpp::opentelemetry-cpp
-    )
-endif()
+add_module(xrpl tx)
+target_link_libraries(xrpl.libxrpl.tx PUBLIC xrpl.libxrpl.ledger)
 
-# Links xrpl.libxrpl.telemetry for the consensus tracing spans declared in
-# include/xrpl/consensus/ConsensusSpanNames.h.
 add_module(xrpl consensus)
 target_link_libraries(
     xrpl.libxrpl.consensus
@@ -264,13 +215,6 @@ target_link_libraries(
         xrpl.libxrpl.json
         xrpl.libxrpl.protocol
         xrpl.libxrpl.ledger
-        xrpl.libxrpl.telemetry
-)
-
-add_module(xrpl tx)
-target_link_libraries(
-    xrpl.libxrpl.tx
-    PUBLIC xrpl.libxrpl.ledger xrpl.libxrpl.telemetry
 )
 
 add_library(xrpl.libxrpl)
@@ -307,7 +251,6 @@ target_link_modules(
     resource
     server
     shamap
-    telemetry
     tx
 )
 

cmake/XrplCov.cmake

@@ -44,7 +44,6 @@ setup_target_for_coverage_gcovr(
     EXCLUDE
         "src/test"
         "src/tests"
-        "src/benchmarks"
         "include/xrpl/beast/test"
         "include/xrpl/beast/unit_test"
         "${CMAKE_BINARY_DIR}/pb-xrpl.libpb"

cmake/XrplDocs.cmake

@@ -27,12 +27,8 @@ file(
     src/*.cpp
     src/*.md
     Builds/*.md
+    *.md
 )
-# Add only top-level .md files (README, CONTRIBUTING, etc.) without
-# recursing into dot-directories like .claude/ whose files are not
-# valid Doxygen/CMake sources.
-file(GLOB doxygen_top_md CONFIGURE_DEPENDS "*.md")
-list(APPEND doxygen_input ${doxygen_top_md})
 list(APPEND doxygen_input external/README.md)
 set(dependencies "${doxygen_input}" "${doxyfile}")
 

cmake/XrplPackaging.cmake

@@ -1,7 +1,7 @@
 #[===================================================================[
    Linux packaging support: 'package' target.
 
-   The packaging script (package/build_pkg.py) installs to FHS-standard
+   The packaging script (package/build_pkg.sh) installs to FHS-standard
    paths (/usr/bin, /etc/xrpld, etc.) regardless of CMAKE_INSTALL_PREFIX,
    so no prefix guard is needed here.
 #]===================================================================]
@@ -25,39 +25,19 @@ if(NOT (RPMBUILD_EXECUTABLE OR DPKG_BUILDPACKAGE_EXECUTABLE))
     return()
 endif()
 
-if(NOT TARGET xrpld)
-    message(STATUS "xrpld=ON is required; 'package' target not available")
-    return()
-endif()
-
-if(NOT TARGET validator-keys)
-    message(
-        STATUS
-        "validator_keys=ON is required; 'package' target not available"
-    )
-    return()
-endif()
-
-if(DPKG_BUILDPACKAGE_EXECUTABLE)
-    set(pkg_type deb)
-else()
-    set(pkg_type rpm)
-endif()
-
-# Unquoted below, so an empty value adds no argument at all.
-set(pkg_variant_option "")
-if(assert)
-    set(pkg_variant_option --variant=assert)
-endif()
+set(package_env
+    SRC_DIR=${CMAKE_SOURCE_DIR}
+    BUILD_DIR=${CMAKE_BINARY_DIR}
+    PKG_RELEASE=${pkg_release}
+)
 
 add_custom_target(
     package
     COMMAND
-        ${CMAKE_SOURCE_DIR}/package/build_pkg.py --package-type=${pkg_type}
-        --build-dir=${CMAKE_BINARY_DIR} --pkg-release=${pkg_release}
-        ${pkg_variant_option} --channel=UNRELEASED
+        ${CMAKE_COMMAND} -E env ${package_env}
+        ${CMAKE_SOURCE_DIR}/package/build_pkg.sh
     WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
-    DEPENDS xrpld validator-keys
-    COMMENT "Building Linux ${pkg_type} package"
+    DEPENDS xrpld
+    COMMENT "Building Linux package (deb/rpm inferred from host tooling)"
     VERBATIM
 )

cmake/XrplProtocolAutogen.cmake

@@ -2,22 +2,21 @@
    Protocol Autogen - Code generation for protocol wrapper classes
 #]===================================================================]
 
-# The repository root, derived from the location of this file rather than from
-# the including project, so that the targets below can also be offered on their
-# own by cmake/codegen/CMakeLists.txt.
-get_filename_component(XRPL_ROOT "${CMAKE_CURRENT_LIST_DIR}/.." ABSOLUTE)
-
 set(CODEGEN_VENV_DIR
-    "${XRPL_ROOT}/.venv"
+    "${CMAKE_CURRENT_SOURCE_DIR}/.venv"
     CACHE PATH
     "Path to a Python virtual environment for code generation. A venv will be created here by setup_code_gen and used to run generation scripts."
 )
 
 # Directory paths
-set(MACRO_DIR "${XRPL_ROOT}/include/xrpl/protocol/detail")
-set(AUTOGEN_HEADER_DIR "${XRPL_ROOT}/include/xrpl/protocol_autogen")
-set(AUTOGEN_TEST_DIR "${XRPL_ROOT}/src/tests/libxrpl/protocol_autogen")
-set(SCRIPTS_DIR "${XRPL_ROOT}/cmake/scripts/codegen")
+set(MACRO_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl/protocol/detail")
+set(AUTOGEN_HEADER_DIR
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl/protocol_autogen"
+)
+set(AUTOGEN_TEST_DIR
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/tests/libxrpl/protocol_autogen"
+)
+set(SCRIPTS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/cmake/scripts/codegen")
 
 # Input macro files
 set(TRANSACTIONS_MACRO "${MACRO_DIR}/transactions.macro")
@@ -115,14 +114,14 @@ if(CODEGEN_VENV_DIR)
         setup_code_gen
         COMMAND ${Python3_EXECUTABLE} -m venv "${CODEGEN_VENV_DIR}"
         COMMAND ${CODEGEN_PYTHON} -m pip install -r "${REQUIREMENTS_FILE}"
-        WORKING_DIRECTORY "${XRPL_ROOT}"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
         COMMENT "Creating venv and installing code generation dependencies..."
     )
 else()
     add_custom_target(
         setup_code_gen
         COMMAND ${Python3_EXECUTABLE} -m pip install -r "${REQUIREMENTS_FILE}"
-        WORKING_DIRECTORY "${XRPL_ROOT}"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
         COMMENT "Installing code generation dependencies..."
     )
 endif()
@@ -140,8 +139,8 @@ add_custom_target(
         -DSFIELDS_MACRO=${SFIELDS_MACRO}
         -DAUTOGEN_HEADER_DIR=${AUTOGEN_HEADER_DIR}
         -DAUTOGEN_TEST_DIR=${AUTOGEN_TEST_DIR} -P
-        "${CMAKE_CURRENT_LIST_DIR}/XrplProtocolAutogenRun.cmake"
-    WORKING_DIRECTORY "${XRPL_ROOT}"
+        "${CMAKE_CURRENT_SOURCE_DIR}/cmake/XrplProtocolAutogenRun.cmake"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
     COMMENT "Running protocol code generation..."
     SOURCES ${ALL_INPUT_FILES}
 )

cmake/XrplSettings.cmake

@@ -32,11 +32,6 @@ endif()
 
 option(benchmark "Build benchmarks" ON)
 
-# When OFF, the crates directory is not added to the build at all: no Rust
-# toolchain is required, no cxxbridge bindings are generated, and the C++ tests
-# that consume those bindings are left out of the build tree.
-option(rust "Build the Rust crates and the C++ code that depends on them" OFF)
-
 # Enabled by default so every header is compiled on its own as the main file of
 # its own compile_commands.json entry - this is what lets clang-tidy (and clangd
 # and IDEs) analyse a header's own includes directly. The per-header objects are

cmake/XrplValidatorKeys.cmake

@@ -5,39 +5,22 @@ option(
 )
 
 if(validator_keys)
-    # Own the install destination below rather than relying on another module
-    # having pulled this in first.
-    include(GNUInstallDirs)
-
-    # Pinned to an exact commit, not a branch: the tool ships inside our
-    # packages, so the same xrpld version must always package the same
-    # validator-keys. Bump this deliberately.
-    set(validator_keys_commit "4c0fb75eec9601c711645998c904507e87e910ae")
-    message(STATUS "Using ValidatorKeys commit: ${validator_keys_commit}")
+    git_branch(current_branch)
+    # default to tracking VK master branch unless we are on release
+    if(NOT (current_branch STREQUAL "release"))
+        set(current_branch "master")
+    endif()
+    message(STATUS "Tracking ValidatorKeys branch: ${current_branch}")
 
     FetchContent_Declare(
         validator_keys
         GIT_REPOSITORY https://github.com/ripple/validator-keys-tool.git
-        GIT_TAG "${validator_keys_commit}"
+        GIT_TAG "${current_branch}"
     )
     FetchContent_MakeAvailable(validator_keys)
-    # The tool's own CMakeLists excludes the target from 'all' when it is built
-    # as a subproject. Undo that, so validator_keys=ON really does build it.
     set_target_properties(
         validator-keys
-        PROPERTIES
-            RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
-            EXCLUDE_FROM_ALL OFF
-            EXCLUDE_FROM_DEFAULT_BUILD OFF
-    )
-    # We ship this binary, so like xrpld it must not keep the Nix store's ELF
-    # loader, or it cannot run on the target distro at all.
-    patch_nix_binary(validator-keys)
-
-    configure_file(
-        "${validator_keys_SOURCE_DIR}/LICENSE"
-        "${CMAKE_BINARY_DIR}/validator-keys-LICENSE"
-        COPYONLY
+        PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
     )
     install(TARGETS validator-keys RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
 endif()

cmake/codegen/CMakeLists.txt

@@ -1,21 +0,0 @@
-#[===================================================================[
-   Protocol Autogen - Standalone project
-
-   Exposes the 'setup_code_gen' and 'code_gen' targets on their own, without
-   configuring the rest of xrpl. Code generation is pure Python, so this needs
-   neither the dependencies nor a compiler, which makes it usable in CI and by
-   contributors who only want to regenerate the protocol wrapper classes:
-
-     cmake -S cmake/codegen -B build/codegen
-     cmake --build build/codegen --target setup_code_gen
-     cmake --build build/codegen --target code_gen
-
-   The targets are identical to the ones offered by the top-level build, since
-   both come from cmake/XrplProtocolAutogen.cmake.
-#]===================================================================]
-
-cmake_minimum_required(VERSION 3.16)
-
-project(xrpl_codegen LANGUAGES NONE)
-
-include("${CMAKE_CURRENT_LIST_DIR}/../XrplProtocolAutogen.cmake")

cmake/scripts/codegen/generate_tx_classes.py

@@ -8,7 +8,6 @@ Uses pcpp to preprocess the macro file and pyparsing to parse the DSL.
 
 import io
 import argparse
-import re
 from pathlib import Path
 import pyparsing as pp
 
@@ -54,89 +53,28 @@ def create_transaction_parser():
     return macro_parser
 
 
-# Defaults for xrpl::TxSettings members, mirroring
-# include/xrpl/protocol/TxSettings.h. A transaction's settings blob only names
-# the members that differ from these.
-SETTING_DEFAULTS = {
-    "delegable": "Delegation::NotDelegable",
-    "amendment": "uint256{}",
-    "privileges": "Privilege::NoPriv",
-}
-
-
-def parse_settings(settings_str):
-    """Parse a TxSettings blob into a dict, filling in defaults.
-
-    Args:
-        settings_str: A string like '({.delegable = Delegation::NotDelegable,
-                      .privileges = Privilege::CreateAcct})', or '({})'.
-
-    Returns:
-        A dict with a value for every key in SETTING_DEFAULTS.
-    """
-    body = settings_str.strip()
-    if not (body.startswith("(") and body.endswith(")")):
-        raise ValueError(
-            f"Malformed settings blob, expected '({{...}})': {settings_str!r}"
-        )
-    body = body[1:-1].strip()
-    if not (body.startswith("{") and body.endswith("}")):
-        raise ValueError(
-            f"Malformed settings blob, expected '({{...}})': {settings_str!r}"
-        )
-    body = body[1:-1]
-
-    # Strip comments, which may be interleaved with the designated initializers.
-    body = re.sub(r"//[^\n]*", "", body)
-
-    settings = dict(SETTING_DEFAULTS)
-    seen = set()
-    # Each entry runs from '.key =' up to the next '.key =' or the end.
-    for key, value in re.findall(
-        r"\.(\w+)\s*=\s*(.*?)(?=,\s*\.\w+\s*=|,?\s*$)", body, re.S
-    ):
-        if key not in SETTING_DEFAULTS:
-            raise ValueError(f"Unknown TxSettings member '.{key}' in {settings_str!r}")
-        settings[key] = " ".join(value.split()).rstrip(",")
-        seen.add(key)
-
-    # Catch a typo'd or unparsed initializer rather than silently defaulting it.
-    # Every '.member' in the blob must have been consumed above.
-    if len(re.findall(r"\.\w+", body)) != len(seen):
-        raise ValueError(f"Could not parse every setting in {settings_str!r}")
-
-    # A blob with content but no designated initializer is positional, which
-    # would otherwise be read as "all defaults" and silently generate the
-    # wrong output.
-    if body.strip() and not seen:
-        raise ValueError(
-            "TxSettings requires designated initializers (.member = value), "
-            f"got {settings_str!r}"
-        )
-
-    return settings
-
-
 def parse_transaction_args(args_list):
     """Parse the arguments of a TRANSACTION macro call.
 
     Args:
         args_list: A list of parsed arguments from pyparsing, e.g.,
-                   ['ttPAYMENT', '0', 'Payment',
-                    '({.privileges = Privilege::CreateAcct})', '({...})']
+                   ['ttPAYMENT', '0', 'Payment', 'Delegation::delegable',
+                    'uint256{}', 'createAcct', '({...})']
 
     Returns:
         A dict with parsed transaction information.
     """
-    if len(args_list) < 5:
+    if len(args_list) < 7:
         raise ValueError(
-            f"Expected at least 5 parts in TRANSACTION, got {len(args_list)}: {args_list}"
+            f"Expected at least 7 parts in TRANSACTION, got {len(args_list)}: {args_list}"
         )
 
     tag = args_list[0]
     value = args_list[1]
     name = args_list[2]
-    settings = parse_settings(args_list[3])
+    delegable = args_list[3]
+    amendments = args_list[4]
+    privileges = args_list[5]
     fields_str = args_list[-1]
 
     # Parse fields: ({field1, field2, ...})
@@ -146,9 +84,9 @@ def parse_transaction_args(args_list):
         "tag": tag,
         "value": value,
         "name": name,
-        "delegable": settings["delegable"],
-        "amendments": settings["amendment"],
-        "privileges": settings["privileges"],
+        "delegable": delegable,
+        "amendments": amendments,
+        "privileges": privileges,
         "fields": fields,
     }
 

conan.lock

@@ -10,23 +10,19 @@
         "rocksdb/10.5.1#4a197eca381a3e5ae8adf8cffa5aacd0%1782392413.075713",
         "re2/20251105#8579cfd0bda4daf0683f9e3898f964b4%1782392402.431897",
         "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81%1782392410.233933",
-        "opentelemetry-cpp/1.28.0#2cbf71db4e0e0535df20be305005cb2f%1785939947.292581",
         "openssl/3.6.3#f806de8933e3bf6f01016c6a888cee2e%1783945160.863288",
         "nudb/2.0.9#11149c73f8f2baff9a0198fe25971fc7%1782392402.297166",
-        "nlohmann_json/3.11.3#45828be26eb619a2e04ca517bb7b828d%1701220705.259",
-        "mpt-crypto/1.0.2#b313cef0c1a493eb970ad185b2e9bab7%1784285108.866483",
+        "mpt-crypto/0.4.0-rc4#ffdba12f2332357f0d8b0ae944cfff52%1784138702.932355",
         "lz4/1.10.0#982d9b673900f665a1da109e09c17cab%1782392402.164188",
         "libiconv/1.17#9923bc6dc6f106646d6967e0039a5ada%1782392792.775744",
-        "libcurl/8.21.0#8c26e59c04891ba3373ea3552e18f67f%1783067699.863",
         "libbacktrace/cci.20210118#a7691bfccd8caaf66309df196790a5a1%1782392402.420732",
         "libarchive/3.8.7#c446109bd1f1d8ba7936c94189bc50e6%1782392403.066892",
         "jemalloc/5.3.1#1fc58d55316041f10fbc1e8a2eae632a%1776700028.228",
         "gtest/1.17.0#5224b3b3ff3b4ce1133cbdd27d53ee7d%1782392402.791979",
         "grpc/1.81.1#f729f6d75992d20f9c72828e9142d62f%1783945160.094135",
-        "fast_float/8.2.10#f6f28d6bb22112078e7dbda611caf681%1785888854.601666",
+        "fast_float/8.2.10#f6f28d6bb22112078e7dbda611caf681%1782494504.298",
         "ed25519/2015.03#ae761bdc52730a843f0809bdf6c1b1f6%1782307148.15562",
         "date/3.0.4#862e11e80030356b53c2c38599ceb32b%1782392402.538492",
-        "corrosion/0.6.1#bfa292df0a957bc70a450ff316cd9435%1786119416.131296",
         "c-ares/1.34.6#545240bb1c40e2cacd4362d6b8967650%1782392402.681654",
         "bzip2/1.0.8#c470882369c2d95c5c77e970c0c7e321%1782392402.296732",
         "boost/1.91.0#ea540ca2133d831b560036aa24dece3c%1782392419.475605",
@@ -37,15 +33,9 @@
         "zlib/1.3.2#1cb806da49011867778ffb6ac7190fcb%1782392402.122708",
         "strawberryperl/5.32.1.1#8d114504d172cfea8ea1662d09b6333e%1782395692.540639",
         "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81%1782392410.233933",
-        "pkgconf/2.5.1#93c2051284cba1279494a43a4fcfeae2%1757684701.089",
-        "opentelemetry-proto/1.7.0#ed6d5bd761bef0afb0ba09676420b9ea%1749461220.268",
-        "ninja/1.13.2#c8c5dc2a52ed6e4e42a66d75b4717ceb%1764096931.974",
         "nasm/2.16.01#31e26f2ee3c4346ecd347911bd126904%1782395690.33162",
         "msys2/cci.latest#d22fe7b2808f5fd34d0a7923ace9c54f%1770657326.649",
-        "meson/1.10.2#9d2d10681fe7fe61c788c58626c89b25%1775558003.754",
         "m4/1.4.19#1727f439cf74e83826ec96d0b4904eee%1784541921.659",
-        "libtool/2.4.7#14e7739cc128bc1623d2ed318008e47e%1755679003.847",
-        "gnu-config/cci.20210814#466e9d4d7779e1c142443f7ea44b4284%1762363589.329",
         "cmake/4.3.3#840cf00ea09777e05c2050a50a82c722%1782392418.696091",
         "b2/5.4.2#ffd6084a119587e70f11cd45d1a386e2%1782392402.624226",
         "automake/1.16.5#b91b7c384c3deaa9d535be02da14d04f%1755524470.56",
@@ -71,9 +61,6 @@
         ],
         "lz4/[>=1.9.4 <2]": [
             "lz4/1.10.0#982d9b673900f665a1da109e09c17cab"
-        ],
-        "protobuf/[>=4.25.3 <7]": [
-            "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81"
         ]
     },
     "config_requires": []

conan/init.sh

@@ -1,21 +0,0 @@
-#!/usr/bin/env bash
-# Install our Conan configuration, profiles and the xrplf remote into CONAN_HOME.
-# Safe to re-run; never deletes the Conan home.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
-CONAN_DIR="$(conan config home)"
-
-echo "Installing Conan configuration into ${CONAN_DIR}"
-conan config install "${SCRIPT_DIR}/global.conf"
-conan config install "${SCRIPT_DIR}/profiles" -tf "${CONAN_DIR}/profiles"
-# This script manages these files, so make them read-only - Conan does not
-# preserve the source mode. Only the files: the directories must stay writable
-# for `conan config install` to replace them.
-chmod a-w "${CONAN_DIR}/global.conf"
-find "${CONAN_DIR}/profiles" -type f -exec chmod a-w {} +
-
-echo "Adding the xrplf Conan remote"
-# --index 0: our patched recipes must win over Conan Center.
-conan remote add --index 0 --force xrplf https://conan.xrplf.org/repository/conan/

conan/profiles/default

@@ -1,7 +1,10 @@
 {% set os = detect_api.detect_os() %}
 {% set arch = detect_api.detect_arch() %}
 {% set compiler, version, compiler_exe = detect_api.detect_default_compiler() %}
+{% set compiler_version = version %}
+{% if os == "Linux" %}
 {% set compiler_version = detect_api.default_compiler_version(compiler, version) %}
+{% endif %}
 {% if os == "Macos" %}
 {# Minimum macOS the dependencies target. #}
 {# Without this, Conan builds each dependency against the (possibly newer) host SDK, so the #}
@@ -58,18 +61,3 @@ tools.info.package_id:confs+=["user.package:cppstd_version"]
 {# Scoped to boost/* since it is the only gap. #}
 boost/*:MACOSX_DEPLOYMENT_TARGET={{ min_macos_version }}
 {% endif %}
-{% if compiler == "gcc" and compiler_version < 13 %}
-tools.build:cxxflags+=['-Wno-restrict']
-{% endif %}
-{% if os == "Windows" %}
-# opentelemetry-cpp's recipe removes the `shared` option on Windows and never
-# sets BUILD_SHARED_LIBS, so its upstream CMake defaults the protobuf-generated
-# `opentelemetry_proto` target to a DLL (opentelemetry_proto.dll). The rest of
-# the project links statically and nothing deploys that DLL next to the
-# executables, so the telemetry unit test fails to start with
-# STATUS_DLL_NOT_FOUND (0xC0000135). Force the dependency to build fully static
-# so no runtime DLL is produced. The conf is folded into the package id so a
-# fresh static binary is built instead of reusing a previously cached one.
-opentelemetry-cpp/*:tools.cmake.cmaketoolchain:extra_variables={"BUILD_SHARED_LIBS": "OFF"}
-opentelemetry-cpp/*:tools.info.package_id:confs+=["tools.cmake.cmaketoolchain:extra_variables"]
-{% endif %}

conanfile.py

@@ -22,14 +22,12 @@ class Xrpl(ConanFile):
         "rocksdb": [True, False],
         "shared": [True, False],
         "static": [True, False],
-        "telemetry": [True, False],
         "tests": [True, False],
         "unity": [True, False],
         "xrpld": [True, False],
     }
 
     requires = [
-        "corrosion/0.6.1",
         "ed25519/2015.03",
         "fast_float/8.2.10",
         "grpc/1.81.1",
@@ -57,7 +55,6 @@ class Xrpl(ConanFile):
         "rocksdb": True,
         "shared": False,
         "static": True,
-        "telemetry": True,
         "tests": False,
         "unity": False,
         "xrpld": False,
@@ -142,20 +139,15 @@ class Xrpl(ConanFile):
         if self.options.jemalloc:
             self.requires("jemalloc/5.3.1")
         self.requires("lz4/1.10.0", force=True)
-        self.requires("mpt-crypto/1.0.2", transitive_headers=True)
+        self.requires("mpt-crypto/0.4.0-rc4", transitive_headers=True)
         self.requires("protobuf/6.33.5", force=True)
         if self.options.rocksdb:
             self.requires("rocksdb/10.5.1")
         self.requires("secp256k1/0.7.1", transitive_headers=True)
         self.requires("sqlite3/3.53.0", force=True)
-        # OpenTelemetry C++ SDK for distributed tracing (optional).
-        # Provides OTLP/HTTP exporter, batch span processor, and trace API.
-        if self.options.telemetry:
-            self.requires("opentelemetry-cpp/1.28.0")
         self.requires("xxhash/0.8.3", transitive_headers=True)
 
     exports_sources = (
-        "bin/default-loader-path.sh",
         "CMakeLists.txt",
         "cfg/*",
         "cmake/*",
@@ -182,7 +174,6 @@ class Xrpl(ConanFile):
         tc.variables["rocksdb"] = self.options.rocksdb
         tc.variables["BUILD_SHARED_LIBS"] = self.options.shared
         tc.variables["static"] = self.options.static
-        tc.variables["telemetry"] = self.options.telemetry
         tc.variables["unity"] = self.options.unity
         tc.variables["xrpld"] = self.options.xrpld
         tc.generate()
@@ -237,9 +228,3 @@ class Xrpl(ConanFile):
         ]
         if self.options.rocksdb:
             libxrpl.requires.append("rocksdb::librocksdb")
-        if self.options.telemetry:
-            libxrpl.requires.append("opentelemetry-cpp::opentelemetry-cpp")
-            # The public telemetry headers pick their class layout on this
-            # define, so a consumer that does not see it compiles a different
-            # SpanGuard than the one inside the library it links.
-            libxrpl.defines.append("XRPL_ENABLE_TELEMETRY")

crates/.cargo/config.toml

@@ -1,17 +0,0 @@
-# The Rust static libraries are linked into C++ targets, so the runtime linkage
-# here has to match what the C++ build uses (see cmake/XrplCompiler.cmake).
-#
-# macOS needs nothing: AppleClang cannot link libgcc/libc++ statically, so the
-# C++ build skips those flags on Apple as well.
-
-# Both amd64 and arm64 Linux builds link libgcc statically. This only affects
-# links that rustc itself drives (`cargo test` binaries and the like) — the
-# `staticlib` crates consumed by CMake are archived, not linked, so rustc
-# silently ignores link args for them. Keeping libgcc_s.so.1 off the xrpld link
-# line is handled in crates/CMakeLists.txt instead.
-[target.'cfg(target_os = "linux")']
-rustflags = ["-C", "link-args=-static-libgcc"]
-
-# Windows builds use the static MSVC runtime.
-[target.'cfg(windows)']
-rustflags = ["-C", "target-feature=+crt-static"]

crates/CMakeLists.txt

@@ -1,104 +0,0 @@
-find_package(Corrosion REQUIRED)
-
-corrosion_import_crate(MANIFEST_PATH ${CMAKE_CURRENT_SOURCE_DIR}/Cargo.toml)
-
-# The generated C++ lands in the build tree, so put a .clang-tidy next to it to
-# keep clang-tidy from analyzing code we don't own.
-configure_file(
-    generated.clang-tidy
-    "${CMAKE_CURRENT_BINARY_DIR}/.clang-tidy"
-    COPYONLY
-)
-
-add_custom_target(xrpl_crates)
-add_dependencies(tidy_prerequisites xrpl_crates)
-
-# On macOS, ld warns `ignoring duplicate libraries` when linking a crate.
-# Corrosion is the source of both duplicates it names:
-#
-# * The crate archive and its cxxbridge archive, because
-#   `corrosion_add_cxxbridge` makes the two depend on each other, and CMake
-#   repeats a static library cycle on the link line so single-pass linkers can
-#   resolve it. (LINK_INTERFACE_MULTIPLICITY can only raise that count.)
-# * `-lSystem`, which Corrosion copies from rustc's `native-static-libs` even
-#   though the compiler driver always links libSystem.
-#
-# ld needs neither: it resolves the cycle from one copy of each archive and
-# links libSystem once. So silence the warning rather than rewrite Corrosion's
-# link interface, which the cycle is also part of. The option itself is old —
-# Xcode 15 is only where the warning became the default — and the check below
-# leaves it out on a linker that does not know it.
-if(is_macos)
-    include(CheckLinkerFlag)
-    check_linker_flag(
-        CXX
-        -Wl,-no_warn_duplicate_libraries
-        have_no_warn_duplicate_libraries
-    )
-endif()
-
-function(_unlink_libgcc_s crate)
-    if(NOT (is_linux AND static))
-        return()
-    endif()
-
-    # Corrosion exposes a crate's staticlib as an imported `<crate>-static`
-    # target and puts the native libs in its INTERFACE_LINK_LIBRARIES. If either
-    # of those changes, warn instead of silently letting libgcc_s.so.1 return.
-    set(imported "${crate}-static")
-    if(NOT TARGET ${imported})
-        message(
-            FATAL_ERROR
-            "Corrosion did not create the imported target '${imported}', so "
-            "libgcc_s cannot be removed from the link interface of '${crate}'. "
-            "xrpld will link libgcc_s.so.1 dynamically. Check where Corrosion "
-            "${CORROSION_VERSION} now records `native-static-libs`."
-        )
-        return()
-    endif()
-
-    get_target_property(libs ${imported} INTERFACE_LINK_LIBRARIES)
-    if(NOT "gcc_s" IN_LIST libs)
-        message(
-            WARNING
-            "'gcc_s' was not in the link interface of '${imported}' as "
-            "expected. If the Rust toolchain stopped reporting it this "
-            "workaround is obsolete and can be deleted; otherwise xrpld may "
-            "link libgcc_s.so.1 dynamically. Verify with: "
-            "objdump -p xrpld | grep NEEDED"
-        )
-        return()
-    endif()
-
-    list(REMOVE_ITEM libs gcc_s)
-    set_property(TARGET ${imported} PROPERTY INTERFACE_LINK_LIBRARIES ${libs})
-endfunction()
-
-function(add_xrpl_crate name)
-    cmake_parse_arguments(ARG "" "CRATE" "FILES" ${ARGN})
-    _unlink_libgcc_s(${ARG_CRATE})
-    # `cc` picks its runtime flag from `crt-static` alone, so it compiles a
-    # crate's C++ with `-MT`; Debug needs `-MTd` (to match cmake/XrplCompiler.cmake).
-    if(is_msvc)
-        corrosion_set_env_vars(
-            ${ARG_CRATE}
-            "$<$<CONFIG:Debug>:CXXFLAGS=-MTd>"
-        )
-    endif()
-    corrosion_add_cxxbridge(${name}_cxxbridge CRATE ${ARG_CRATE} FILES
-                            ${ARG_FILES}
-    )
-    # Generated cxxbridge headers don't exist at configure time; CMake 3.28+
-    # validates INTERFACE_SOURCES on consuming targets. Clear it to skip the
-    # existence check — build-time ordering is enforced by the custom commands.
-    set_target_properties(${name}_cxxbridge PROPERTIES INTERFACE_SOURCES "")
-    if(have_no_warn_duplicate_libraries)
-        target_link_options(
-            ${name}_cxxbridge
-            INTERFACE -Wl,-no_warn_duplicate_libraries
-        )
-    endif()
-    add_dependencies(xrpl_crates ${name}_cxxbridge)
-endfunction()
-
-add_xrpl_crate(rs_hello_world CRATE rs_hello_world FILES lib.rs)

crates/Cargo.lock

@@ -1,301 +0,0 @@
-# This file is automatically @generated by Cargo.
-# It is not intended for manual editing.
-version = 4
-
-[[package]]
-name = "anstyle"
-version = "1.0.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
-
-[[package]]
-name = "cc"
-version = "1.2.61"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d16d90359e986641506914ba71350897565610e87ce0ad9e6f28569db3dd5c6d"
-dependencies = [
- "find-msvc-tools",
- "shlex",
-]
-
-[[package]]
-name = "clap"
-version = "4.6.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
-dependencies = [
- "clap_builder",
-]
-
-[[package]]
-name = "clap_builder"
-version = "4.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
-dependencies = [
- "anstyle",
- "clap_lex",
- "strsim",
-]
-
-[[package]]
-name = "clap_lex"
-version = "1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
-
-[[package]]
-name = "codespan-reporting"
-version = "0.13.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "af491d569909a7e4dee0ad7db7f5341fef5c614d5b8ec8cf765732aba3cff681"
-dependencies = [
- "serde",
- "termcolor",
- "unicode-width",
-]
-
-[[package]]
-name = "cxx"
-version = "1.0.199"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "824894a4a85dca76d4c95c2b9098c036f5a29f627b30c12780774f6654e60974"
-dependencies = [
- "cc",
- "cxx-build",
- "cxxbridge-cmd",
- "cxxbridge-flags",
- "cxxbridge-macro",
- "foldhash",
- "link-cplusplus",
-]
-
-[[package]]
-name = "cxx-build"
-version = "1.0.199"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1ae0b651ea5b0000b19513aef5a03f194d7e3486f2d9258b658da8677fe9036"
-dependencies = [
- "cc",
- "codespan-reporting",
- "indexmap",
- "proc-macro2",
- "quote",
- "scratch",
- "syn 3.0.3",
-]
-
-[[package]]
-name = "cxxbridge-cmd"
-version = "1.0.199"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fb05f91d3fb8435d9bab6ac5ce6ac1868be774325fb7fb2a91be39393b21388e"
-dependencies = [
- "clap",
- "codespan-reporting",
- "indexmap",
- "proc-macro2",
- "quote",
- "syn 3.0.3",
-]
-
-[[package]]
-name = "cxxbridge-flags"
-version = "1.0.199"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf293202e0e3e98495785745389e8d0755b217e66f19194a5c695c25e03282ef"
-
-[[package]]
-name = "cxxbridge-macro"
-version = "1.0.199"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ca001d746947c7249ed9d332a10f7a59daedbafeb0ec68c5c18a7db7a93f6ccc"
-dependencies = [
- "indexmap",
- "proc-macro2",
- "quote",
- "syn 3.0.3",
-]
-
-[[package]]
-name = "equivalent"
-version = "1.0.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
-
-[[package]]
-name = "find-msvc-tools"
-version = "0.1.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
-
-[[package]]
-name = "foldhash"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
-
-[[package]]
-name = "hashbrown"
-version = "0.17.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"
-
-[[package]]
-name = "indexmap"
-version = "2.14.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
-dependencies = [
- "equivalent",
- "hashbrown",
-]
-
-[[package]]
-name = "link-cplusplus"
-version = "1.0.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f78c730aaa7d0b9336a299029ea49f9ee53b0ed06e9202e8cb7db9bae7b8c82"
-dependencies = [
- "cc",
-]
-
-[[package]]
-name = "proc-macro2"
-version = "1.0.106"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
-dependencies = [
- "unicode-ident",
-]
-
-[[package]]
-name = "quote"
-version = "1.0.45"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
-dependencies = [
- "proc-macro2",
-]
-
-[[package]]
-name = "rs-hello_world"
-version = "0.1.0"
-dependencies = [
- "cxx",
-]
-
-[[package]]
-name = "scratch"
-version = "1.0.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d68f2ec51b097e4c1a75b681a8bec621909b5e91f15bb7b840c4f2f7b01148b2"
-
-[[package]]
-name = "serde"
-version = "1.0.228"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
-dependencies = [
- "serde_core",
- "serde_derive",
-]
-
-[[package]]
-name = "serde_core"
-version = "1.0.228"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
-dependencies = [
- "serde_derive",
-]
-
-[[package]]
-name = "serde_derive"
-version = "1.0.228"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
-
-[[package]]
-name = "shlex"
-version = "1.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
-
-[[package]]
-name = "strsim"
-version = "0.11.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
-
-[[package]]
-name = "syn"
-version = "2.0.117"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
-dependencies = [
- "proc-macro2",
- "quote",
- "unicode-ident",
-]
-
-[[package]]
-name = "syn"
-version = "3.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
-dependencies = [
- "proc-macro2",
- "quote",
- "unicode-ident",
-]
-
-[[package]]
-name = "termcolor"
-version = "1.4.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755"
-dependencies = [
- "winapi-util",
-]
-
-[[package]]
-name = "unicode-ident"
-version = "1.0.24"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
-
-[[package]]
-name = "unicode-width"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
-
-[[package]]
-name = "winapi-util"
-version = "0.1.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
-dependencies = [
- "windows-sys",
-]
-
-[[package]]
-name = "windows-link"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
-
-[[package]]
-name = "windows-sys"
-version = "0.61.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
-dependencies = [
- "windows-link",
-]

crates/Cargo.toml

@@ -1,18 +0,0 @@
-[workspace]
-members = ["hello_world"]
-resolver = "3"
-
-[workspace.dependencies]
-cxx = { version = "1.0.198", features = ["c++20"] }
-
-[workspace.package]
-edition = "2024"
-
-[workspace.lints.rust]
-unexpected_cfgs = { level = "warn", check-cfg = [ 'cfg(coverage)', 'cfg(coverage_nightly)' ] }
-
-[profile.release]
-opt-level = 3
-overflow-checks = true
-lto = true
-debug = true

crates/generated.clang-tidy

@@ -1,10 +0,0 @@
----
-# Neutralizes clang-tidy for the corrosion/cxxbridge-generated C++. Copied into
-# the crates build directory by crates/CMakeLists.txt, next to the generated
-# sources, so clang-tidy picks it up instead of the top-level configuration.
-#
-# One check is kept enabled to avoid clang-tidy's "no checks enabled" error.
-Checks: "-*,google-readability-todo"
-WarningsAsErrors: ""
-HeaderFilterRegex: ""
-InheritParentConfig: false

crates/hello_world/Cargo.toml

@@ -1,13 +0,0 @@
-[package]
-name = "rs-hello_world"
-version = "0.1.0"
-edition.workspace = true
-
-[lib]
-crate-type = ["staticlib"]
-
-[dependencies]
-cxx.workspace = true
-
-[lints]
-workspace = true

crates/hello_world/src/lib.rs

@@ -1,23 +0,0 @@
-#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
-
-#[cxx::bridge(namespace = "rs::hello_world")]
-mod ffi {
-    extern "Rust" {
-        fn hello_world() -> String;
-    }
-}
-
-pub fn hello_world() -> String {
-    "hello_world".to_string()
-}
-
-#[cfg(test)]
-#[cfg_attr(coverage_nightly, coverage(off))]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn hello_world_returns_hello_world() {
-        assert_eq!(hello_world(), "hello_world")
-    }
-}