92 lines
5.0 KiB
Markdown
92 lines
5.0 KiB
Markdown
# 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.
|