Skip to content

docs(patterns): backfill #14 walkthrough + document #6/#15 gaps#524

Merged
trilamsr merged 2 commits into
mainfrom
docs/patterns-backfill-06-14
Jun 4, 2026
Merged

docs(patterns): backfill #14 walkthrough + document #6/#15 gaps#524
trilamsr merged 2 commits into
mainfrom
docs/patterns-backfill-06-14

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes the missing-pattern-docs gap in docs/patterns/ for the two
numerically-missing IDs (#6, #14) against NORTHSTARS Appendix A's
15-pattern roster.

Investigation

Surveyed module/pkg/patterns/, NORTHSTARS Appendix A, and
MILESTONES M18/M19 to pin actual detector state per ID:

ID NORTHSTARS Appendix A claim Actual repo state Decision
#6 Stragglers (M18) ☑ in-tree detector No detector exists — no straggler*.go, no data_time aggregation, no replay fixture. Only failure-inject cpu-steal chaos hook (M4b) lands the symptom. MILESTONES line 237 acknowledges M18 is at-risk and build-time-coupled to M17's cross_rank.go. The Appendix A mark is aspirational, not current state. Option B — README gap-note explicitly documenting the unimplemented state + linking the M18 milestone. Reconciliation of Appendix A's claim is left for the detector-shipping PR.
#14 Pod evicted (M19) ☑ in-tree detector Shipped — patterns.PodEvictedDetector in module/pkg/patterns/pod_evicted.go, processor wiring in module/processor/patterndetectorprocessor/, canonical replay fixture at module/pkg/replay/pod_evicted/canonical/. Option A — backfill full operator walkthrough 14-pod-evicted-walkthrough.md following the 02-ib-link-flap-walkthrough.md template (Symptom → Signal → Query → Alert → Escalation → Replay → Detector status → Verdict shape → Integration recipe).

Also surfaced #15 (Image pull / FailedMount on restart) — present
in Appendix A but absent from this directory. Added to the same
"Reserved / unfilled" table for completeness so every Appendix A
ID is accounted for somewhere in docs/patterns/.

Changes

Test plan

  • make doc-check green — all markdown links + anchors resolve,
    banned-phrase lint clean, walkthrough renders.
  • Pre-commit hooks pass (golangci-lint, go vet,
    go mod verify, attribute-namespace-check,
    deprecation-check).
  • Cross-checked every link in the new walkthrough resolves to a
    real on-disk file (pod_evicted.go, pod_evicted_test.go,
    pod_evicted_bench_test.go, replay/pod_evicted/canonical/,
    k8sobjects-events.md, ATTRIBUTES.md,
    example_config.yaml).
docs(patterns): add operator walkthrough for pattern #14 (pod evicted); document pattern #6 + #15 gaps in the patterns README.

Signed-off-by: Tri Lam <tree@lumalabs.ai>
@trilamsr trilamsr enabled auto-merge (squash) June 4, 2026 02:31
Signed-off-by: Tri Lam <tree@lumalabs.ai>
@trilamsr

trilamsr commented Jun 4, 2026

Copy link
Copy Markdown
Contributor Author

Adversarial review (independent pass): grade A.

Findings:

  1. (ACT, fixed in 7fd2022) — alert YAML filtered on k8s.namespace.name, which is not in the customer-stable scalar-promotion contract (verdict.go:60-62 only promotes k8s.pod.namespace). Operators following the walkthrough would write a filter that silently matches nothing once the verdict-driven dashboard ships. Swapped to k8s.pod.namespace.
  2. (DROP) — count_over_time({...}) is LogQL-flavored, but the section header already labels it 'OTLP filter — post-OTTL' (log records, not metrics), so the syntax flavor is honest.
  3. (verified) — every pattern.* and k8s.* verdict attribute in the walkthrough's verdict-shape table matches the constants in module/processor/patterndetectorprocessor/patterndetector.go:115-127 and module/pkg/patterns/verdict.go:59-77.
  4. (verified) — headline regex /Pod .* evicted at .* due to .* pressure/ matches the canonical fixture's golden.json headline.
  5. (verified) — Make RFC process optional, not gated #6 gap-note is accurate: no straggler*.go, no data_time aggregator in module/pkg/patterns/; NORTHSTARS Appendix A's ☑ in-tree detector mark is aspirational.
  6. (verified) — coverage count 'Seven of 15' = ci(deps): bump the gh-actions group with 5 updates #1, Bump the gh-actions group across 1 directory with 4 updates #2, Add NORTHSTARS, RFC-0002, and Q1 MILESTONES #3, Wave 1: governance bootstrap (CODEOWNERS, DCO, signing) #4, Apply Wave-1 follow-ups: tests, automation, doc-truth #5, Add AI review + PR-creation gates and lifecycle skills #7, [docs] FOLLOWUPS: close squash-merge-trailer item with observation #14 in the shipped table.
  7. (verified) — every referenced file path exists on disk: example_config.yaml, pod_evicted_test.go, pod_evicted_bench_test.go, replay/pod_evicted/canonical/, replay/pod_evicted/_negative/, replay/pod_evicted/_real_world/, k8sobjects-events.md, ATTRIBUTES.md.

Grade A: doc-only PR with one load-bearing fix applied. Auto-merge armed.

@trilamsr trilamsr merged commit c14ef09 into main Jun 4, 2026
12 checks passed
@trilamsr trilamsr deleted the docs/patterns-backfill-06-14 branch June 4, 2026 02:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant