fix(examples): with-telemetry.yaml -> RFC-0013 successor components (#454)

docs/examples/with-telemetry.yaml

@@ -2,51 +2,66 @@
 # If you expose the receiver across a trust boundary, wire the bearer-token or mTLS
 # shape from docs/integrations/multi-cluster.md before deploy.
 #
-# 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]