diff --git a/docs/examples/with-telemetry.yaml b/docs/examples/with-telemetry.yaml index 6d3ec9f3..eb5253da 100644 --- a/docs/examples/with-telemetry.yaml +++ b/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]