Files
skyg-linux-tracker/plan/phase-5-consolidator/ws-e-telemetry.md
T
2026-10-19 16:43:35 -04:00

43 lines
2.5 KiB
Markdown

# WS-E: Telemetry
Part of [Phase 5: Consolidator](README.md). Contracts: [contracts.md](contracts.md) sections 3 and 8.
| Field | Value |
|---|---|
| Status | Not started |
| Owner | |
| Depends on | B (registry). In practice: A0 for compiling; read the snapshot from `static_registry` / `registry_with` until B lands |
| Blocks | F; [WS-T](ws-t-tests.md) goes green at the end of E |
| Can start when | A0 is merged |
| Owned files | `src/telemetry/metrics_export.rs`, `src/telemetry/mod.rs` |
| Do not touch | `src/peers/**` (A, B, C), `src/api/**`, `src/mcp/**`, `src/state.rs`, `src/server.rs`, `src/main.rs`, `Cargo.toml` (B; if a new telemetry dependency is truly needed, ask B and log it), `nix/**`, `dev/otelcol.yaml` (E may add peer series examples only if needed, note in Log), `docs/**` |
Shared-file seams: telemetry reads `state.peers` (the field exists from A0, set by B in `serve()`); E does not edit `state.rs`/`main.rs`. `spawn_exporters(state)` already receives `AppState`, so no signature change is expected. `inject_traceparent()` (E2) is exported from `telemetry/mod.rs` and called by `src/peers/proxy.rs`/client via `ProxyOpts.traceparent` (contracts section 8); until E2 lands `ProxyOpts.traceparent` is simply `None`.
## Goal
Peer health in OTel, peer calls in traces.
## Tasks
- **E1** observable gauges (f64) fed from the registry snapshot, so removed peers vanish (G11); no polling of peers by the exporter, it reads the registry. Metric table in D10 (names and attributes frozen in contracts section 8).
- **E2** outbound client spans with `peer.name`; inject `traceparent` into peer requests.
## Inputs
- Contracts section 8 (metric names, attributes, units) and 3 (`snapshot`); decisions D10.
- Fakes: `static_registry(Vec<PeerStatus>)` to feed the gauges; `FakeTransport` call records to assert `traceparent` injection.
## Done when
Metrics test with the fake registry; with `otel.enabled` and no peers nothing new is exported; `devenv up` collector shows `peer.up` series for two peers and drops one after `peer remove`. (Peers are declarative, so "peer remove" means removing the entry from config and sending SIGHUP; see D1.)
## Handoff
- Working gauges and `inject_traceparent` for WS-B/C wiring and WS-F's docs.
- Signal to WS-T and WS-F: with E, B, C, D merged the VM test should pass; F2 then promotes it. E also unlocks adding the `peer.api.auth_ok = 0` check from T4 if wanted.
## Log
- 2026-10-19: Split from the single phase plan 2026-10-19. Note added that "peer remove" in the collector check means removal from config plus SIGHUP (D1).