feat: migrate skills review desk to astro

2026-09-05 16:54:37 +00:00
parent 107e429fb9
commit 71e4775573
66 changed files with 8184 additions and 96 deletions
@@ -0,0 +1,77 @@
+# Auditing a service and the volume gate
+
+## Static audit
+
+Run from the checkout root of any Go service under `sources/project/`. Heuristic, not a linter: it flags short projection methods such as `toShortString()` as dumps, and it does not know about on-demand troubleshooting guards. Read what it prints; do not treat the counts as a gate on their own.
+
+```python
+import re, glob
+
+files = [f for f in glob.glob('**/*.go', recursive=True)
+         if not f.endswith('_test.go') and '/vendor/' not in f]
+info = dump = loop = noctx = 0
+for path in files:
+    depth, loops = 0, []
+    for i, line in enumerate(open(path, errors='ignore'), 1):
+        stripped = line.strip()
+        if re.search(r'\bfor .*\{\s*$', stripped):
+            loops.append(depth)
+        depth += line.count('{') - line.count('}')
+        loops = [d for d in loops if d < depth]
+        if re.search(r'logging\.Log(Info|Debug|Warning|Error|Fatal)\(', line):
+            noctx += 1
+            print(f'noCtx  {path}:{i}: {stripped[:100]}')
+        if re.search(r'logging\.LogInfo(Ctx)?\(', line):
+            info += 1
+            if '%+v' in line and not re.search(r'%\+v[^"]*"\s*,\s*len\(', line):
+                dump += 1
+                print(f'dump   {path}:{i}: {stripped[:100]}')
+            if loops:
+                loop += 1
+                print(f'loop   {path}:{i}: {stripped[:100]}')
+print(f'INFO={info} dump={dump} loop={loop} noCtx={noctx}')
+```
+
+To exclude lines already behind an on-demand troubleshooting guard, track the brace depth of the block opened by `IsAlarmTroubleshootingActive(` and skip lines while inside it. In `gfiber-policy-executor` that moved the count from 77 INFO sites to 34 ungated ones, which is the number that matters.
+
+### How to read the output
+
+| Signal | Meaning |
+|--------|---------|
+| high `dump` against low `INFO` | the few INFO lines the service has are the expensive kind |
+| any `loop` | a line scaling with item count rather than request count; the per-item result line is the one legitimate case |
+| `noCtx` | lines that cannot be attached to a work item |
+
+## Volume gate
+
+Any change to logging on a high-volume path states its volume impact in the merge request. Measure the same scenario before and after, in the same namespace and window, using the `graylog-search` entry in [scripts/data/index.yaml](../../../scripts/data/index.yaml) with `--scope containers` and a container plus level filter, per [scripts/data/graylog-search.example.md](../../../scripts/data/graylog-search.example.md).
+
+Repeat for INFO, DEBUG, WARN and ERROR, then rerun on the branch build.
+
+| Metric | Before | After | Delta |
+|--------|--------|-------|-------|
+| INFO messages per run | | | |
+| INFO bytes per run | | | |
+| DEBUG messages per run | | | |
+| WARN and ERROR per run | | | |
+| Longest single INFO line, bytes | | | |
+
+Acceptance: INFO message count and INFO bytes must not increase. DEBUG is allowed to grow, since it is off in production.
+
+For SA services use the registered SVT cases from [skills/gfiber-svt-analysis/cases/index.yaml](../../gfiber-svt-analysis/cases/index.yaml). Services without an SVT case need a reference scenario agreed with the reviewer before the gate means anything.
+
+On the same run, confirm that a sample identifier from it is still findable at `LOG_LEVEL: INFO` with the SA alarm template from [queries/graylog/index.yaml](../../../queries/graylog/index.yaml). That is the regression the policy exists to prevent, and it is satisfied by the per-item result line rather than by anything new.
+
+## Merge request checklist
+
+The hard rules in [levels.md](levels.md) double as the review checklist. In addition:
+
+- Every new INFO line matches one of the four INFO cases.
+- No new INFO line prints a collection, a struct or a body.
+- No new INFO line sits inside a loop over domain objects.
+- Every identifier list is capped.
+- Every call is the `Ctx` variant.
+- WARN and ERROR on failure paths carry the identifiers of the work they lost.
+- The summary line is written from a `defer` that survives a panic.
+- New metric labels come from a fixed vocabulary, with no identifiers in them.
+- `go vet` is clean and no line prints a pointer address or a `%!s` marker.