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

// 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.

5.0 KiB Raw Permalink Blame History