feat: add more instrumentation to xrpld

.cspell.config.yaml

@@ -18,6 +18,7 @@ dictionaries:
 ignoreRegExpList:
   - /\b[rs][1-9A-HJ-NP-Za-km-z]{25,34}/g # addresses and seeds
   - /\bC[A-Z0-9]{15}/g # CTIDs
+  - /\bXRPL_METRIC_[A-Z_]+/g # telemetry macro names; the splitter emits subwords like ISTOGRAM
   - /\b(XRPL|BEAST)_[A-Z_0-9]+_H_INCLUDED+/g # include guards
   - /\b(XRPL|BEAST)_[A-Z_0-9]+_H+/g # include guards
   - /::[a-z:_]+/g # things from other namespaces
@@ -351,6 +352,7 @@ words:
   - txns
   - txqueue
   - txs
+  - txset
   - ubsan
   - UBSAN
   - ufdio

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

@@ -14,5 +14,5 @@ Loop: xrpld.overlay xrpld.rpc
   xrpld.rpc ~= xrpld.overlay
 
 Loop: xrpld.overlay xrpld.telemetry
-  xrpld.telemetry ~= xrpld.overlay
+  xrpld.overlay > xrpld.telemetry
 

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

@@ -193,6 +193,7 @@ tests.libxrpl > xrpl.config
 tests.libxrpl > xrpl.consensus
 tests.libxrpl > xrpl.core
 tests.libxrpl > xrpld.app
+tests.libxrpl > xrpld.overlay
 tests.libxrpl > xrpld.telemetry
 tests.libxrpl > xrpl.json
 tests.libxrpl > xrpl.ledger
@@ -334,6 +335,7 @@ xrpld.telemetry > xrpl.consensus
 xrpld.telemetry > xrpl.core
 xrpld.telemetry > xrpld.core
 xrpld.telemetry > xrpl.json
+xrpld.telemetry > xrpl.ledger
 xrpld.telemetry > xrpl.nodestore
 xrpld.telemetry > xrpl.protocol
 xrpld.telemetry > xrpl.rdb

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

@@ -35,18 +35,29 @@ hardcoded allowlist:
   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`.
+- **L1-metrics** — instrument names, label keys and bounded label values come
+  from the `namespace metric` / `namespace label` / `namespace lval` blocks of
+  every `*MetricNames.h`, read as `inline constexpr char NAME[] = "wire";`.
+  These headers deliberately do **not** use the `makeStr`/`StaticStr` DSL the
+  span headers use: the OTel C++ API takes `nostd::string_view`, which
+  constructs from `char const*` but has no constructor from
+  `std::string_view`, so a `StaticStr` will not compile in an instrument-name
+  or label-key position.
 
 ### 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 | 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.                                                                                                                                                                                                                                                                                                                                                                                  |
+| I    | No string literals as **metric** instrument names or label keys — the mirror of Rule F. Applies to the name passed to an `XRPL_METRIC_*` macro or a `meter->Create*` factory and to the label _keys_ in its label set. Label _values_, descriptions, `*MetricNames.h`, `MetricMacros.h` and test files are exempt. Scoped by metric **family** (first underscore segment): declaring a constant opts that family in, so the metric surface can be converted subsystem by subsystem. Unconverted families warn as Rule L.                                                                   |
+| J    | Metric instrument names follow the suffix conventions: `lower_snake_case`, no `xrpld_`/`xrpl_` prefix (the exporter adds it), a counter ends `_total`, a histogram ends `_us`/`_ms`/`_seconds`, a gauge does not end `_total`. The instrument **kind** is read from the emit site, never guessed from words in the name — so a multi-series gauge carrying units in its label values (e.g. `nodestore_state` observing `write_mean_us`) is not a violation. A name created through two different factories is itself reported as a kind conflict, since no suffix can be correct for both. |
+| K    | Every metric named in `docker/telemetry/workload/expected_metrics.json` resolves to a declared constant, so a rename in code cannot leave the workload validator asserting a name nothing emits. PromQL selectors (`m{label="v"}`) and exporter-appended histogram suffixes (`_bucket`/`_count`/`_sum`) are normalized away first; groups fed by another emit path (`statsd_gauges`, `statsd_counters`, `spanmetrics`) are out of scope by design.                                                                                                                                         |
 
 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
@@ -58,6 +69,7 @@ still caught.
 | 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. |
+| L    | A literal metric name in a family that has no `*MetricNames.h` constants yet. Rule I's ratchet defers these instead of failing the build on the whole pre-existing metric surface at once; the warning keeps the outstanding conversion work visible rather than silently accepted.                                                                                                        |
 
 ## Presence-gated