feat(monitoring): modulo shared/monitoring/ — metriche CPU/mem, heartbeat agenti, alerter con soglie runtime

Author: leopu00

shared/monitoring/alerter.ts

@@ -0,0 +1,95 @@
+/**
+ * Monitoring — Alerter: soglie, valutazione, alert attivi
+ */
+import type { AlertThreshold, AlertEvent, SystemMetrics } from './types.js';
+
+const thresholds = new Map<string, AlertThreshold>();
+const activeAlerts = new Map<string, AlertEvent>();
+
+/** Registra una soglia di alert */
+export function defineThreshold(threshold: AlertThreshold): void {
+  thresholds.set(threshold.id, threshold);
+}
+
+/** Rimuove una soglia */
+export function removeThreshold(id: string): boolean {
+  activeAlerts.delete(id);
+  return thresholds.delete(id);
+}
+
+/** Lista soglie registrate */
+export function getThresholds(): AlertThreshold[] {
+  return [...thresholds.values()];
+}
+
+/** Valuta le metriche contro le soglie e ritorna nuovi alert */
+export function checkThresholds(metrics: SystemMetrics): AlertEvent[] {
+  const triggered: AlertEvent[] = [];
+
+  for (const t of thresholds.values()) {
+    if (t.metric === 'heartbeat') continue;
+    const current = metrics[t.metric] as number;
+    const fired = evaluate(current, t.operator, t.value);
+
+    if (fired) {
+      const event: AlertEvent = {
+        thresholdId: t.id, metric: t.metric,
+        currentValue: current, thresholdValue: t.value,
+        operator: t.operator, description: t.description,
+        triggeredAt: Date.now(),
+      };
+      activeAlerts.set(t.id, event);
+      triggered.push(event);
+    } else {
+      activeAlerts.delete(t.id);
+    }
+  }
+
+  return triggered;
+}
+
+/** Valuta alert heartbeat (chiamare con tempo dall'ultimo heartbeat in ms) */
+export function checkHeartbeatAlert(agentId: string, elapsedMs: number): AlertEvent | null {
+  for (const t of thresholds.values()) {
+    if (t.metric !== 'heartbeat') continue;
+    if (evaluate(elapsedMs, t.operator, t.value)) {
+      const event: AlertEvent = {
+        thresholdId: t.id, metric: `heartbeat:${agentId}`,
+        currentValue: elapsedMs, thresholdValue: t.value,
+        operator: t.operator, description: `${t.description} (${agentId})`,
+        triggeredAt: Date.now(),
+      };
+      activeAlerts.set(`${t.id}:${agentId}`, event);
+      return event;
+    }
+  }
+  return null;
+}
+
+/** Ritorna tutti gli alert attivi */
+export function getActiveAlerts(): AlertEvent[] {
+  return [...activeAlerts.values()];
+}
+
+/** Rimuove un alert attivo */
+export function clearAlert(thresholdId: string): boolean {
+  return activeAlerts.delete(thresholdId);
+}
+
+/** Rimuove tutti gli alert */
+export function clearAllAlerts(): void {
+  activeAlerts.clear();
+}
+
+/** Reset completo (per test) */
+export function resetAlerter(): void {
+  thresholds.clear();
+  activeAlerts.clear();
+}
+
+function evaluate(current: number, op: string, threshold: number): boolean {
+  if (op === 'gt') return current > threshold;
+  if (op === 'lt') return current < threshold;
+  if (op === 'eq') return current === threshold;
+  return false;
+}

shared/monitoring/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Monitoring — Monitoraggio runtime, heartbeat, alerting
+ */
+
+export type {
+  SystemMetrics, AgentHeartbeat,
+  AlertThreshold, AlertEvent, MonitorConfig,
+} from './types.js';
+export { DEFAULT_MONITOR_CONFIG } from './types.js';
+
+export {
+  configureMonitor, collectMetrics, getMetricsHistory,
+  registerHeartbeat, getAgentStatus, getAllAgentStatuses,
+  checkHeartbeats, removeAgent, resetMonitor,
+} from './monitor.js';
+
+export {
+  defineThreshold, removeThreshold, getThresholds,
+  checkThresholds, checkHeartbeatAlert,
+  getActiveAlerts, clearAlert, clearAllAlerts, resetAlerter,
+} from './alerter.js';

shared/monitoring/monitor.ts

@@ -0,0 +1,94 @@
+/**
+ * Monitoring — Raccolta metriche sistema e heartbeat agenti
+ */
+import os from 'node:os';
+import type { SystemMetrics, AgentHeartbeat, MonitorConfig } from './types.js';
+import { DEFAULT_MONITOR_CONFIG } from './types.js';
+
+const heartbeats = new Map<string, { lastSeen: number; metadata?: Record<string, unknown> }>();
+const metricsHistory: SystemMetrics[] = [];
+let config: Required<MonitorConfig> = { ...DEFAULT_MONITOR_CONFIG };
+
+/** Configura il monitor */
+export function configureMonitor(opts: MonitorConfig): void {
+  config = { ...DEFAULT_MONITOR_CONFIG, ...opts };
+}
+
+/** Raccoglie metriche di sistema correnti */
+export function collectMetrics(): SystemMetrics {
+  const totalMem = os.totalmem();
+  const freeMem = os.freemem();
+  const usedMem = totalMem - freeMem;
+  const cpus = os.cpus();
+  let cpuUsage = 0;
+  if (cpus.length > 0) {
+    const totals = cpus.reduce((acc, c) => {
+      const t = Object.values(c.times).reduce((s, v) => s + v, 0);
+      return { idle: acc.idle + c.times.idle, total: acc.total + t };
+    }, { idle: 0, total: 0 });
+    cpuUsage = Math.round((1 - totals.idle / totals.total) * 10000) / 100;
+  }
+
+  const metrics: SystemMetrics = {
+    cpuUsage,
+    memoryUsedMB: Math.round(usedMem / 1048576),
+    memoryTotalMB: Math.round(totalMem / 1048576),
+    memoryPercent: Math.round((usedMem / totalMem) * 10000) / 100,
+    uptimeSeconds: Math.floor(os.uptime()),
+    loadAvg: os.loadavg() as [number, number, number],
+    timestamp: Date.now(),
+  };
+
+  metricsHistory.push(metrics);
+  while (metricsHistory.length > config.metricsHistorySize) metricsHistory.shift();
+
+  return metrics;
+}
+
+/** Ritorna storico metriche */
+export function getMetricsHistory(): SystemMetrics[] {
+  return [...metricsHistory];
+}
+
+/** Registra heartbeat di un agente */
+export function registerHeartbeat(agentId: string, metadata?: Record<string, unknown>): void {
+  heartbeats.set(agentId, { lastSeen: Date.now(), metadata });
+}
+
+/** Stato di un singolo agente */
+export function getAgentStatus(agentId: string): AgentHeartbeat | null {
+  const hb = heartbeats.get(agentId);
+  if (!hb) return null;
+  return { agentId, lastSeen: hb.lastSeen, status: resolveStatus(hb.lastSeen), metadata: hb.metadata };
+}
+
+/** Stato di tutti gli agenti registrati */
+export function getAllAgentStatuses(): AgentHeartbeat[] {
+  return [...heartbeats.entries()].map(([agentId, hb]) => ({
+    agentId, lastSeen: hb.lastSeen, status: resolveStatus(hb.lastSeen), metadata: hb.metadata,
+  }));
+}
+
+/** Controlla heartbeat e ritorna agenti stale/dead */
+export function checkHeartbeats(): AgentHeartbeat[] {
+  return getAllAgentStatuses().filter(a => a.status !== 'alive');
+}
+
+/** Rimuove un agente dal monitoraggio */
+export function removeAgent(agentId: string): boolean {
+  return heartbeats.delete(agentId);
+}
+
+/** Reset completo (per test) */
+export function resetMonitor(): void {
+  heartbeats.clear();
+  metricsHistory.length = 0;
+  config = { ...DEFAULT_MONITOR_CONFIG };
+}
+
+function resolveStatus(lastSeen: number): 'alive' | 'stale' | 'dead' {
+  const elapsed = Date.now() - lastSeen;
+  if (elapsed > config.heartbeatDeadMs) return 'dead';
+  if (elapsed > config.heartbeatStaleMs) return 'stale';
+  return 'alive';
+}

shared/monitoring/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Monitoring — Tipi per monitoraggio runtime
+ */
+
+/** Metriche di sistema */
+export interface SystemMetrics {
+  cpuUsage: number;
+  memoryUsedMB: number;
+  memoryTotalMB: number;
+  memoryPercent: number;
+  uptimeSeconds: number;
+  loadAvg: [number, number, number];
+  timestamp: number;
+}
+
+/** Heartbeat di un agente */
+export interface AgentHeartbeat {
+  agentId: string;
+  lastSeen: number;
+  status: 'alive' | 'stale' | 'dead';
+  metadata?: Record<string, unknown>;
+}
+
+/** Soglia di alert */
+export interface AlertThreshold {
+  id: string;
+  metric: 'cpuUsage' | 'memoryPercent' | 'heartbeat';
+  operator: 'gt' | 'lt' | 'eq';
+  value: number;
+  description: string;
+}
+
+/** Evento di alert attivo */
+export interface AlertEvent {
+  thresholdId: string;
+  metric: string;
+  currentValue: number;
+  thresholdValue: number;
+  operator: string;
+  description: string;
+  triggeredAt: number;
+}
+
+/** Configurazione monitor */
+export interface MonitorConfig {
+  heartbeatStaleMs?: number;
+  heartbeatDeadMs?: number;
+  metricsHistorySize?: number;
+}
+
+export const DEFAULT_MONITOR_CONFIG: Required<MonitorConfig> = {
+  heartbeatStaleMs: 30_000,
+  heartbeatDeadMs: 120_000,
+  metricsHistorySize: 60,
+};