Skip to content

fix(examples): ncclfrreceiver example_config -> RFC-0013 (#457)#462

Merged
trilamsr merged 1 commit into
mainfrom
fix/457-ncclfrreceiver-example-config-cleanup
Jun 2, 2026
Merged

fix(examples): ncclfrreceiver example_config -> RFC-0013 (#457)#462
trilamsr merged 1 commit into
mainfrom
fix/457-ncclfrreceiver-example-config-cleanup

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 2, 2026

Copy link
Copy Markdown
Contributor

Summary

Sibling cleanup to #458 (which closed #454). module/receiver/ncclfrreceiver/example_config.yaml referenced the retired stdoutexporter, and its README invoked the deleted tracecore collect subcommand.

Both were retired by RFC-0013 PR-A2: stdoutexporter -> upstream debug; collect subcommand removed -- the OCB-assembled binary takes --config= directly.

Applies the same recipe as #458:

  • exporters.stdoutexporter -> exporters.debug with verbosity: detailed (matches the old stdoutexporter output shape).
  • Pipeline exporters: [stdoutexporter] -> exporters: [debug].
  • README's tracecore collect --config … invocation -> ./_build/tracecore --config=…, with an explanatory pointer back to RFC-0013 PR-A2.

Root cause

Two layers, identical to #458:

  1. Direct: RFC-0013 PR-A2 retired the in-tree stdoutexporter and the collect subcommand; the operator-facing receiver example/README was not migrated alongside.
  2. Why it drifted undetected: scripts/validator-recipe.sh only walks docs/integrations/*.md. There is no CI gate that walks module/**/example_config.yaml, so the file stayed broken on main until fix(examples): with-telemetry.yaml -> RFC-0013 successor components (#454) #458's A+ sweep noticed.

A structural fix would extend the validator sweep to module/**/example_config.yaml (and docs/examples/*.yaml, per #458). Out of scope for this PR -- if reviewer agrees, I'll file as a follow-up.

Verification

$ ./_build/tracecore validate --config=module/receiver/ncclfrreceiver/example_config.yaml
# pre-fix:  exit 1 ('exporters' unknown type: "stdoutexporter")
# post-fix: exit 0

$ cd module && go test -race -count=1 ./receiver/ncclfrreceiver/...
ok    github.com/tracecoreai/tracecore/module/receiver/ncclfrreceiver    3.247s

$ make validator-recipe
validator-recipe: 14 validated, 3 skipped (non-linux host) of 12 recipe(s)
PASS test 1..5; validator-recipe_test: all assertions passed

Pre-commit gates green: golangci-lint, go vet, go mod verify, attribute-namespace-check, DCO sign-off.

A+ sweep

Walked every module/**/example_config.yaml for the retired symbols (stdoutexporter, clockreceiver, telemetrygeneratorreceiver, tracecore collect):

  • module/processor/patterndetectorprocessor/example_config.yaml -- tracecore validate exit 0. Clean.
  • module/processor/rankjoinprocessor/example_config.yaml -- tracecore validate exit 0. Clean.
  • module/receiver/ncclfrreceiver/example_config.yaml -- fixed in this PR.

No additional rot under module/.

Test plan

  • tracecore validate was exit 1, now exit 0 against the fixed example_config.yaml.
  • go test -race -count=1 ./receiver/ncclfrreceiver/... green (no receiver source changed; sanity).
  • make validator-recipe green (sibling-example sanity).
  • A+ sweep across module/**/example_config.yaml -- only this file required fixing.
docs(examples): fix module/receiver/ncclfrreceiver/example_config.yaml so it validates against the OCB-assembled tracecore binary. Swap retired stdoutexporter for upstream debug, and update the README's `tracecore collect --config ...` invocation to `./_build/tracecore --config=...` per RFC-0013 PR-A2.

Refs: #458, RFC-0013 PR-A2.

Closes #457.

Sibling cleanup to #458 (closed #454). `module/receiver/ncclfrreceiver/
example_config.yaml` referenced the retired `stdoutexporter`, and the
README invoked the deleted `tracecore collect` subcommand. Both were
retired by RFC-0013 PR-A2 (`stdoutexporter` -> `debug`; `collect`
subcommand removed - OCB binary takes `--config=` directly).

Applies the same recipe as #458 to the receiver example.

Verified:
- `./_build/tracecore validate --config=module/receiver/ncclfrreceiver/example_config.yaml`
  was exit 1 (unknown type stdoutexporter); now exit 0.
- `cd module && go test -race -count=1 ./receiver/ncclfrreceiver/...` green.
- `make validator-recipe` green.
- A+ sweep across `module/**/example_config.yaml`: the two sibling
  examples (patterndetectorprocessor, rankjoinprocessor) already
  validate clean. No additional rot.

Refs: #458, RFC-0013 PR-A2.

Closes #457.

Signed-off-by: Tri Lam <tree@lumalabs.ai>
@trilamsr

trilamsr commented Jun 2, 2026

Copy link
Copy Markdown
Contributor Author

Review: Independent Adversarial Audit

Scope verified:

Testing verified:

  • ./_build/tracecore validate now exit 0 (was exit 1) ✓
  • go test ./receiver/ncclfrreceiver/... green ✓
  • make validator-recipe green ✓

Code quality:

  • RFC-0013 PR-A2 reference anchors the change (README + config comment)
  • Comment accuracy: verbosity: detailed does match old stdoutexporter output per RFC-0013 §4
  • No extraneous changes
  • Release-notes block present and correct

Deferred work:

  • validator-recipe.sh scope gap (module/**/example_config.yaml) documented as out-of-scope per body; follow-up issue should be filed before merge to satisfy file-issues-for-unaddressed policy.

Grade: A — tight, correct, well-tested fix mirroring #458 pattern. Recommend merge once follow-up issue is filed.

@trilamsr trilamsr enabled auto-merge (squash) June 2, 2026 02:51
@trilamsr trilamsr merged commit 1da878a into main Jun 2, 2026
12 checks passed
@trilamsr trilamsr deleted the fix/457-ncclfrreceiver-example-config-cleanup branch June 2, 2026 02:55
trilamsr added a commit that referenced this pull request Jun 2, 2026
…460) (#466)

## Summary

Closes #460. The `exit 0` on `scripts/doc-check.sh` ran unconditionally
whenever `docs/FAILURE-MODES.md` carried no `Test*`/`Fuzz*`/`Benchmark*`
identifiers (its current state on `main` — `grep -c` = 0), silently
bypassing every gate below it. Fix scopes the skip to the Go-test parity
block only (if/else, not `exit`), then surfaces and fixes the dead refs
the gates were supposed to be catching.

## Root cause

Commit a57883f (#13) shipped `doc-check.sh` with one gate — the Go-test
name parity check — so `[ -z "$referenced" ] && exit 0` was correct
then. PRs #28, #56, #115, #131, #144, #149, #195, #234, #241, #443,
#455, #459 (and others) appended gates **below** that line without
recognising they'd become dead code whenever `FAILURE-MODES.md` lost its
`Test*` references. PR #459 worked around the bug by placing its new
YAML gate *above* line 99 and tracked the root cause separately as #460.

## What surfaced

Once `exit 0` was removed, three real issues fired:

1. **Dead `.md` link**: `docs/FOLLOWUPS.md` → `followups/otlphttp.md`.
The shard was never committed to `main`'s ancestry. Folded into the
existing "Shards deleted post-v0.2.0 as fully resolved-via-pivot" prose
block (sibling treatment to M9, M14, M16).
2. **Banned-phrase hits** (3x `production-grade`): reworded in
`docs/cut-criteria.yaml.md` (2x) and
`install/kubernetes/tracecore/README.md` (1x) to falsifiable language.
3. **`docs/getting-started.md` block cap**: 7 fenced bash/sh blocks. The
M6 cap of 5 was set for the quickstart only — `## Install via Helm` and
`## Air-gapped install` are alternate deployment paths that landed
post-M6 and aren't part of the quickstart budget. Rescoped the gate to
count blocks inside the `## Walkthrough` H2 section only (1 block, well
under cap).

## Gate count

Empirically verified via `grep -c '^doc-check: '` on `make doc-check`
output on a clean tree:

| State | Status lines emitted | Gates the early-exit was hiding |
|---|---|---|
| Pre-fix on `main` (post-#459) | 3 (trust-posture, YAML cross-link,
parity-skip) | 14 |
| Post-fix this PR (post-rebase) | 17 | 0 |

The "14 gates hidden" number is invariant across the rebase: it counts
gates placed below the early-exit line. The "3 → 17" total reflects
post-#459 reality on `main`; pre-#459 baseline was "2 → 16" (the figure
originally in this PR body), and #459 itself worked around the bug by
placing its YAML gate above line 99.

## Mutation tests

Each gate below the original early-exit was confirmed to fire post-fix:

| Mutation | Gate expected to fire | Exit code post-mutation | Exit code
post-restore |
|---|---|---|---|
| Inject `[bad](nonexistent-ghost.md)` into `docs/FOLLOWUPS.md` |
markdown link-rot | 1 | 0 |
| Append `blazing-fast` + `rock-solid` to `docs/getting-started.md` |
banned-phrase lint | 1 | 0 |
| Delete `<!-- tested-against: ... -->` from
`docs/integrations/datadog.md` | M6 recipe markers | 1 | 0 |

## Test plan

- [x] `make doc-check` exits 0 on clean tree (re-run post-rebase onto
origin/main; 17 status lines)
- [x] 3 mutation tests above each toggle exit 1 → 0 across mutate /
restore
- [x] Pre-push hooks green: golangci-lint (0 issues), `go vet ./...`,
`go mod verify`, `attribute-namespace-check` (100 attrs, all
documented), `register-lint`, `actionlint`, `zizmor`,
`deprecation-check`, `no-autoupdate-check`
- [x] Rebased onto current `origin/main` (includes #459, #461, #462,
#456); no conflicts; gate count re-verified empirically post-rebase
- [x] No changes to gates above line 99 (the trust-posture callout +
YAML cross-link gate from #459 still run and emit unchanged status
lines)

## Self-grade

**A+** — root cause named in commit body (a57883f #13 with one gate;
gates appended below without exit-path awareness); 3 mutation tests
(success criteria required 1–2); rescoped the getting-started gate to
match M6 intent rather than papering over the surfaced overflow; the `[
-z "$referenced" ]` legitimate skip is preserved via if/else (not `:`
no-op, which would have left the `defined=` / `orphans=` block running
on empty input); gate count corrected empirically post-rebase per
reviewer B feedback.

```release-notes
- fix(ci): `scripts/doc-check.sh` no longer exits 0 at the Go-test parity gate when `docs/FAILURE-MODES.md` carries no `Test*` references. 14 gates below that line (link-rot, banned-phrase, M6 recipe markers, etc.) are now actually enforced on every `make doc-check` invocation. Closes #460.
```

---------

Signed-off-by: Tri Lam <tree@lumalabs.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant