Initial Commit
This commit is contained in:
@@ -0,0 +1,91 @@
|
||||
# OpenSpec Change: network-plugin-monitor
|
||||
|
||||
- **Change ID**: network-plugin-monitor
|
||||
- **Package**: `@suaveplan/network-plugin-monitor` (new)
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
Operating a production mesh network requires visibility into node health, connection quality, message flow, and hierarchy structure. Without monitoring, operators cannot detect degradation, diagnose partitions, or optimize topology. The genesis `opentelemetry` integration provides distributed tracing, but the network layer needs its own domain-specific metrics: peer latency distributions, tier stability, promotion/demotion rates, message routing efficiency, and transport health trends.
|
||||
|
||||
This plugin implements **production monitoring and distributed tracing** for the network layer, integrating with `@suaveplan/opentelemetry` for trace export while maintaining mesh-specific metrics.
|
||||
|
||||
## What changes
|
||||
|
||||
- **ADDED**: `MonitorPlugin` class implementing `NetworkPlugin`.
|
||||
- **ADDED**: `NetworkMonitor` — collects and analyzes metrics across 4 categories:
|
||||
- **Node metrics**: CPU utilization, memory usage, message queue size, plugin count, error rate
|
||||
- **Connection metrics**: latency (min/avg/max/p95), packet loss, bandwidth, connection stability score
|
||||
- **Message metrics**: throughput (messages/sec), size distribution, processing time, routing efficiency
|
||||
- **Hierarchy metrics**: nodes per tier, parent-child ratios, promotion/demotion rates, sibling relationships
|
||||
- **ADDED**: `MetricCollector` — supports 4 metric types: Counter, Gauge, Histogram, Summary. Configurable sampling rates. Push and pull collection modes.
|
||||
- **ADDED**: `AlertEngine` — threshold-based alerting with configurable rules. Emits `monitor:alert` on `NetworkBus` when metrics exceed thresholds.
|
||||
- **ADDED**: `NetworkTracer` — distributed tracing compatible with OpenTelemetry:
|
||||
- Trace ID propagation across mesh hops via message headers
|
||||
- Span creation for operations crossing multiple nodes
|
||||
- Context carriers for different transport types
|
||||
- Sampling strategies: probabilistic, rate-limited, error-based, priority-based
|
||||
- Clock skew detection and correction between peers
|
||||
- **ADDED**: `HistoricalDataStore` — maintains metric history with configurable retention policies. Supports rollup and aggregation for long-term analysis.
|
||||
- **ADDED**: `AdaptiveSampler` — reduces sampling rate under high metric volume to prevent monitoring overhead from degrading network performance.
|
||||
- **ADDED**: `NETWORK_MON_CODES` — frozen error registry.
|
||||
|
||||
## Metric example
|
||||
|
||||
```typescript
|
||||
// Node metric
|
||||
monitor.recordNodeMetric(peerId, 'cpu', 0.45);
|
||||
|
||||
// Connection metric
|
||||
monitor.recordConnectionMetric(sourceId, targetId, 'latency', 42);
|
||||
|
||||
// Message metric
|
||||
monitor.recordMessageMetric('registry:update', 'processingTime', 3.2);
|
||||
|
||||
// Hierarchy metric
|
||||
monitor.recordHierarchyMetric('tier0', 'nodeCount', 3);
|
||||
```
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Visual dashboards → external tools (Grafana, etc.) consume exported metrics.
|
||||
- Log aggregation → `network-plugin-audit-mesh` handles signed log chains.
|
||||
- Alert delivery (email, SMS) → external alerting system consumes `monitor:alert` bus events.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This derives from `docs/old-network-planning/PHASE_8.md` §Monitoring and Tracing.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| Metric types (Counter, Gauge, Histogram, Summary) | `PHASE_8.md` §Metric Types | verbatim |
|
||||
| Metric categories (node, connection, message, hierarchy) | `PHASE_8.md` §Metric Categories | verbatim |
|
||||
| Distributed tracing | `PHASE_8.md` §NetworkTracer | reworded; OpenTelemetry compatible |
|
||||
| Sampling strategies | `PHASE_8.md` §Sampling Strategies | verbatim: 4 strategies |
|
||||
| Alerting | `PHASE_8.md` §Alerting | reworded; bus-based |
|
||||
| Adaptive sampling | `PHASE_8.md` §High-Volume Monitoring | reworded |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
| Requirement | Justification |
|
||||
|---|---|
|
||||
| Clock skew detection | Required for accurate cross-node span timing |
|
||||
| Historical data store | Required for trend analysis and degradation detection |
|
||||
| Push and pull modes | Required for integration with different monitoring backends |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/monitor/monitor.spec-conformance.test.ts` — pins metric collection, categorization, aggregation.
|
||||
- `src/collector/collector.spec-conformance.test.ts` — pins 4 metric types, sampling, push/pull.
|
||||
- `src/alert/alert.spec-conformance.test.ts` — pins threshold rules, bus emission, suppression.
|
||||
- `src/tracer/tracer.spec-conformance.test.ts` — pins trace propagation, span creation, sampling.
|
||||
- `src/history/history.spec-conformance.test.ts` — pins retention, rollup, aggregation.
|
||||
- `src/sampler/sampler.spec-conformance.test.ts` — pins adaptive rate reduction under load.
|
||||
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
- `tests/dep-graph.test.ts` — pins no direct import of transport or webrtc packages.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only. Monitoring is opt-in; metrics are collected only when the plugin is installed.
|
||||
84
openspec/archive/2026-05-04-network-plugin-monitor/tasks.md
Normal file
84
openspec/archive/2026-05-04-network-plugin-monitor/tasks.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Tasks — network-plugin-monitor
|
||||
|
||||
> Blocked on: `network-core`, `network-plugin-registry`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-monitor/` with `package.json` (`@suaveplan/network-plugin-monitor@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/opentelemetry`, `@suaveplan/timing`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/metric.types.ts` — `Metric`, `MetricType`, `MetricCategory`, `MetricValue`.
|
||||
- [x] 2.2 `src/types/alert.types.ts` — `AlertRule`, `AlertSeverity`, `AlertState`.
|
||||
- [x] 2.3 `src/types/trace.types.ts` — `NetworkTrace`, `NetworkSpan`, `TraceContext`.
|
||||
- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_MON", [...])`.
|
||||
|
||||
## 3. Network monitor
|
||||
|
||||
- [x] 3.1 `src/monitor/network-monitor.ts` — `NetworkMonitor`.
|
||||
- [x] 3.2 4 metric categories: node, connection, message, hierarchy.
|
||||
- [x] 3.3 `recordNodeMetric(peerId, name, value)`, `recordConnectionMetric(source, target, name, value)`, etc.
|
||||
- [x] 3.4 Statistical analysis: min, max, avg, p50, p95, p99.
|
||||
|
||||
## 4. Metric collector
|
||||
|
||||
- [x] 4.1 `src/collector/metric-collector.ts` — `MetricCollector`.
|
||||
- [x] 4.2 4 metric types: Counter, Gauge, Histogram, Summary.
|
||||
- [x] 4.3 Configurable sampling rates.
|
||||
- [x] 4.4 Push and pull collection modes.
|
||||
|
||||
## 5. Alert engine
|
||||
|
||||
- [x] 5.1 `src/alert/alert-engine.ts` — `AlertEngine`.
|
||||
- [x] 5.2 Threshold-based rules with configurable comparison (>, <, ==, !=).
|
||||
- [x] 5.3 Emits `monitor:alert` on bus with severity.
|
||||
- [x] 5.4 Alert suppression (cooldown between repeat alerts).
|
||||
|
||||
## 6. Network tracer
|
||||
|
||||
- [x] 6.1 `src/tracer/network-tracer.ts` — `NetworkTracer`.
|
||||
- [x] 6.2 OpenTelemetry compatible API.
|
||||
- [x] 6.3 Trace ID propagation via message headers.
|
||||
- [x] 6.4 Span creation for cross-node operations.
|
||||
- [x] 6.5 Sampling: probabilistic, rate-limited, error-based, priority-based.
|
||||
- [x] 6.6 Clock skew detection and correction.
|
||||
|
||||
## 7. Historical data store
|
||||
|
||||
- [x] 7.1 `src/history/historical-data-store.ts` — `HistoricalDataStore`.
|
||||
- [x] 7.2 Configurable retention policies (time-based, count-based).
|
||||
- [x] 7.3 Rollup and aggregation for long-term storage.
|
||||
|
||||
## 8. Adaptive sampler
|
||||
|
||||
- [x] 8.1 `src/sampler/adaptive-sampler.ts` — `AdaptiveSampler`.
|
||||
- [x] 8.2 Reduces sampling rate when metric volume exceeds threshold.
|
||||
- [x] 8.3 Restores full sampling when volume decreases.
|
||||
|
||||
## 9. Plugin wrapper
|
||||
|
||||
- [x] 9.1 `src/plugin/monitor-plugin.ts` — `MonitorPlugin` implements `NetworkPlugin`.
|
||||
- [x] 9.2 Subscribes to bus events and converts them to metrics.
|
||||
- [x] 9.3 Installs monitor, collector, alert engine, tracer on `install()`.
|
||||
|
||||
## 10. Spec
|
||||
|
||||
- [x] 10.1 Update `openspec/specs/network/spec.md` with `NET-44`.
|
||||
|
||||
## 11. Conformance tests
|
||||
|
||||
- [x] 11.1 `src/monitor/monitor.spec-conformance.test.ts` — collection, categories, aggregation.
|
||||
- [x] 11.2 `src/collector/collector.spec-conformance.test.ts` — 4 types, sampling, push/pull.
|
||||
- [x] 11.3 `src/alert/alert.spec-conformance.test.ts` — thresholds, bus emission, suppression.
|
||||
- [x] 11.4 `src/tracer/tracer.spec-conformance.test.ts` — propagation, spans, sampling.
|
||||
- [x] 11.5 `src/history/history.spec-conformance.test.ts` — retention, rollup, aggregation.
|
||||
- [x] 11.6 `src/sampler/sampler.spec-conformance.test.ts` — adaptive reduction, restoration.
|
||||
- [x] 11.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 12. Verify
|
||||
|
||||
- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-monitor` green.
|
||||
- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-monitor` 100/100/100/100.
|
||||
- [x] 12.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-monitor` PASS.
|
||||
Reference in New Issue
Block a user