ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2026-07-24 07:30:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'pratik/otel-phase9-metric-gap-fill' into pratik/otel-phase10-workload-validation

Browse Source 
Forward-merge the OTel naming-check Rule C/D fixes and the phase 2-9 chain.

Conflict resolutions:
- 02-design-decisions.md TxQ Attributes: take the convention-correct markdown
  table (txq_* keys) over the stale planned-attrs code block.
- SpanGuardFactory.cpp: keep the explanatory comment for the literal attribute
  keys in the libxrpl test.
This commit is contained in:
Pratik Mankawde
2026-06-11 19:38:09 +01:00
parent d259ae34e3 3cf7eea230
commit 8172c0c811
69 changed files with 3118 additions and 4004 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.github/scripts/levelization/results/ordering.txt vendored
View File

@@ -47,6 +47,7 @@ libxrpl.shamap > xrpl.nodestore
libxrpl.shamap > xrpl.protocol
libxrpl.shamap > xrpl.shamap
libxrpl.telemetry > xrpl.basics
libxrpl.telemetry > xrpl.config
libxrpl.telemetry > xrpl.telemetry
libxrpl.tx > xrpl.basics
libxrpl.tx > xrpl.conditions
@@ -253,8 +254,7 @@ xrpl.server > xrpl.shamap
xrpl.shamap > xrpl.basics
xrpl.shamap > xrpl.nodestore
xrpl.shamap > xrpl.protocol
xrpl.telemetry > xrpl.basics
xrpl.telemetry > xrpld.consensus
xrpl.telemetry > xrpl.config
xrpl.tx > xrpl.basics
xrpl.tx > xrpl.core
xrpl.tx > xrpl.ledger
@@ -334,6 +334,7 @@ xrpld.shamap > xrpl.protocol
xrpld.shamap > xrpl.shamap
xrpld.telemetry > xrpl.basics
xrpld.telemetry > xrpl.core
xrpld.telemetry > xrpld.consensus
xrpld.telemetry > xrpld.core
xrpld.telemetry > xrpl.json
xrpld.telemetry > xrpl.nodestore

65
.github/scripts/otel-naming/README.md vendored Normal file
View File

@@ -0,0 +1,65 @@
# 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`).
- **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). |
| 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`/`childSpan`. 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. |
## 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.

838
.github/scripts/otel-naming/check_otel_naming.py vendored Normal file
View File

@@ -0,0 +1,838 @@
#!/usr/bin/env python3
"""
Usage: check_otel_naming.py
This script takes no parameters and can be called from any directory inside the
repository (it locates the repo root via `git rev-parse`).
Enforces the OpenTelemetry span-attribute naming convention documented in
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.
Design principles
-----------------
1. No hardcoded allowlist. The set of valid attribute keys — including which
dotted keys are legitimate resource attributes — is derived dynamically by
parsing the repository's own OTel code:
* `*SpanNames.h` `namespace attr { ... }` blocks (the underscore/bare keys
and the `join(seg::..., ...)` dotted resource compositions), and
* the keys the code passes to `Resource::Create({ ... })` in Telemetry.cpp
(the standard `semconv::service::*` keys -> service.name/version/...).
2. Presence-gated enforcement. Every rule runs ONLY when the source files it
needs are present in the tree, and is otherwise skipped (never failed). This
keeps the check correct no matter how work is split across PRs: a stacked
chain, one large PR, or independent per-stage PRs where (for example) the
collector config lands in a different PR than the dashboards. The check never
assumes a file from another phase/PR exists.
Layers
------
L1 code : src/**/*SpanNames.h, include/**/*SpanNames.h (ground truth)
L1 resource : src/libxrpl/telemetry/Telemetry.cpp (dotted allowlist)
L1 callsites : setAttribute/addEvent/span/childSpan in src/**, include/**
L2 collector : docker/telemetry/otel-collector-config.yaml (spanmetrics dims)
L3 tempo : docker/telemetry/tempo.yaml (span filter tags)
L4 dashboards: docker/telemetry/grafana/dashboards/*.json (PromQL labels)
L5 runbook : docs/telemetry-runbook.md (attr tables)
L6 metrics : MetricsRegistry.cpp instrument labels (native-metric
label keys, a valid dashboard-label source besides L1)
Rules (each FAILS the build, when its inputs are present)
---------------------------------------------------------
A No stray dotted span-attribute key. A dotted `<a>.<b>` used as a span
attribute that is not in the derived resource-key set is a violation.
G Attribute keys must be lower_snake_case (^[a-z][a-z0-9_]*$ per segment).
Flags camelCase, UPPERCASE, spaces, and other stray characters.
F No string literals as attribute keys or span-name arguments. The
setAttribute/addEvent key and the span/childSpan prefix/name args must
reference a *SpanNames.h constant, never a "literal". Attribute VALUES are
exempt (runtime data). Definitions inside *SpanNames.h are exempt, and
test files are exempt (they pass arbitrary literals to exercise the API).
B Every collector spanmetrics dimension 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, an L6
native-metric label, or a builtin. TraceQL `span.`/`resource.` scope
prefixes 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.
Warnings (printed, but do NOT fail the build)
----------------------------------------------
H A constant referenced at a telemetry call-site is not defined in any
*SpanNames.h. Span constants should live in the corresponding
*SpanNames.h (single source of truth); defining one in-place bypasses the
naming rules. A warning (not a failure) because the argument may instead
be a legitimately dynamic local (e.g. a computed span-name leaf).
Exit code is non-zero if any present-and-enforced rule finds a violation.
Warnings never change the exit code.
"""
import re
import subprocess
import sys
from pathlib import Path
from typing import Dict, List, Optional, Set, Tuple
# ---------------------------------------------------------------------------
# Repo location
# ---------------------------------------------------------------------------
def repo_root() -> Path:
"""Return the repository root, so the script works from any CWD.
Exits with a readable message (not a traceback) if git is unavailable or the
CWD is outside a repository."""
try:
out = subprocess.run(
["git", "rev-parse", "--show-toplevel"],
capture_output=True,
text=True,
check=True,
)
except (subprocess.CalledProcessError, FileNotFoundError):
print(
"error: check_otel_naming.py must be run inside the git repository.",
file=sys.stderr,
)
sys.exit(2)
return Path(out.stdout.strip())
def read_source(path: Path) -> str:
"""Read a file as UTF-8, tolerating stray non-UTF-8 bytes rather than
crashing the whole check on one bad byte."""
return path.read_text(encoding="utf-8", errors="ignore")
# ---------------------------------------------------------------------------
# Regexes (compiled once)
# ---------------------------------------------------------------------------
# A segment/string constant definition: `inline constexpr auto NAME = <expr>;`
CONST_DEF = re.compile(r"inline\s+constexpr\s+auto\s+(\w+)\s*=\s*(.+?);", re.DOTALL)
MAKESTR = re.compile(r'makeStr\(\s*"([^"]*)"\s*\)')
# A `namespace <name> {` opener, to track which namespace a constant lives in.
NS_OPEN = re.compile(r"namespace\s+([\w:]+)\s*\{")
# A `using ::a::b::field;` re-export inside an attr block; captures the leaf.
USING_DECL = re.compile(r"using\s+(?:::)?[\w:]*::(\w+)\s*;")
# Telemetry call-sites whose string arguments must be constants, not literals.
# Require a receiver so we match real SpanGuard calls, not std::span / a math
# `span(...)` / a bare method declaration:
# - `SpanGuard::span(` / `SpanGuard::childSpan(` (static factory)
# - `<obj>.span(` / `<obj>->setAttribute(` etc. (member call)
# `span`/`childSpan` additionally require the `SpanGuard`/`.`/`->` receiver;
# `setAttribute`/`addEvent` only ever exist on a guard, so a `.`/`->` suffices.
CALLSITE = re.compile(
r"(?:SpanGuard::|\.|->)\s*(setAttribute|addEvent|span|childSpan)\s*\("
)
# A C++ string literal (used to flag literals inside call-site argument lists).
STRING_LITERAL = re.compile(r'"((?:[^"\\]|\\.)*)"')
# A C++ line comment (`//` ... end of line) and a block comment (`/* ... */`).
LINE_COMMENT = re.compile(r"//[^\n]*")
BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.DOTALL)
# A TraceQL scope prefix on a label (`span.`, `resource.`, `event.`, etc.).
# Dashboards reference span attributes in TraceQL as `span.<attr>`; the bare
# attribute is what must exist in L1, so strip the scope before validating.
TRACEQL_SCOPE = re.compile(r"^(?:span|resource|event|link|instrumentation_scope)\.")
# An OTel metric label key as emitted in C++: `Add(.., {{"label", ...}})` /
# `{{"label", value}}` instrument calls in MetricsRegistry.
METRIC_LABEL = re.compile(r'\{\{\s*"([a-z_][a-z0-9_]*)"\s*,')
def strip_comments(text: str) -> str:
"""Remove C/C++ `//` line comments and `/* ... */` block comments.
Used only for L1 attribute-key extraction so that a commented-out or
illustrative `makeStr("...")` inside a `namespace attr` block does not leak
into the authoritative key set. Rule F deliberately does NOT strip comments
— it must still see `@code` doc-comment examples so their call-site
arguments are held to the constant-only convention.
String literals are not specially handled; a `//` or `/*` appearing inside a
string is vanishingly rare in the *SpanNames.h headers and would at worst
drop a constant from L1 (a conservative direction).
"""
text = BLOCK_COMMENT.sub("", text)
text = LINE_COMMENT.sub("", text)
return text
# ---------------------------------------------------------------------------
# L1: parse *SpanNames.h into the authoritative key set
# ---------------------------------------------------------------------------
def find_spanname_headers(root: Path) -> List[Path]:
return sorted(
p
for p in list((root / "src").rglob("*SpanNames.h"))
+ list((root / "include").rglob("*SpanNames.h"))
if p.is_file()
)
def resolve_constants(
text: str, symbols: Optional[Dict[str, str]] = None
) -> Dict[str, str]:
"""Resolve `inline constexpr auto NAME = <makeStr/join expr>` to strings.
Supports the small constexpr DSL used by SpanNames.h:
makeStr("x") -> "x"
join(a, b) -> resolve(a) + "." + resolve(b)
seg::xrpl / attr::foo -> looked up in the symbol table
The optional `symbols` argument seeds (and is updated in place with) the
table, so a global pass over ALL *SpanNames.h headers can resolve
cross-file references such as `join(seg::rpc, ...)` where `seg::rpc` is
defined in the base SpanNames.h. Keys are stored by their bare name
(last `::` component), so `seg::rpc` and `rpc` both resolve.
"""
if symbols is None:
symbols = {}
def resolve_expr(expr: str) -> Optional[str]:
expr = expr.strip()
m = MAKESTR.fullmatch(expr)
if m:
return m.group(1)
if expr.startswith("join(") and expr.endswith(")"):
args = split_top_level_args(expr[len("join(") : -1])
parts = [resolve_expr(a) for a in args]
if any(p is None for p in parts):
return None
return ".".join(p for p in parts if p is not None)
# Bare or qualified symbol reference, e.g. `seg::xrpl` or `networkId`.
key = expr.split("::")[-1]
return symbols.get(key, symbols.get(expr))
# Iterate definitions in source order so earlier symbols are available.
for m in CONST_DEF.finditer(text):
name, expr = m.group(1), m.group(2)
val = resolve_expr(expr)
if val is not None:
symbols[name] = val
return symbols
def build_global_symbols(headers: List[Path]) -> Dict[str, str]:
"""Resolve constants across ALL headers so cross-file `seg::`/`join`
references (e.g. `join(seg::rpc, ...)` in RpcSpanNames.h, where `seg::rpc`
lives in the base SpanNames.h) resolve. Base SpanNames.h is processed
first so its `seg::` segments seed the table."""
symbols: Dict[str, str] = {}
ordered = sorted(headers, key=lambda p: (p.name != "SpanNames.h", str(p)))
# Two passes: the first seeds segments, the second resolves dependents.
# Comments are stripped so a commented-out constant cannot seed the table.
for _ in range(2):
for h in ordered:
resolve_constants(strip_comments(read_source(h)), symbols)
return symbols
def split_top_level_args(s: str) -> List[str]:
"""Split a comma-separated arg list, respecting nested parentheses and
ignoring parens/commas that appear inside a "string literal" (so a value
like `setAttribute(k, ",")` does not get mis-split)."""
args, depth, cur = [], 0, ""
in_str = False
escaped = False
for ch in s:
if in_str:
cur += ch
if escaped:
escaped = False
elif ch == "\\":
escaped = True
elif ch == '"':
in_str = False
continue
if ch == '"':
in_str = True
cur += ch
elif ch == "(":
depth += 1
cur += ch
elif ch == ")":
depth -= 1
cur += ch
elif ch == "," and depth == 0:
args.append(cur)
cur = ""
else:
cur += ch
if cur.strip():
args.append(cur)
return args
def attr_namespace_spans(text: str) -> List[str]:
"""Return the source text of each `namespace attr { ... }` block in `text`.
Brace-matched over the whole (comment-stripped) text, so a definition that
wraps across several physical lines is contained in one span. Nested braces
inside the block are balanced correctly."""
spans: List[str] = []
for opener in NS_OPEN.finditer(text):
if opener.group(1).split("::")[-1] != "attr":
continue
# Walk from the opening brace, balancing nesting to the matching close.
i = opener.end() # one char past the namespace's `{`
depth = 1
start = i
while i < len(text) and depth > 0:
c = text[i]
if c == "{":
depth += 1
elif c == "}":
depth -= 1
i += 1
spans.append(text[start : i - 1])
return spans
def attr_keys_from_header(path: Path, symbols: Dict[str, str]) -> Set[str]:
"""Return the set of attribute-key strings declared in a header's
`namespace attr { ... }` block(s). `symbols` is the global cross-file
table so `join(seg::rpc, ...)` style dotted attrs resolve correctly.
Comments are stripped first (a commented constant must not enter L1), and
each attr block is brace-matched over the whole text so multi-line
`inline constexpr auto NAME = join(\\n ...);` definitions are captured."""
text = strip_comments(read_source(path))
keys: Set[str] = set()
for block in attr_namespace_spans(text):
for md in CONST_DEF.finditer(block):
# Resolve the named constant against the global symbol table; this
# captures makeStr("x"), join(seg::y, ...), and `using ::a::b` forms.
val = symbols.get(md.group(1))
if val is not None:
keys.add(val)
# `using ::ns::attr::field;` re-exports a base constant into this attr
# block (e.g. RpcSpanNames imports txHash). Resolve the imported name.
for um in USING_DECL.finditer(block):
val = symbols.get(um.group(1))
if val is not None:
keys.add(val)
return keys
# ---------------------------------------------------------------------------
# Reporting
# ---------------------------------------------------------------------------
class Report:
def __init__(self) -> None:
self.violations: List[Tuple[str, str, str, str]] = []
self.warnings: List[Tuple[str, str, str, str]] = []
self.skips: List[str] = []
self.checked: List[str] = []
def violation(self, rule: str, loc: str, token: str, expected: str) -> None:
self.violations.append((rule, loc, token, expected))
def warning(self, rule: str, loc: str, token: str, note: str) -> None:
"""A non-fatal finding: printed, but does not fail the build. Used where
the script cannot be certain a finding is wrong (e.g. a constant used at
a call-site that is not defined in any *SpanNames.h — it might be a
misplaced constant, or a legitimately dynamic value)."""
self.warnings.append((rule, loc, token, note))
def skip(self, rule: str, reason: str) -> None:
self.skips.append(f"SKIP: {rule} — {reason}")
def ok(self, msg: str) -> None:
self.checked.append(f"OK: {msg}")
def render_and_exit(self) -> None:
for line in self.skips:
print(line)
for line in self.checked:
print(line)
if self.warnings:
print("\nNaming-convention warnings (non-fatal):\n")
print(f" {'RULE':<5} {'LOCATION':<48} {'TOKEN':<28} NOTE")
print(f" {'-' * 5} {'-' * 48} {'-' * 28} {'-' * 30}")
for rule, loc, token, note in self.warnings:
print(f" {rule:<5} {loc:<48} {token:<28} {note}")
if self.violations:
print("\nNaming-convention violations:\n")
print(f" {'RULE':<5} {'LOCATION':<48} {'TOKEN':<28} EXPECTED")
print(f" {'-' * 5} {'-' * 48} {'-' * 28} {'-' * 30}")
for rule, loc, token, expected in self.violations:
print(f" {rule:<5} {loc:<48} {token:<28} {expected}")
print(
"\nSee CONTRIBUTING.md -> 'Telemetry span attribute naming'. "
"The *SpanNames.h constants are the single source of truth."
)
sys.exit(1)
print("\nAll present telemetry naming layers are consistent.")
sys.exit(0)
def main() -> None:
root = repo_root()
report = Report()
# --- Build the L1 ground-truth key set (presence-gated) ----------------
headers = find_spanname_headers(root)
l1_keys: Set[str] = set()
if headers:
symbols = build_global_symbols(headers)
# Map each key to the header(s) that declare it, so Rule A can tell a
# legitimate resource attr (declared in the base SpanNames.h) from a
# stray dotted key declared in a domain header.
keys_by_header: Dict[Path, Set[str]] = {}
for h in headers:
hk = attr_keys_from_header(h, symbols)
keys_by_header[h] = hk
l1_keys |= hk
report.ok(
f"L1: {len(l1_keys)} attribute keys from {len(headers)} "
f"*SpanNames.h header(s)"
)
else:
report.skip("L1", "no *SpanNames.h present (not a naming-relevant tree)")
keys_by_header = {}
# --- Derive the legitimate dotted (resource) keys dynamically ----------
# ONLY the base SpanNames.h resource attrs + the semconv keys Telemetry.cpp
# passes to Resource::Create(). A dotted key from any other header is a
# violation, not an allowlist entry.
dotted_allow = derive_dotted_resource_keys(root, keys_by_header, report)
# --- Rule A: no stray dotted span-attribute keys -----------------------
if l1_keys:
run_rule_a(keys_by_header, dotted_allow, report)
# --- Rule G: keys must be lower_snake_case -----------------------------
if l1_keys:
run_rule_g(keys_by_header, report)
# --- Rule F (+ Rule H): scan telemetry call-sites ----------------------
# Runs UNCONDITIONALLY: Rule F is a purely syntactic check (is this argument
# a literal?) and does not need the L1 key set, so a code path that uses
# SpanGuard::span/setAttribute directly without ever defining a *SpanNames.h
# is still caught. Rule H (warning) additionally flags constant references
# not defined in any *SpanNames.h.
header_symbols = spanname_symbol_names(headers)
run_rule_f(root, report, header_symbols)
# --- Cross-layer rules B/C/D/E (each presence-gated) -------------------
# L6 native-metric labels: span attributes are not the only valid dashboard
# labels — the MetricsRegistry emits OTel metrics whose label keys are an
# additional source of truth. Derive them dynamically (same principle as L1)
# so dashboards may reference them without tripping Rule D.
metric_labels = metric_label_names(root)
run_rule_b_collector(root, l1_keys, report)
run_rule_c_tempo(root, l1_keys, report)
run_rule_d_dashboards(root, l1_keys, metric_labels, report)
run_rule_e_runbook(root, l1_keys, report)
report.render_and_exit()
def derive_dotted_resource_keys(
root: Path, keys_by_header: Dict[Path, Set[str]], report: Report
) -> Set[str]:
"""Legitimate dotted keys = dotted attrs declared ONLY in the base
SpanNames.h (xrpl.network.*) plus the standard semconv keys the code
passes to Resource::Create() in Telemetry.cpp (service.*). Dotted keys
declared in any OTHER header are NOT allowlisted — they are Rule-A
violations."""
allow: Set[str] = set()
for h, keys in keys_by_header.items():
if h.name == "SpanNames.h": # the base header holds resource attrs
allow |= {k for k in keys if "." in k}
tele = root / "src" / "libxrpl" / "telemetry" / "Telemetry.cpp"
if tele.is_file():
text = read_source(tele)
# semconv::<group>::k<CamelKey> -> the dotted OTel-standard key. The
# CamelKey already embeds the group, e.g. service::kServiceInstanceId
# -> service.instance.id. Split the CamelCase name into dotted lowercase
# segments; if it does not lead with the group, prepend the group.
for m in re.finditer(r"semconv::(\w+)::k(\w+)", text):
group, camel = m.group(1), m.group(2)
segments = camel_to_dotsegments(camel)
if segments and segments[0] == group:
allow.add(".".join(segments))
else:
allow.add(group + "." + ".".join(segments))
report.ok(f"resource dotted-key allowlist derived: {sorted(allow)}")
else:
report.skip("resource-derive", "Telemetry.cpp not present")
return allow
def camel_to_dotsegments(s: str) -> List[str]:
"""Split a CamelCase identifier into lowercase dot-segment parts, e.g.
`ServiceInstanceId` -> ['service', 'instance', 'id']."""
return [w.lower() for w in re.findall(r"[A-Z][a-z0-9]*", s)]
def run_rule_a(
keys_by_header: Dict[Path, Set[str]], dotted_allow: Set[str], report: Report
) -> None:
"""Any dotted attribute key that is not an allowed resource key is a
violation, reported against the header that declares it."""
found = False
for h in sorted(keys_by_header):
for key in sorted(keys_by_header[h]):
if "." in key and key not in dotted_allow:
found = True
report.violation("A", h.name, key, "underscore form, not dotted")
if not found:
report.ok("A: no stray dotted span-attribute keys")
# A lower_snake_case identifier segment: starts lowercase, then lowercase /
# digits / underscores. No uppercase, no spaces, no camelCase.
SNAKE_SEGMENT = re.compile(r"^[a-z][a-z0-9_]*$")
def run_rule_g(keys_by_header: Dict[Path, Set[str]], report: Report) -> None:
"""Every attribute key must be lower_snake_case. Bare/underscore keys must
match ^[a-z][a-z0-9_]*$; dotted resource keys must be lowercase
dot-separated segments (each segment lower_snake_case). Flags camelCase,
UPPERCASE, spaces, and other stray characters."""
found = False
for h in sorted(keys_by_header):
for key in sorted(keys_by_header[h]):
segments = key.split(".")
if all(SNAKE_SEGMENT.match(seg) for seg in segments):
continue
found = True
report.violation("G", h.name, key, "must be lower_snake_case")
if not found:
report.ok("G: all attribute keys are lower_snake_case")
# Which argument positions of each call must be a constant (0-based). The
# attribute VALUE position is intentionally absent: values are runtime data
# (command names, hashes, counts), not naming-convention surface.
# setAttribute(key, value) -> check arg 0 (key); value (arg 1) exempt
# addEvent(name[, attrs]) -> check arg 0 (event name)
# span(category, prefix, name) -> check args 1,2 (prefix + span-name leaf)
# childSpan(name[, parentCtx]) -> check arg 0 (span-name leaf)
CONSTANT_ARG_POSITIONS: Dict[str, Set[int]] = {
"setAttribute": {0},
"addEvent": {0},
"span": {1, 2},
"childSpan": {0},
}
def is_test_path(path: Path) -> bool:
"""True if the path is test code. Tests legitimately pass arbitrary literal
keys/names to exercise the API mechanics, so Rule F does not apply to them.
Matches a `test`/`tests` directory anywhere in the path (e.g. src/test/,
src/tests/, .../detail/tests/)."""
return any(part in ("test", "tests") for part in path.parts)
# A constant reference passed at a call-site, e.g. `rpc_span::attr::command`
# or a bare `myKey`. We capture the leaf identifier (after the last `::`).
IDENTIFIER_ARG = re.compile(r"^[\s&*]*([A-Za-z_][\w:]*)\s*$")
def spanname_symbol_names(headers: List[Path]) -> Set[str]:
"""Every `inline constexpr auto NAME = ...;` symbol defined across the
*SpanNames.h headers, by bare name. Used by Rule H to tell whether a
constant referenced at a call-site actually lives in a SpanNames header."""
names: Set[str] = set()
for h in headers:
for m in CONST_DEF.finditer(strip_comments(read_source(h))):
names.add(m.group(1))
return names
def run_rule_f(root: Path, report: Report, header_symbols: Set[str]) -> None:
"""Walk every telemetry call-site (non-test, non-*SpanNames.h) and check the
constant-only argument positions of setAttribute/addEvent/span/childSpan:
Rule F (FAIL): a string literal in a key / span-name position. Attribute
VALUES are exempt (runtime data).
Rule H (WARN): a constant reference whose name is not defined in any
*SpanNames.h. The constant should live in the corresponding
*SpanNames.h (single source of truth); defining it in-place bypasses
the naming rules. Warn rather than fail — the argument may instead be a
legitimately dynamic local (e.g. a computed span-name leaf)."""
found_f = False
sources = [
p
for base in ("src", "include")
for ext in ("*.h", "*.cpp")
for p in (root / base).rglob(ext)
if p.is_file()
]
for path in sorted(sources):
if path.name.endswith("SpanNames.h") or is_test_path(path):
continue
text = read_source(path)
rel = path.relative_to(root)
for call, arglist, lineno in iter_calls(text):
positions = CONSTANT_ARG_POSITIONS.get(call, set())
args = split_top_level_args(arglist)
for idx in positions:
if idx >= len(args):
continue
arg = args[idx]
lit = STRING_LITERAL.search(arg)
if lit:
found_f = True
report.violation(
"F",
f"{rel}:{lineno}",
f'{call} arg{idx} "{lit.group(1)}"',
"use a *SpanNames.h constant",
)
continue
# Not a literal: Rule H warns when a NAMESPACE-QUALIFIED constant
# reference (e.g. `consensus::span::accept`) is not defined in
# any *SpanNames.h — i.e. the constant was defined in-place
# instead of in the proper header. We only consider qualified
# refs (containing `::`): a bare lowercase identifier is almost
# always a legitimately dynamic local (a computed span-name leaf
# or attribute value), not a misplaced constant, so warning on it
# would be noise. Standard-library types (std::...) are skipped.
ident = IDENTIFIER_ARG.match(arg)
if not (ident and header_symbols):
continue
ref = ident.group(1)
if "::" not in ref or ref.startswith("std::"):
continue
leaf = ref.split("::")[-1]
if leaf not in header_symbols:
report.warning(
"H",
f"{rel}:{lineno}",
f"{call} arg{idx} {ref}",
"not defined in any *SpanNames.h",
)
if not found_f:
report.ok("F: no string-literal keys/names at telemetry call-sites")
def iter_calls(text: str):
"""Yield (call_name, raw_arglist, lineno) for each setAttribute/addEvent/
span/childSpan invocation, spanning multiple physical lines if needed."""
for m in CALLSITE.finditer(text):
name = m.group(1)
# Walk from the opening paren, balancing nesting to find the close.
# Parens inside a "string literal" are ignored so a value such as
# `setAttribute(k, ")")` does not close the call early.
i = m.end() # one char past the '('
depth = 1
in_str = False
escaped = False
while i < len(text) and depth > 0:
c = text[i]
if in_str:
if escaped:
escaped = False
elif c == "\\":
escaped = True
elif c == '"':
in_str = False
elif c == '"':
in_str = True
elif c == "(":
depth += 1
elif c == ")":
depth -= 1
i += 1
arglist = text[m.end() : i - 1]
lineno = text.count("\n", 0, m.start()) + 1
yield name, arglist, lineno
def run_rule_b_collector(root: Path, l1_keys: Set[str], report: Report) -> None:
path = root / "docker" / "telemetry" / "otel-collector-config.yaml"
if not path.is_file():
report.skip("B", "collector config not present")
return
text = read_source(path)
if "spanmetrics" not in text:
report.skip("B", "no spanmetrics block in collector config")
return
dims = extract_spanmetrics_dimensions(text)
if not l1_keys:
report.skip("B", "no L1 key set to validate against")
return
miss = [d for d in dims if d not in l1_keys]
for d in miss:
report.violation("B", str(path.relative_to(root)), d, "must exist in L1")
if not miss:
report.ok(f"B: {len(dims)} collector dimension(s) all in L1")
def extract_spanmetrics_dimensions(text: str) -> List[str]:
dims: List[str] = []
in_dims = False
for line in text.splitlines():
if re.search(r"\bdimensions\s*:", line):
in_dims = True
continue
if in_dims:
m = re.search(r"-\s*name\s*:\s*([A-Za-z0-9_.]+)", line)
if m:
dims.append(m.group(1))
elif line.strip() and not line.lstrip().startswith("-") and ":" in line:
in_dims = False
return dims
def run_rule_c_tempo(root: Path, l1_keys: Set[str], report: Report) -> None:
# The trace-search filter tags live in the Grafana Tempo DATASOURCE
# provisioning file (search.filters[].{tag,scope}); the Tempo server
# tempo.yaml has no such tags. Prefer the datasource file; fall back to the
# server file so the rule still does something if the layout changes.
candidates = [
root / "docker/telemetry/grafana/provisioning/datasources/tempo.yaml",
root / "docker/telemetry/tempo.yaml",
]
path = next((p for p in candidates if p.is_file()), None)
if path is None:
report.skip("C", "tempo datasource provisioning not present")
return
if not l1_keys:
report.skip("C", "no L1 key set to validate against")
return
# Pair each filter's `tag:` with its `scope:` (a few lines below it) and
# validate only span-scope tags — resource/intrinsic tags (service.*, name,
# status, duration) are not span attributes. Strip a TraceQL span. prefix.
lines = read_source(path).splitlines()
span_tags: List[str] = []
for i, line in enumerate(lines):
m = re.search(r"^\s*tag:\s*(\S+)", line)
if not m:
continue
scope = next(
(
sm.group(1)
for j in range(i, min(i + 4, len(lines)))
for sm in [re.search(r"scope:\s*(\S+)", lines[j])]
if sm
),
"",
)
if scope == "span":
span_tags.append(TRACEQL_SCOPE.sub("", m.group(1)))
if not span_tags:
report.skip("C", "no span-scope filter tags in tempo datasource")
return
miss = [t for t in span_tags if t not in l1_keys]
for t in sorted(set(miss)):
report.violation("C", str(path.relative_to(root)), t, "must exist in L1")
if not miss:
report.ok(f"C: {len(span_tags)} tempo span-filter tag(s) all in L1")
def metric_label_names(root: Path) -> Set[str]:
"""L6: OTel native-metric label keys emitted by the telemetry code, e.g.
`counter->Add(1, {{"job_type", value}})` in MetricsRegistry.cpp. These are
a valid source of dashboard labels distinct from span attributes (L1)."""
labels: Set[str] = set()
for base in ("src", "include"):
for p in (root / base).rglob("*.cpp"):
if not p.is_file():
continue
text = read_source(p)
if "MetricsRegistry" not in p.name and "metric" not in text.lower():
continue
labels |= set(METRIC_LABEL.findall(text))
return labels
def run_rule_d_dashboards(
root: Path, l1_keys: Set[str], metric_labels: Set[str], report: Report
) -> None:
dash_dir = root / "docker" / "telemetry" / "grafana" / "dashboards"
files = sorted(dash_dir.glob("*.json")) if dash_dir.is_dir() else []
if not files:
report.skip("D", "no dashboard JSON present")
return
if not l1_keys:
report.skip("D", "no L1 key set to validate against")
return
builtins = {
"__name__", # Prometheus reserved label for the metric name itself
"le",
"exported_instance",
"span_name",
"status_code",
"service_name",
"service_version",
"service_instance_id",
"job",
"instance",
}
# A dashboard label is valid if it is a span attribute (L1), a native-metric
# label (L6), or a Prometheus/Grafana builtin.
valid = l1_keys | metric_labels | builtins
found = False
for f in files:
try:
text = read_source(f)
except OSError:
continue
# PromQL `sum by (a, b)` and `{label="..."}` references.
labels: Set[str] = set()
for m in re.finditer(r"by\s*\(([^)]*)\)", text):
labels |= {x.strip() for x in m.group(1).split(",") if x.strip()}
for m in re.finditer(r"\b([a-z_][a-z0-9_.]*)\s*[=!]~?\s*\"", text):
labels.add(m.group(1))
for lbl in sorted(labels):
# Strip a TraceQL scope prefix (span./resource./...) — the bare
# attribute is what must resolve against L1.
bare = TRACEQL_SCOPE.sub("", lbl)
if bare in valid:
continue
found = True
report.violation(
"D",
str(f.relative_to(root)),
lbl,
"must exist in L1, a metric label, or be a builtin",
)
if not found:
report.ok(f"D: dashboard PromQL labels all resolve ({len(files)} file(s))")
def run_rule_e_runbook(root: Path, l1_keys: Set[str], report: Report) -> None:
path = root / "docs" / "telemetry-runbook.md"
if not path.is_file():
report.skip("E", "runbook not present")
return
if not l1_keys:
report.skip("E", "no L1 key set to validate against")
return
text = read_source(path)
found = False
# Only the dotted `xrpl.<domain>.<field>` attribute form is a violation. The
# `xrpl.`-with-trailing-dot anchor is the discriminator: it matches the old
# dotted attribute convention being migrated away from, while everything
# else legitimately dotted in the runbook does NOT match it —
# * span names (`consensus.round`, `tx.process`) no `xrpl.` prefix
# * filenames (`xrpld.cfg`, `RCLConsensus.cpp`) `xrpld.`/`.cpp`, not `xrpl.`
# * OTel-standard (`service.name`, `http.method`) no `xrpl.` prefix
# * metric labels (`xrpl_rpc_command`) underscore, no dot
# Legitimate dotted resource attrs (`xrpl.network.id`/`.type`) are in L1 and
# are skipped. A dotted `xrpl.` token absent from L1 is a genuine doc/code
# mismatch (e.g. `xrpl.tx.hash` where the code emits `tx_hash`).
for m in re.finditer(r"`(xrpl\.[a-z][a-z0-9_.]*)`", text):
token = m.group(1)
if token in l1_keys: # legitimate dotted resource attr (xrpl.network.*)
continue
found = True
report.violation(
"E", str(path.relative_to(root)), token, "underscore, not dotted"
)
if not found:
report.ok("E: runbook attribute references consistent with L1")
if __name__ == "__main__":
main()

708
.github/scripts/otel-naming/test_check_otel_naming.py vendored Normal file
View File

@@ -0,0 +1,708 @@
#!/usr/bin/env python3
"""Unit tests for check_otel_naming.py.
Stdlib-only (unittest), matching the dependency-free policy of the check itself.
Run from anywhere:
python .github/scripts/otel-naming/test_check_otel_naming.py
Each rule is exercised in isolation against a synthetic tree / synthetic L1 key
set, covering positive (must flag), negative (must not flag), and boundary
cases. Rule E (runbook dotted-attribute detection) has the densest coverage
because its discriminator — the `xrpl.<domain>.` prefix vs span names,
filenames, OTel-standard keys, and metric labels — is the subtlest.
"""
import contextlib
import importlib.util
import io
import shutil
import tempfile
import unittest
from pathlib import Path
# Load the check module by path (it is not an importable package).
_spec = importlib.util.spec_from_file_location(
"check_otel_naming", str(Path(__file__).with_name("check_otel_naming.py"))
)
chk = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(chk)
# A controlled L1 set used across tests: the two legitimate dotted resource
# attrs plus a handful of underscore span-attribute keys.
L1 = {
"xrpl.network.id",
"xrpl.network.type",
"tx_hash",
"peer_id",
"consensus_mode",
"command",
"rpc_status",
"ledger_seq",
}
def _run_rule_e(runbook_text: str):
"""Run Rule E against a synthetic runbook; return the flagged tokens."""
d = Path(tempfile.mkdtemp())
try:
(d / "docs").mkdir()
(d / "docs" / "telemetry-runbook.md").write_text(runbook_text)
report = chk.Report()
chk.run_rule_e_runbook(d, set(L1), report)
return sorted(v[2] for v in report.violations)
finally:
shutil.rmtree(d)
class RuleERunbook(unittest.TestCase):
"""Rule E: only dotted `xrpl.<domain>.<field>` attribute keys are flagged."""
# ----- positive: genuine dotted attribute-key violations -----
def test_single_dotted_attr(self):
self.assertEqual(_run_rule_e("`xrpl.tx.hash`"), ["xrpl.tx.hash"])
def test_multiple_dotted_attrs(self):
self.assertEqual(
_run_rule_e("`xrpl.tx.hash` and `xrpl.consensus.mode`"),
["xrpl.consensus.mode", "xrpl.tx.hash"],
)
def test_deep_dotted_three_segments(self):
self.assertEqual(
_run_rule_e("`xrpl.consensus.ledger.seq`"), ["xrpl.consensus.ledger.seq"]
)
def test_dotted_attr_with_underscore_field(self):
self.assertEqual(
_run_rule_e("`xrpl.consensus.round_id`"), ["xrpl.consensus.round_id"]
)
def test_repeated_token_reported_each_occurrence(self):
self.assertEqual(
_run_rule_e("`xrpl.tx.hash` ... `xrpl.tx.hash`"),
["xrpl.tx.hash", "xrpl.tx.hash"],
)
def test_resource_attr_not_in_l1_is_flagged(self):
self.assertEqual(
_run_rule_e("`xrpl.network.unknown`"), ["xrpl.network.unknown"]
)
# ----- negative: legitimately-dotted tokens that must NOT be flagged -----
def test_span_name_single(self):
self.assertEqual(_run_rule_e("`consensus.round`"), [])
def test_span_name_multi_segment(self):
self.assertEqual(
_run_rule_e("`consensus.phase.open` `rpc.command.server_info`"), []
)
def test_filename_cfg(self):
self.assertEqual(_run_rule_e("`xrpld.cfg`"), [])
def test_filename_cpp(self):
self.assertEqual(_run_rule_e("`RCLConsensus.cpp`"), [])
def test_otel_standard_service_name(self):
self.assertEqual(_run_rule_e("`service.name`"), [])
def test_otel_standard_http_method(self):
self.assertEqual(_run_rule_e("`http.method`"), [])
def test_metric_label_underscore(self):
self.assertEqual(_run_rule_e("`xrpl_rpc_command`"), [])
def test_bare_underscore_attrs(self):
self.assertEqual(_run_rule_e("`tx_hash` `consensus_mode`"), [])
def test_legit_dotted_resource_attrs_in_l1(self):
self.assertEqual(_run_rule_e("`xrpl.network.id` `xrpl.network.type`"), [])
def test_prose_word(self):
self.assertEqual(_run_rule_e("the `command` attribute"), [])
def test_plain_prose_no_backticks(self):
self.assertEqual(_run_rule_e("xrpl.tx.hash without backticks is prose"), [])
# ----- boundary -----
def test_empty_runbook(self):
self.assertEqual(_run_rule_e(""), [])
def test_lookalike_prefix_xrpld(self):
# `xrpld.` is NOT `xrpl.` — must not match.
self.assertEqual(_run_rule_e("`xrpld.foo`"), [])
def test_lookalike_prefix_underscore(self):
# `xrpl_rpc.command` starts with `xrpl_`, not `xrpl.`.
self.assertEqual(_run_rule_e("`xrpl_rpc.command`"), [])
def test_uppercase_segment_not_matched(self):
# The pattern requires a lowercase char after `xrpl.`; uppercase keys are
# caught by Rule G at the L1 layer, not by the runbook text scan.
self.assertEqual(_run_rule_e("`xrpl.TX.hash`"), [])
def test_token_touching_table_pipes(self):
self.assertEqual(_run_rule_e("| `xrpl.tx.hash` | desc |"), ["xrpl.tx.hash"])
def test_mixed_line_only_xrpl_dotted_flagged(self):
self.assertEqual(
_run_rule_e("`consensus.round` uses `xrpl.tx.hash` and `service.name`"),
["xrpl.tx.hash"],
)
def test_skips_when_runbook_absent(self):
d = Path(tempfile.mkdtemp())
try:
report = chk.Report()
chk.run_rule_e_runbook(d, set(L1), report)
self.assertEqual(report.violations, [])
self.assertTrue(any("SKIP: E" in s for s in report.skips))
finally:
shutil.rmtree(d)
def test_skips_when_l1_empty(self):
d = Path(tempfile.mkdtemp())
try:
(d / "docs").mkdir()
(d / "docs" / "telemetry-runbook.md").write_text("`xrpl.tx.hash`")
report = chk.Report()
chk.run_rule_e_runbook(d, set(), report)
self.assertEqual(report.violations, [])
self.assertTrue(any("SKIP: E" in s for s in report.skips))
finally:
shutil.rmtree(d)
class DslParser(unittest.TestCase):
"""The makeStr/join/seg:: constexpr DSL resolver — the foundation of the
L1 key set. Covers flat, nested, cross-file, alias, and multi-line forms."""
def test_flat_join(self):
syms = chk.resolve_constants(
'inline constexpr auto a = makeStr("xrpl");\n'
'inline constexpr auto b = makeStr("network");\n'
"inline constexpr auto c = join(a, b);\n"
)
self.assertEqual(syms["c"], "xrpl.network")
def test_nested_join_three_segments(self):
syms = chk.resolve_constants(
'inline constexpr auto xrpl = makeStr("xrpl");\n'
'inline constexpr auto network = makeStr("network");\n'
"inline constexpr auto networkId = "
'join(join(xrpl, network), makeStr("id"));\n'
)
self.assertEqual(syms["networkId"], "xrpl.network.id")
def test_qualified_seg_reference(self):
# `seg::rpc` resolves by its bare leaf `rpc`.
syms = chk.resolve_constants('inline constexpr auto rpc = makeStr("rpc");\n')
syms2 = chk.resolve_constants(
'inline constexpr auto command = join(seg::rpc, makeStr("command"));\n',
syms,
)
self.assertEqual(syms2["command"], "rpc.command")
def test_alias_reference(self):
syms = chk.resolve_constants('inline constexpr auto rpc = makeStr("rpc");\n')
chk.resolve_constants("inline constexpr auto alias = seg::rpc;\n", syms)
self.assertEqual(syms["alias"], "rpc")
def test_unresolvable_expr_omitted(self):
syms = chk.resolve_constants("inline constexpr auto x = join(unknown, y);\n")
self.assertNotIn("x", syms)
def test_split_top_level_args_respects_nesting(self):
self.assertEqual(
chk.split_top_level_args("join(seg::a, b), c"),
["join(seg::a, b)", " c"],
)
def test_split_top_level_args_ignores_comma_in_string(self):
self.assertEqual(
chk.split_top_level_args('key, ","'),
["key", ' ","'],
)
def test_strip_comments_removes_line_and_block(self):
self.assertEqual(
chk.strip_comments("a // line\nb /* blk */ c").split(),
["a", "b", "c"],
)
def _write(path: Path, text: str) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text)
def _header(ns_attr_body: str, prefix_seg: str = "") -> str:
"""A minimal *SpanNames.h body: optional seg defs + a namespace attr block."""
return (
"#pragma once\n"
+ prefix_seg
+ "namespace xrpl::telemetry::demo::span {\n"
+ "namespace attr {\n"
+ ns_attr_body
+ "} // namespace attr\n"
+ "}\n"
)
class AttrKeyExtraction(unittest.TestCase):
"""attr_keys_from_header: comment-stripping + multi-line + using re-export."""
def _l1(self, header_text):
d = Path(tempfile.mkdtemp())
try:
h = d / "src" / "DemoSpanNames.h"
_write(h, header_text)
syms = chk.build_global_symbols([h])
return chk.attr_keys_from_header(h, syms)
finally:
shutil.rmtree(d)
def test_single_line_makestr(self):
keys = self._l1(_header('inline constexpr auto k = makeStr("tx_hash");\n'))
self.assertIn("tx_hash", keys)
def test_multiline_constexpr_captured(self):
keys = self._l1(
_header("inline constexpr auto k =\n" ' makeStr("round_time_ms");\n')
)
self.assertIn("round_time_ms", keys)
def test_commented_makestr_not_leaked(self):
keys = self._l1(
_header(
'inline constexpr auto k = makeStr("good");\n'
'// inline constexpr auto bad = makeStr("old.dotted");\n'
)
)
self.assertIn("good", keys)
self.assertNotIn("old.dotted", keys)
def test_block_commented_makestr_not_leaked(self):
keys = self._l1(
_header(
'inline constexpr auto k = makeStr("good");\n'
'/* makeStr("blockbad") */\n'
)
)
self.assertNotIn("blockbad", keys)
class CamelToDotSegments(unittest.TestCase):
"""semconv CamelCase -> dotted OTel-standard key derivation."""
def test_service_instance_id(self):
self.assertEqual(
chk.camel_to_dotsegments("ServiceInstanceId"),
["service", "instance", "id"],
)
def test_service_name(self):
self.assertEqual(chk.camel_to_dotsegments("ServiceName"), ["service", "name"])
def test_derive_keys_from_telemetry_cpp(self):
d = Path(tempfile.mkdtemp())
try:
tele = d / "src" / "libxrpl" / "telemetry" / "Telemetry.cpp"
_write(
tele,
"resource::Resource::Create({\n"
" {semconv::service::kServiceName, x},\n"
" {semconv::service::kServiceInstanceId, y},\n"
"});\n",
)
report = chk.Report()
allow = chk.derive_dotted_resource_keys(d, {}, report)
self.assertIn("service.name", allow)
self.assertIn("service.instance.id", allow)
finally:
shutil.rmtree(d)
def _run_rule_a(keys_by_header, allow):
report = chk.Report()
chk.run_rule_a(keys_by_header, allow, report)
return sorted(v[2] for v in report.violations)
class RuleADotted(unittest.TestCase):
def test_dotted_attr_not_in_allow_flagged(self):
kbh = {Path("src/RpcSpanNames.h"): {"xrpl.tx.hash", "command"}}
self.assertEqual(_run_rule_a(kbh, {"xrpl.network.id"}), ["xrpl.tx.hash"])
def test_resource_attr_in_allow_passes(self):
kbh = {Path("src/SpanNames.h"): {"xrpl.network.id"}}
self.assertEqual(_run_rule_a(kbh, {"xrpl.network.id"}), [])
def test_bare_key_never_flagged(self):
kbh = {Path("src/TxSpanNames.h"): {"tx_hash", "command"}}
self.assertEqual(_run_rule_a(kbh, set()), [])
def _run_rule_g(keys_by_header):
report = chk.Report()
chk.run_rule_g(keys_by_header, report)
return sorted(v[2] for v in report.violations)
class RuleGSnakeCase(unittest.TestCase):
def test_camelcase_flagged(self):
self.assertEqual(_run_rule_g({Path("h"): {"txHash"}}), ["txHash"])
def test_uppercase_flagged(self):
self.assertEqual(_run_rule_g({Path("h"): {"TX_HASH"}}), ["TX_HASH"])
def test_space_flagged(self):
self.assertEqual(_run_rule_g({Path("h"): {"bad key"}}), ["bad key"])
def test_snake_case_passes(self):
self.assertEqual(_run_rule_g({Path("h"): {"tx_hash", "rpc_status"}}), [])
def test_dotted_resource_segments_pass(self):
self.assertEqual(_run_rule_g({Path("h"): {"xrpl.network.id"}}), [])
def test_dotted_with_bad_segment_flagged(self):
self.assertEqual(
_run_rule_g({Path("h"): {"xrpl.Network.id"}}), ["xrpl.Network.id"]
)
class RuleFAndH(unittest.TestCase):
"""run_rule_f: literal keys/span-names flagged; values & tests exempt.
Rule H: qualified constant not in any header warns (non-fatal)."""
def _run(self, rel_path, source, header_symbols=frozenset()):
d = Path(tempfile.mkdtemp())
try:
_write(d / rel_path, source)
report = chk.Report()
chk.run_rule_f(d, report, set(header_symbols))
return (
sorted(v[2] for v in report.violations),
sorted(w[2] for w in report.warnings),
)
finally:
shutil.rmtree(d)
def test_literal_key_flagged(self):
v, _ = self._run("src/Foo.cpp", 'g.setAttribute("lit_key", v);\n')
self.assertEqual(v, ['setAttribute arg0 "lit_key"'])
def test_literal_value_exempt(self):
v, _ = self._run("src/Foo.cpp", 'g.setAttribute(attr::command, "submit");\n')
self.assertEqual(v, [])
def test_span_name_args_flagged(self):
v, _ = self._run("src/Foo.cpp", 'SpanGuard::span(cat, "rpc", "command");\n')
self.assertEqual(v, ['span arg1 "rpc"', 'span arg2 "command"'])
def test_test_path_exempt(self):
v, _ = self._run("src/test/Foo.cpp", 'g.setAttribute("lit_key", v);\n')
self.assertEqual(v, [])
def test_spannames_header_exempt(self):
v, _ = self._run("src/DemoSpanNames.h", 'g.setAttribute("lit_key", v);\n')
self.assertEqual(v, [])
def test_bare_span_call_not_matched(self):
# No SpanGuard/./-> receiver -> not a telemetry call-site.
v, _ = self._run("src/Foo.cpp", 'auto s = span("not", "telemetry");\n')
self.assertEqual(v, [])
def test_multiline_call_reports_first_line(self):
v, _ = self._run("src/Foo.cpp", 'g.setAttribute(\n "k",\n v);\n')
self.assertEqual(v, ['setAttribute arg0 "k"'])
def test_paren_in_string_value_does_not_break_parsing(self):
# The ")" inside the value must not end the call early; key still seen.
v, _ = self._run("src/Foo.cpp", 'g.setAttribute("k", ")");\n')
self.assertEqual(v, ['setAttribute arg0 "k"'])
def test_rule_h_qualified_constant_warns(self):
v, w = self._run(
"src/Foo.cpp",
"g.setAttribute(consensus::span::accept, v);\n",
header_symbols={"command"},
)
self.assertEqual(v, [])
self.assertEqual(w, ["setAttribute arg0 consensus::span::accept"])
def test_rule_h_known_constant_no_warning(self):
_, w = self._run(
"src/Foo.cpp",
"g.setAttribute(rpc_span::attr::command, v);\n",
header_symbols={"command"},
)
self.assertEqual(w, [])
def test_rule_h_bare_local_no_warning(self):
_, w = self._run(
"src/Foo.cpp", "g.setAttribute(myLeaf, v);\n", header_symbols={"command"}
)
self.assertEqual(w, [])
class RuleBCollector(unittest.TestCase):
def _run(self, yaml_text, l1):
d = Path(tempfile.mkdtemp())
try:
_write(d / "docker" / "telemetry" / "otel-collector-config.yaml", yaml_text)
report = chk.Report()
chk.run_rule_b_collector(d, set(l1), report)
return sorted(v[2] for v in report.violations), report.skips
finally:
shutil.rmtree(d)
def test_dimension_not_in_l1_flagged(self):
y = "spanmetrics:\n dimensions:\n - name: bogus_dim\n - name: command\n"
v, _ = self._run(y, {"command"})
self.assertEqual(v, ["bogus_dim"])
def test_all_dimensions_in_l1_pass(self):
y = "spanmetrics:\n dimensions:\n - name: command\n - name: rpc_status\n"
v, _ = self._run(y, {"command", "rpc_status"})
self.assertEqual(v, [])
def test_skip_when_no_spanmetrics_block(self):
v, skips = self._run("receivers:\n otlp:\n", {"command"})
self.assertEqual(v, [])
self.assertTrue(any("SKIP: B" in s for s in skips))
class RuleCTempo(unittest.TestCase):
"""Rule C reads the Grafana Tempo DATASOURCE file's search.filters and
validates only span-scope tags against L1."""
DS = "docker/telemetry/grafana/provisioning/datasources/tempo.yaml"
def _run(self, yaml_text, l1):
d = Path(tempfile.mkdtemp())
try:
_write(d / self.DS, yaml_text)
report = chk.Report()
chk.run_rule_c_tempo(d, set(l1), report)
return sorted(v[2] for v in report.violations), report.skips
finally:
shutil.rmtree(d)
def _filter(self, fid, tag, scope):
return (
f" - id: {fid}\n"
f" tag: {tag}\n"
f' operator: "="\n'
f" scope: {scope}\n"
f" type: static\n"
)
def test_span_tag_not_in_l1_flagged(self):
y = "search:\n filters:\n" + self._filter("f1", "bogus_tag", "span")
v, _ = self._run(y, {"command"})
self.assertEqual(v, ["bogus_tag"])
def test_span_tags_in_l1_pass(self):
y = (
"search:\n filters:\n"
+ self._filter("f1", "command", "span")
+ self._filter("f2", "tx_hash", "span")
)
v, _ = self._run(y, {"command", "tx_hash"})
self.assertEqual(v, [])
def test_resource_and_intrinsic_tags_ignored(self):
# service.* (resource) and name/status/duration (intrinsic) are not
# span attributes — they must not be validated against L1.
y = (
"search:\n filters:\n"
+ self._filter("f1", "service.instance.id", "resource")
+ self._filter("f2", "name", "intrinsic")
+ self._filter("f3", "duration", "intrinsic")
)
v, skips = self._run(y, {"command"})
self.assertEqual(v, [])
self.assertTrue(any("SKIP: C" in s for s in skips))
def test_skip_when_datasource_absent(self):
d = Path(tempfile.mkdtemp())
try:
report = chk.Report()
chk.run_rule_c_tempo(d, {"command"}, report)
self.assertEqual(report.violations, [])
self.assertTrue(any("SKIP: C" in s for s in report.skips))
finally:
shutil.rmtree(d)
class RuleDDashboards(unittest.TestCase):
def _run(self, json_text, l1, metric_labels=frozenset()):
d = Path(tempfile.mkdtemp())
try:
_write(
d / "docker" / "telemetry" / "grafana" / "dashboards" / "x.json",
json_text,
)
report = chk.Report()
chk.run_rule_d_dashboards(d, set(l1), set(metric_labels), report)
return sorted(v[2] for v in report.violations)
finally:
shutil.rmtree(d)
def test_unknown_promql_label_flagged(self):
self.assertEqual(
self._run('"expr": "sum by (bogus_label) (x)"', {"command"}),
["bogus_label"],
)
def test_builtin_labels_not_flagged(self):
self.assertEqual(
self._run('"expr": "sum by (le, span_name, exported_instance) (x)"', set()),
[],
)
def test_prometheus_name_label_not_flagged(self):
# `__name__` is the Prometheus reserved metric-name label; the renamed
# system-*.json dashboards use `sum by (le, __name__)`.
self.assertEqual(
self._run('"expr": "sum by (le, __name__) (rate(x[5m]))"', set()),
[],
)
def test_l1_label_passes(self):
self.assertEqual(self._run('"q": "{command=\\"x\\"}"', {"command"}), [])
def test_traceql_span_prefix_stripped(self):
# `span.establish_count` must validate against the bare L1 key.
self.assertEqual(
self._run(
'"expr": "count_over_time(x) by (span.establish_count)"',
{"establish_count"},
),
[],
)
def test_traceql_resource_prefix_stripped(self):
self.assertEqual(self._run('"q": "{resource.service_name=\\"x\\"}"', set()), [])
def test_native_metric_label_passes(self):
# `job_type` / `reason` are emitted by MetricsRegistry, not span attrs.
self.assertEqual(
self._run(
'"expr": "sum by (job_type, reason) (x)"',
{"command"},
metric_labels={"job_type", "reason"},
),
[],
)
def test_unknown_label_still_flagged_with_metric_labels(self):
# A label that is neither L1, metric label, nor builtin still fails.
self.assertEqual(
self._run(
'"expr": "sum by (bogus) (x)"',
{"command"},
metric_labels={"job_type"},
),
["bogus"],
)
def test_span_prefixed_unknown_still_flagged(self):
# `span.not_a_key` whose bare form is unknown is still a violation.
self.assertEqual(
self._run('"expr": "x by (span.not_a_key)"', {"command"}),
["span.not_a_key"],
)
class MetricLabelExtraction(unittest.TestCase):
"""L6: native-metric label keys parsed from C++ instrument calls."""
def test_extracts_add_label(self):
d = Path(tempfile.mkdtemp())
try:
_write(
d / "src" / "xrpld" / "telemetry" / "MetricsRegistry.cpp",
'counter->Add(1, {{"job_type", std::string(jobType)}});\n'
'c2->Add(1, {{"reason", std::string(r)}});\n',
)
self.assertEqual(chk.metric_label_names(d), {"job_type", "reason"})
finally:
shutil.rmtree(d)
def test_no_metrics_file_empty(self):
d = Path(tempfile.mkdtemp())
try:
(d / "src").mkdir()
self.assertEqual(chk.metric_label_names(d), set())
finally:
shutil.rmtree(d)
class ReportExitContract(unittest.TestCase):
@staticmethod
def _exit_code(report):
"""Call render_and_exit (which prints + raises SystemExit), swallowing
its stdout, and return the exit code."""
with contextlib.redirect_stdout(io.StringIO()):
try:
report.render_and_exit()
except SystemExit as e:
return e.code
return None # pragma: no cover - render_and_exit always exits
def test_violation_exits_nonzero(self):
r = chk.Report()
r.violation("A", "f", "tok", "exp")
self.assertEqual(self._exit_code(r), 1)
def test_clean_exits_zero(self):
r = chk.Report()
r.ok("all good")
self.assertEqual(self._exit_code(r), 0)
def test_warning_only_exits_zero(self):
r = chk.Report()
r.warning("H", "f", "tok", "note")
self.assertEqual(self._exit_code(r), 0)
class RuleEReportTuple(unittest.TestCase):
"""Assert Rule E records the full (rule, expected) tuple, not just token."""
def test_violation_tuple_fields(self):
d = Path(tempfile.mkdtemp())
try:
(d / "docs").mkdir()
(d / "docs" / "telemetry-runbook.md").write_text("`xrpl.tx.hash`")
report = chk.Report()
chk.run_rule_e_runbook(d, {"xrpl.network.id"}, report)
self.assertEqual(len(report.violations), 1)
rule, _loc, token, expected = report.violations[0]
self.assertEqual(rule, "E")
self.assertEqual(token, "xrpl.tx.hash")
self.assertEqual(expected, "underscore, not dotted")
finally:
shutil.rmtree(d)
def test_clean_runbook_records_ok(self):
d = Path(tempfile.mkdtemp())
try:
(d / "docs").mkdir()
(d / "docs" / "telemetry-runbook.md").write_text(
"`tx_hash` `consensus.round`"
)
report = chk.Report()
chk.run_rule_e_runbook(d, {"tx_hash"}, report)
self.assertEqual(report.violations, [])
self.assertTrue(any("E:" in c for c in report.checked))
finally:
shutil.rmtree(d)
if __name__ == "__main__":
unittest.main(verbosity=2)

57
.github/scripts/strategy-matrix/generate.py vendored
View File

@@ -27,6 +27,19 @@ def get_cmake_args(build_type: str, extra_args: str) -> str:
return " ".join(args)
def runs_on_event(exclude_event_types: list[str], event: str | None) -> bool:
"""Whether a config should run for the current event.
'exclude_event_types' is a list of GitHub event names (e.g.
["pull_request"]) on which the config should NOT run; an empty list means
the config runs on every event. When no event is given (event is None), no
filtering is applied.
"""
if event is None:
return True
return event not in exclude_event_types
# ---------------------------------------------------------------------------
# Input types — shapes of the JSON config files
# ---------------------------------------------------------------------------
@@ -43,6 +56,9 @@ class LinuxConfig:
suffix: str = ""
extra_cmake_args: str = ""
image: str = "" # only used by package_configs entries
# List of GitHub event names (e.g. "pull_request") on which this config
# should NOT run. Empty means it runs on every event.
exclude_event_types: list[str] = dataclasses.field(default_factory=list)
@dataclasses.dataclass
@@ -77,6 +93,9 @@ class PlatformConfig:
build_type: list[str]
build_only: bool = False # if true, skip tests (e.g. macos/Windows Debug)
extra_cmake_args: str = ""
# List of GitHub event names (e.g. "pull_request") on which this config
# should NOT run. Empty means it runs on every event.
exclude_event_types: list[str] = dataclasses.field(default_factory=list)
def __post_init__(self) -> None:
if isinstance(self.build_type, str):
@@ -151,16 +170,21 @@ _ARCHS: dict[str, Architecture] = {
}
def expand_linux_matrix(linux: LinuxFile) -> list[MatrixEntry]:
def expand_linux_matrix(
linux: LinuxFile, event: str | None = None
) -> list[MatrixEntry]:
"""Expand a LinuxFile into a flat list of matrix entries.
Each config entry is expanded over the cross-product of its
compiler, build_type, sanitizers, and architecture lists.
compiler, build_type, sanitizers, and architecture lists. Configs that
exclude the current event are skipped.
"""
entries: list[MatrixEntry] = []
for distro, configs in linux.configs.items():
for cfg in configs:
if not runs_on_event(cfg.exclude_event_types, event):
continue
# An empty sanitizers list means "one entry with no sanitizer".
effective_sanitizers = cfg.sanitizers or [""]
effective_archs = {arch: _ARCHS[arch] for arch in cfg.arch}
@@ -218,13 +242,20 @@ def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
return entries
def expand_platform_matrix(pf: PlatformFile) -> list[MatrixEntry]:
"""Expand a PlatformFile (macOS or Windows) into matrix entries."""
def expand_platform_matrix(
pf: PlatformFile, event: str | None = None
) -> list[MatrixEntry]:
"""Expand a PlatformFile (macOS or Windows) into matrix entries.
Configs that exclude the current event are skipped.
"""
platform_name, arch = pf.platform.split("/")
is_windows = platform_name == "windows"
entries: list[MatrixEntry] = []
for cfg in pf.configs:
if not runs_on_event(cfg.exclude_event_types, event):
continue
for build_type in cfg.build_type:
entries.append(
MatrixEntry(
@@ -262,6 +293,14 @@ if __name__ == "__main__":
help="Emit the Linux packaging matrix instead of the build/test matrix.",
action="store_true",
)
parser.add_argument(
"-e",
"--event",
help="The GitHub event name that triggered the workflow (e.g. 'push', "
"'pull_request'). Configs are filtered by their 'event_type'. If "
"omitted, no filtering is applied.",
default=None,
)
args = parser.parse_args()
matrix: list[MatrixEntry] | list[PackagingEntry] = []
@@ -270,12 +309,16 @@ if __name__ == "__main__":
matrix = expand_linux_packaging(LinuxFile.load(THIS_DIR / "linux.json"))
else:
if args.config in ("linux", None):
matrix += expand_linux_matrix(LinuxFile.load(THIS_DIR / "linux.json"))
matrix += expand_linux_matrix(
LinuxFile.load(THIS_DIR / "linux.json"), args.event
)
if args.config in ("macos", None):
matrix += expand_platform_matrix(PlatformFile.load(THIS_DIR / "macos.json"))
matrix += expand_platform_matrix(
PlatformFile.load(THIS_DIR / "macos.json"), args.event
)
if args.config in ("windows", None):
matrix += expand_platform_matrix(
PlatformFile.load(THIS_DIR / "windows.json")
PlatformFile.load(THIS_DIR / "windows.json"), args.event
)
print(f"matrix={json.dumps({'include': [dataclasses.asdict(e) for e in matrix]})}")

3
.github/scripts/strategy-matrix/linux.json vendored
View File

@@ -41,7 +41,8 @@
"build_type": ["Debug"],
"arch": ["amd64"],
"suffix": "unity",
"extra_cmake_args": "-Dunity=ON"
"extra_cmake_args": "-Dunity=ON",
"exclude_event_types": ["pull_request"]
}
],

3
.github/scripts/strategy-matrix/macos.json vendored
View File

@@ -9,7 +9,8 @@
{
"build_type": "Debug",
"extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
"build_only": true
"build_only": true,
"exclude_event_types": ["pull_request"]
}
]
}

6
.github/scripts/strategy-matrix/windows.json vendored
View File

@@ -3,6 +3,10 @@
"runner": ["self-hosted", "Windows", "devbox"],
"configs": [
{ "build_type": "Release" },
{ "build_type": "Debug", "build_only": true }
{
"build_type": "Debug",
"build_only": true,
"exclude_event_types": ["pull_request"]
}
]
}

8
.github/workflows/on-pr.yml vendored
View File

@@ -51,8 +51,10 @@ jobs:
files: |
# These paths are unique to `on-pr.yml`.
.github/scripts/levelization/**
.github/scripts/otel-naming/**
.github/scripts/rename/**
.github/workflows/reusable-check-levelization.yml
.github/workflows/reusable-check-otel-naming.yml
.github/workflows/reusable-check-rename.yml
.github/workflows/on-pr.yml
@@ -108,6 +110,11 @@ jobs:
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' }}
@@ -176,6 +183,7 @@ jobs:
if: failure() || cancelled()
needs:
- check-levelization
- check-otel-naming
- check-rename
- clang-tidy
- build-test

28
.github/workflows/reusable-check-otel-naming.yml vendored Normal file
View File

@@ -0,0 +1,28 @@
# 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: 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

3
.github/workflows/reusable-strategy-matrix.yml vendored
View File

@@ -35,4 +35,5 @@ jobs:
id: generate
env:
GENERATE_CONFIG: ${{ inputs.os != '' && format('--config={0}', inputs.os) || '' }}
run: ./generate.py ${GENERATE_CONFIG} >>"${GITHUB_OUTPUT}"
GENERATE_EVENT: ${{ github.event_name }}
run: ./generate.py ${GENERATE_CONFIG} --event="${GENERATE_EVENT}" >>"${GITHUB_OUTPUT}"