mirror of https://github.com/XRPLF/rippled.git synced 2026-07-30 10:30:22 +00:00

Files

Pratik Mankawde 134a24d5bc ci: Add OpenTelemetry span-attribute naming check (phase 1c)

Add check_otel_naming.py and wire it into on-pr.yml so every PR validates
that span-attribute names stay consistent across the code, collector, Tempo,
dashboards, and docs.

- The valid key set is derived dynamically from the *SpanNames.h constants and
  the resource attributes the code registers in Telemetry.cpp — no hardcoded
  allowlist to drift.
- Each rule is presence-gated: it runs only when the file it needs is in the
  tree, so the check is correct whether telemetry changes land in one PR or
  several (the collector/Tempo/dashboard/runbook layers arrive in later phases).
- Rule A flags dotted span-attribute keys; Rule F flags string-literal
  attribute keys and span-name arguments (values may be runtime data).
- stdlib-only, mirroring the levelization check (bare `python`, no pip step).
- Telemetry.h / SpanGuard.h @code examples now use *SpanNames.h constants so
  the strict literal check passes.
- CONTRIBUTING.md documents the check and how to run it locally.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-11 15:26:38 +01:00

check_otel_naming.py

ci: Add OpenTelemetry span-attribute naming check (phase 1c)

2026-06-11 15:26:38 +01:00

README.md

ci: Add OpenTelemetry span-attribute naming check (phase 1c)

2026-06-11 15:26:38 +01:00

README.md

OTel naming-consistency check

check_otel_naming.py enforces the OpenTelemetry span-attribute naming convention documented in CONTRIBUTING.md 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).
Legitimate dotted keys = the resource attrs declared in the base SpanNames.h (xrpl.network.*) plus the semconv::service::* keys the code passes to Resource::Create() in Telemetry.cpp (service.*). A dotted key declared in any other header is a violation.

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).
F	No string literals as attribute keys or span-name arguments in `setAttribute`/`addEvent`/`span`/`childSpan`. Attribute values are exempt (runtime data). `*SpanNames.h` definitions 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 PromQL label (non-builtin) exists in the L1 key set.
E	Every runbook attribute reference exists in the L1 key set.

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, F) run.