From ae1c2d4c10f4b68c0ee2e5d129f4d04b25d1353f Mon Sep 17 00:00:00 2001
From: Tri Lam <tree@lumalabs.ai>
Date: Mon, 1 Jun 2026 19:24:13 -0700
Subject: [PATCH] fix(examples): with-telemetry.yaml -> RFC-0013 successor
 components

Closes #454.

docs/examples/with-telemetry.yaml referenced the in-tree clockreceiver
and stdoutexporter (retired by RFC-0013 PR-A2 + PR-E) and the legacy
top-level telemetry: block (retired by PR-A2 in favour of the upstream
service/telemetry shape). The OCB-assembled tracecore binary rejected
all three:

  'receivers' unknown type: "clockreceiver"
  'exporters' unknown type: "stdoutexporter"
  '' has invalid keys: telemetry

Swap to the canonical post-pivot shape, matching docs/getting-started.md
and the in-repo Helm chart default:

  - hostmetrics (load scraper @ 1s) replaces clockreceiver.
    telemetrygeneratorreceiver does not exist in opentelemetry-collector-
    contrib (RFC-0013 PR-E, contrib #41687 + #43657 closed not_planned).
  - debug (verbosity: detailed) replaces stdoutexporter.
  - service.telemetry.metrics.readers.pull.exporter.prometheus
    replaces the top-level telemetry: block.
  - healthcheckextension at :13133/ wires liveness + readiness
    (the legacy block's healthz/readyz paths) via service.extensions.

Verify:
  ./_build/tracecore validate --config=docs/examples/with-telemetry.yaml
  -> exit 0 (was exit 1 pre-fix)

A+ sweep noted module/receiver/ncclfrreceiver/example_config.yaml also
references stdoutexporter; filed #457 (out of scope for #454).

Signed-off-by: Tri Lam <tree@lumalabs.ai>
---
 docs/examples/with-telemetry.yaml | 83 ++++++++++++++++++-------------
 1 file changed, 49 insertions(+), 34 deletions(-)

diff --git a/docs/examples/with-telemetry.yaml b/docs/examples/with-telemetry.yaml
index 2f81e5d1..d9d8d024 100644
--- a/docs/examples/with-telemetry.yaml
+++ b/docs/examples/with-telemetry.yaml
@@ -1,48 +1,63 @@
-# Operator-facing example: tracecore with the M2 self-telemetry
-# surface enabled.
+# Operator-facing example: tracecore with the self-telemetry surface
+# (metrics + liveness/readiness) enabled.
 #
 # Save as `tracecore.yaml` and run:
-#     tracecore collect --config=tracecore.yaml
-# then scrape:
+#     ./_build/tracecore --config=tracecore.yaml
+# then scrape and probe:
 #     curl http://localhost:8888/metrics
+#     curl http://localhost:13133/
 #
-# The `telemetry:` block is OPT-IN. Without it tracecore binds no
-# HTTP port - operators in production opt in by setting
-# `telemetry.enabled: true` (or by uncommenting the listen line and
-# changing it to `:8888` to scrape from another node).
+# RFC-0013 (PR-A2 + PR-E) retired the in-tree `clockreceiver` /
+# `stdoutexporter` and the legacy top-level `telemetry:` block. This
+# example tracks the post-pivot shape:
 #
-# RFC-0013 note: `clockreceiver` and `stdoutexporter` below are the
-# v0.0.x in-tree components. At v0.1.0 they map to OCB-bundled
-# equivalents (`telemetrygeneratorreceiver`, `debugexporter`) per
-# RFC-0013 §7, and the `telemetry:` block adopts upstream
-# `service/telemetry` shape with standard `otelcol_*` metric names
-# per RFC-0013 §4.
+#   * Heartbeat source: upstream `hostmetrics` with the `load`
+#     scraper at 1s, matching docs/getting-started.md and the
+#     in-repo Helm chart default. Emits 3 low-cardinality series
+#     `system.cpu.load_average.{1m,5m,15m}`.
+#   * Sink: upstream `debug` exporter (verbosity: detailed).
+#   * Self-telemetry: upstream `service.telemetry.metrics.readers`
+#     drives the Prometheus surface at :8888/metrics with the
+#     standard `otelcol_*` metric names (RFC-0013 §4).
+#   * Liveness/readiness: upstream `healthcheckextension` at
+#     :13133/ (kubelet defaults), opt-in via `service.extensions`.
+#
+# Validated with: ./_build/tracecore validate --config=docs/examples/with-telemetry.yaml
 
 receivers:
-  clockreceiver:
-    interval: 1s
+  hostmetrics:
+    collection_interval: 1s
+    scrapers:
+      load: {}
 
 exporters:
-  stdoutexporter: {}
+  debug:
+    verbosity: detailed
 
-# Self-telemetry surface. The whole block is opt-in: omitting it
-# leaves tracecore binding no HTTP port. As shipped this example
-# enables the surface so a first-run operator gets a working
-# `curl localhost:8888/metrics` — set `enabled: false` (or delete
-# the block) to turn it off again.
-telemetry:
-  enabled: true
-  # Default "localhost:8888" — safe default keeps tracecore from
-  # binding all interfaces. Operators in multi-node setups override
-  # to ":8888" or to a specific interface.
-  listen: localhost:8888
-  paths:
-    metrics: /metrics
-    healthz: /healthz
-    readyz: /readyz
+# Liveness + readiness probes for kubelet / curl. Comment the extension
+# out (and remove it from `service.extensions` below) to skip the
+# health surface; the metrics surface under `service.telemetry` is
+# independent.
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+    path: /
 
 service:
+  extensions: [health_check]
+  # Self-telemetry surface. Tracks the upstream `service/telemetry`
+  # shape (RFC-0013 §4); the legacy top-level `telemetry:` block is
+  # gone. Comment the `telemetry:` stanza out to drop the metrics
+  # listener — the pipelines below continue to run.
+  telemetry:
+    metrics:
+      readers:
+        - pull:
+            exporter:
+              prometheus:
+                host: localhost
+                port: 8888
   pipelines:
     metrics/primary:
-      receivers: [clockreceiver]
-      exporters: [stdoutexporter]
+      receivers: [hostmetrics]
+      exporters: [debug]