Land the shared peer contracts: types, error mapping, transport trait, fake transport and fixtures, registry/proxy/health skeletons, the AppState.peers and Config.peers seams, the ping and peers route stubs, and unit plus integration tests. No loops, no network, feature off by default.
44 lines
2.8 KiB
Markdown
44 lines
2.8 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).
|
|
- 2026-10-19 (A0): contract stubs landed. `PeerRegistry::snapshot()` returns `PeerStatus` sorted by name (jiff timestamps, `since: None` until a check), `AppState.peers` is `None` when the feature is off, and `testing::static_registry` renders fixed snapshots for metric tests.
|