mirror of
https://github.com/XRPLF/rippled.git
synced 2026-07-23 23:20:33 +00:00
Merge branch 'pratik/otel-phase6-statsd' into pratik/otel-phase7-native-metrics
Bring the hardened OTel naming check (Rule E fix + 71 tests) and the phase 1-6 convention work forward into phase 7 (native metrics). Conflict resolution: - 05-configuration-reference.md: kept phase-7's native-OTLP metrics story (server=otel, /v1/metrics) over phase-6's superseded StatsD scrape job, in prose form (no code block). - ordering.txt/loops.txt: regenerated via generate.py (not hand-edited). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Pratik Mankawde
@@ -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
|
||||
@@ -333,5 +333,6 @@ xrpld.shamap > xrpld.core
|
||||
xrpld.shamap > xrpl.protocol
|
||||
xrpld.shamap > xrpl.shamap
|
||||
xrpld.telemetry > xrpl.basics
|
||||
xrpld.telemetry > xrpld.consensus
|
||||
xrpld.telemetry > xrpl.protocol
|
||||
xrpld.telemetry > xrpl.telemetry
|
||||
|
||||
65
.github/scripts/otel-naming/README.md
vendored
Normal file
65
.github/scripts/otel-naming/README.md
vendored
Normal 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 PromQL label (non-builtin) exists in the L1 key set. |
|
||||
| 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.
|
||||
769
.github/scripts/otel-naming/check_otel_naming.py
vendored
Normal file
769
.github/scripts/otel-naming/check_otel_naming.py
vendored
Normal file
@@ -0,0 +1,769 @@
|
||||
#!/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)
|
||||
|
||||
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 PromQL label (non-builtin) exists in the L1 key set.
|
||||
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)
|
||||
|
||||
|
||||
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) -------------------
|
||||
run_rule_b_collector(root, l1_keys, report)
|
||||
run_rule_c_tempo(root, l1_keys, report)
|
||||
run_rule_d_dashboards(root, l1_keys, 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:
|
||||
path = root / "docker" / "telemetry" / "tempo.yaml"
|
||||
if not path.is_file():
|
||||
report.skip("C", "tempo.yaml not present")
|
||||
return
|
||||
text = read_source(path)
|
||||
tags = re.findall(r"(?:tag|attribute)\s*:\s*([A-Za-z0-9_.]+)", text)
|
||||
span_tags = [t for t in tags if not t.startswith(("service.", "span."))]
|
||||
if not span_tags:
|
||||
report.skip("C", "no span-attribute tags in tempo.yaml")
|
||||
return
|
||||
if not l1_keys:
|
||||
report.skip("C", "no L1 key set to validate against")
|
||||
return
|
||||
miss = [t for t in span_tags if t not in l1_keys]
|
||||
for t in 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 tag(s) all in L1")
|
||||
|
||||
|
||||
def run_rule_d_dashboards(root: Path, l1_keys: 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 = {
|
||||
"le",
|
||||
"exported_instance",
|
||||
"span_name",
|
||||
"status_code",
|
||||
"service_name",
|
||||
"service_version",
|
||||
"service_instance_id",
|
||||
"job",
|
||||
"instance",
|
||||
}
|
||||
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):
|
||||
if lbl in builtins or lbl in l1_keys:
|
||||
continue
|
||||
found = True
|
||||
report.violation(
|
||||
"D", str(f.relative_to(root)), lbl, "must exist in L1 or builtin"
|
||||
)
|
||||
if not found:
|
||||
report.ok(f"D: dashboard PromQL labels all in L1 ({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()
|
||||
571
.github/scripts/otel-naming/test_check_otel_naming.py
vendored
Normal file
571
.github/scripts/otel-naming/test_check_otel_naming.py
vendored
Normal file
@@ -0,0 +1,571 @@
|
||||
#!/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 RuleDDashboards(unittest.TestCase):
|
||||
def _run(self, json_text, l1):
|
||||
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), 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_l1_label_passes(self):
|
||||
self.assertEqual(self._run('"q": "{command=\\"x\\"}"', {"command"}), [])
|
||||
|
||||
|
||||
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
57
.github/scripts/strategy-matrix/generate.py
vendored
@@ -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
3
.github/scripts/strategy-matrix/linux.json
vendored
@@ -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
3
.github/scripts/strategy-matrix/macos.json
vendored
@@ -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
6
.github/scripts/strategy-matrix/windows.json
vendored
@@ -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"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user