docs(migration): PR-L — flesh v0.1.x→v0.2.0 guide body

[trilamsr]

Summary

RFC-0013 PR-L — expand docs/migration/v0.1-to-v0.2.md from the PR-179 skeleton (plus the metric-name + chart-values rows landed inline in PR-A2 / #189) into a comprehensive v0.1.x → v0.2.0 cutover guide. Every post-wave-2 landing now has a corresponding operator-facing migration row.

NONE

What landed

Section added / expanded	Source of truth
CLI surface — table covering every removed subcommand (collect, receivers list, debug dump, failure-inject) and removed flag (--log.format=text, --shutdown.drain-budget, --version-short) + their upstream replacements	PR #189 release-notes block + the deleted cmd/tracecore/ tree
Helm chart values — telemetry.listen + telemetry.paths.* → telemetry.metricsListen + telemetry.healthListen + telemetry.healthPath with default-port values	install/kubernetes/tracecore/values.yaml HEAD
Probes — /healthz + /readyz on :8888 → healthcheckextension at :13133/	install/kubernetes/tracecore/templates/daemonset.yaml HEAD
Default pipeline — clockreceiver → stdoutexporter → hostmetrics → debug snippet	values.yaml pipelines: block HEAD
Orphan components table — all 9 (clockreceiver, containerstdout, dcgm, k8sevents, kernelevents, nccl_fr, pyspy, otlphttp, stdoutexporter) mapped to upstream replacement + PR-J recipe	components/receivers/, components/exporters/ directory inventory + RFC-0013 §2 adoption matrix
Self-telemetry metric vocabulary — tracecore_* → otelcol_* for receiver / exporter / queue / component-status / build-info families with per-signal split	upstream OCB instrumentation conventions + internal/integration/ocb_scrape_test.go contract metrics
stdoutexporter failure-rate gap — debugexporter pins otelcol_exporter_send_failed_* at zero; debug-only pipelines lose the signal	upstream debugexporter semantics
Build / CI changes — Makefile, output path (./_build/tracecore), source tree, smoke, image build, release pipeline, version source	Makefile + .goreleaser.yaml + .ko.yaml + workflows HEAD
internal/* package deletion (PR-F, in flight) — per-package public-surface migration map for selftelemetry, runtime/lifecycle, componentstatus, telemetry, pipeline, pipelinebuilder, consumer, fanout	RFC-0013 PR-F scope + internal/ tree inventory
Reproducibility note — 0.1.0-m9-alpha hardcoded in builder-config.yaml dist.version; cross-ref to docs/reproducibility.md workaround	builder-config.yaml HEAD
Verification — adds probe smoke test + tracecore components parity check against the rendered config	new section
Rollback — recipe-toggle path is not available for the deleted set; pin chart + image at v0.1.x	corrects the v0.1.x-era rollback prose

Closes RFC-0013 PR-L. Open follow-ups (PR-I in-repo submodule, PR-J upstream recipes, PR-K in-tree-receiver delete, PR-F internal/* delete) are referenced inline in the guide so the next agent picking up any of them lands the corresponding doc update in the same PR.

Adversarial pre-review notes

• Verified component counts (builder-config.yaml: 6 receivers, 4 exporters, 3 extensions, 4 processors) against awk count of gomod: lines.
• Verified hostmetrics is the default in values.yaml (enabled: true, loadscraper, 1s).
• Verified cmd/tracecore, tools/components-gen, components.yaml all deleted from HEAD (git ls-files returns empty).
• Verified internal/integration/ocb_scrape_test.go is present and asserts the two contract metrics named in the guide.
• Verified the daemonset.yaml probes wire port: health (not port: telemetry) at healthPath.
• Verified no broken markdown links — all 5 outbound links resolve (builder-config.yaml, ocb_scrape_test.go, RFC-0013 §3, RFC-0013 §migration, in-doc anchor).
• One non-blocking observation: install/kubernetes/tracecore/README.md still references /healthz + /readyz on three lines (chart-doc rot from PR-A2 that didn't sweep the README). Out of scope for PR-L; flagging for the next chart-doc sweep.

Test plan

• make doc-check passes (banned-phrase lint, link resolution, test-name parity, all 15 sub-checks green)
• Pre-commit hook (golangci-lint, go vet, go mod verify, DCO + AI trailer) passes
• Pre-push hook (no-autoupdate-check) passes
• CI: chart, ci, install-bench workflows do not gate on this file; only doc-check matters for a docs-only PR

[trilamsr]

Code review

Found 2 issues:

1. The orphan-components table and the closing paragraph point operators at <receiver>.recipe: upstream (lines 67, 69, 70, 82), but no recipe key exists in the chart today. install/kubernetes/tracecore/values.schema.json is additionalProperties: false at the chart root and on every receiver block, so an operator who runs --set receivers.containerstdout.recipe=upstream gets schema-rejected by helm install --dry-run before anything else fires. This is a forward-looking design from RFC-0013 that PR-J will land — the guide should either gate the advice on PR-J landing or reword to describe what operators do in v0.2.0 today (pin chart and image at v0.1.x, wait for PR-J).

tracecore/docs/migration/v0.1-to-v0.2.md

Lines 65 to 83 in acf3767

	|---|---|---|---|
	| `receivers.clockreceiver` | receiver | `hostmetricsreceiver` (loadscraper) | Already the default. Remove the `clockreceiver` block; the chart no-ops if you leave `clockreceiver.enabled: false`. |
	| `receivers.containerstdout` | receiver | `filelogreceiver` + container stanza + `file_storage` extension | Set `containerstdout.recipe: upstream` once PR-J ships; the chart still flips pod `runAsUser=0` and creates the RBAC ClusterRole for `/var/log/pods` access. |
	| `receivers.dcgm` | receiver | `dcgm-exporter` DaemonSet + `prometheusreceiver` | Deploy `dcgm-exporter` via NVIDIA's chart; set `gpu.nvidia.recipe: prometheus` to wire the scrape. |
	| `receivers.k8sevents` | receiver | `k8sobjectsreceiver` + OTTL `k8s.event.hint` transform | Set `k8sevents.recipe: upstream`; the OTTL transform preserves the 11-entry `k8s.event.hint` enum (RFC-0013 §3 contract). |
	| `receivers.kernelevents` | receiver | `journaldreceiver` + `filelogreceiver` (kmsg) + OTTL Xid transform | Set `kernelevents.recipe: upstream`; OTTL transform keeps `kernelevents.xid` attribute populated. |
	| `receivers.nccl_fr` | receiver | In-repo Go submodule via OCB `gomod:` (PR-I) + `replaces: ./module` | No operator action; the receiver ships in `module/receiver/ncclfrreceiver` and OCB pulls it like any upstream module. |
	| `receivers.pyspy` | receiver | Deferred until OTel Profiles GA | Receiver toggle survives until contrib ships `pprofreceiver`. No replacement to wire today. |
	| `exporters.stdoutexporter` | exporter | `debugexporter` (OCB-bundled, chart default) | Replace `exporters.stdoutexporter` with `exporters.debug` in pipelines. The debug exporter writes to pod stdout, same observation channel. |
	| `exporters.otlphttp` (in-tree clone) | exporter | `otlphttpexporter` (OCB-bundled) | Same chart key (`otlphttp`), same field shape — `endpoint`, `compression`, `headers`, `tls.*`, `timeout`, `retry_on_failure`, `sending_queue` pass through to the upstream exporter without translation. |
	To verify what's actually registered in the binary you're running:
	```bash
	./_build/tracecore components
	```
	Until PR-J ships the upstream recipes, the migration path for the in-tree receivers other than `clockreceiver`/`stdoutexporter` is: pin v0.1.x → wait for PR-J → cut over with `<receiver>.recipe: upstream` in one minor.

2. Rollback section recommends pinning image.tag: 0.1.0-m8-alpha and chart appVersion: 0.1.0-m8-alpha, but no v0.1.0-m8-alpha release exists. gh release list shows the only v0.1.x tag is v0.1.0-m1; the chart's current appVersion is 0.1.0-m9-alpha (unreleased, lives only on main). Operators following the guide would helm install --set image.tag=0.1.0-m8-alpha and get ImagePullBackOff. Suggest pointing at v0.1.0-m1 or the actual last published release tag, and either dropping the chart appVersion line (charts are pinned by --version, not appVersion) or naming the matching chart-package version.

tracecore/docs/migration/v0.1-to-v0.2.md

Lines 188 to 190 in acf3767

	## Rollback
	The OCB binary does not bundle the in-tree receivers anymore (`builder-config.yaml` does not list them; OCB regeneration would be required to add them back). Recipe-toggle rollback is not available for the deleted set. If the v0.2.0 deploy fails health checks, pin the chart and image at the prior v0.1.x version (`image.tag: 0.1.0-m8-alpha`, chart `appVersion: 0.1.0-m8-alpha`). No data is mutated on upgrade.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}