93 lines
4.0 KiB
Markdown
93 lines
4.0 KiB
Markdown
# Tasks: enterprise-network-observability
|
|
|
|
**Change ID**: enterprise-network-observability
|
|
**Package**: `@suaveplan/network-observability`
|
|
**Target path**: `universal/network/network-observability`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/timing`
|
|
|
|
---
|
|
|
|
## 1. Scaffold
|
|
|
|
- [x] Create `universal/network/network-observability/` with `src/`, `tests/`, and all feature subdirectories.
|
|
- [x] Write `package.json` at version `0.1.0`: `"sideEffects": false`, exports map, deps per `proposal.md`.
|
|
- [x] Write `tsconfig.json`, `vitest.config.ts`, scripts.
|
|
|
|
---
|
|
|
|
## 2. Types and error codes
|
|
|
|
- [x] Define all public types in `src/types/common.ts`: `NetworkSnapshot`, `RttMetrics`, `BandwidthMetrics`, `PacketLossMetrics`, `NetworkHealthScore`, `HealthFactor`, `NetworkMonitorOptions`, `NetworkThresholds`, `NetworkEvent`, `NetworkSpanAttributes`.
|
|
- [x] Write `src/types/common.md` (≥200 words, simple + advanced examples).
|
|
- [x] Define error codes in `src/error-codes.ts`.
|
|
- [x] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
|
|
|
|
---
|
|
|
|
## 3. RTT metrics (`src/metrics/rtt.ts`)
|
|
|
|
- [x] Implement `measureRtt(url: string, samples?: number, signal?: AbortSignal): Promise<RttMetrics>`:
|
|
- Fire `samples` (default 5) HTTP HEAD or WebSocket ping probes in sequence.
|
|
- Compute min/max/avg/p50/p95/p99 over results.
|
|
- [x] Write `rtt.test.ts` + `rtt.md`.
|
|
|
|
---
|
|
|
|
## 4. Bandwidth metrics (`src/metrics/bandwidth.ts`)
|
|
|
|
- [x] Implement `measureBandwidth(url: string, signal?: AbortSignal): Promise<BandwidthMetrics>`:
|
|
- Download a known-size payload; compute bytes / elapsed time.
|
|
- [x] Write `bandwidth.test.ts` + `bandwidth.md`.
|
|
|
|
---
|
|
|
|
## 5. Health scoring (`src/core/health/`)
|
|
|
|
- [x] Implement `computeHealthScore(snapshot: Partial<NetworkSnapshot>, thresholds?: NetworkThresholds): NetworkHealthScore`:
|
|
- RTT factor (40%): 100 if < 50ms, linear decay to 0 at 500ms.
|
|
- Packet loss factor (35%): 100 if 0%, linear decay to 0 at 10%.
|
|
- Bandwidth factor (25%): 100 if > 10Mbps, linear decay to 0 at 0.
|
|
- Weighted sum = score; grade from score: 80+ excellent, 60+ good, 40+ fair, 20+ poor, <20 critical.
|
|
- [x] Write `health.test.ts` (≤500 lines): known inputs produce expected scores and grades.
|
|
- [x] Write `health.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 6. Trace context propagation (`src/tracing/`)
|
|
|
|
- [x] Implement `injectTraceContext(headers)` — calls `context.with(...)` + OTel `TextMapPropagator.inject`.
|
|
- [x] Implement `extractTraceContext(headers)` — calls OTel `TextMapPropagator.extract`.
|
|
- [x] Implement `withNetworkSpan(name, fn, attributes?)` — wraps `fn` in a span with network attributes.
|
|
- [x] Write `propagation.test.ts` + `propagation.md`.
|
|
|
|
---
|
|
|
|
## 7. Network monitor (`src/core/monitor/`)
|
|
|
|
- [x] Implement `createNetworkMonitor(options?)`:
|
|
- On `start()`, begin measurement loop using `@suaveplan/timing` interval timer.
|
|
- Each iteration: call RTT probe, compute health score, push to history ring buffer.
|
|
- Emit `snapshot` event on each measurement.
|
|
- Check against thresholds; emit `threshold-breach` on violation, `recovery` on recovery.
|
|
- OTel: gauge `net.rtt_ms`, gauge `net.health_score`, gauge `net.packet_loss`.
|
|
- [x] Implement `monitor.snapshot()`, `monitor.history(limit?)`, `monitor.on(event, handler)`.
|
|
- [x] Write `monitor.test.ts` (≤500 lines): start/stop, snapshot, threshold breach + recovery event.
|
|
- [x] Write `monitor.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 8. Property-based tests (`tests/property.test.ts`)
|
|
|
|
- [x] Health score monotonicity: increasing RTT (all else equal) never increases the score.
|
|
- [x] Grade ordering: `score >= 80 ⇒ excellent`, grade boundaries consistent.
|
|
|
|
---
|
|
|
|
## 9. Docs and verify
|
|
|
|
- [x] All per-file `.md` files per layout in `proposal.md`.
|
|
- [x] `universal/network/network-observability/README.md`.
|
|
- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-observability` — all green, 100% coverage.
|
|
- [x] `bun scripts/publish.ts --package @suaveplan/network-observability`.
|
|
- [x] Update `CLAUDE.md`. Archive change folder.
|