@ceon-oy/monitor-sdk 1.3.0 → 1.4.2

package/README.md

@@ -1,6 +1,6 @@
 # Ceon Monitor SDK
 
-Lightweight client SDK for integrating with the Ceon Monitor service. Provides error reporting, technology tracking, vulnerability auditing, and security event monitoring.
+Lightweight client SDK for integrating with the Ceon Monitor service. Provides error reporting, technology tracking, vulnerability auditing, system metrics collection (CPU, RAM, disk), and security event monitoring.
 
 ## Table of Contents
 
@@ -12,6 +12,7 @@ Lightweight client SDK for integrating with the Ceon Monitor service. Provides e
   - [Technology Tracking](#technology-tracking)
   - [Vulnerability Auditing](#vulnerability-auditing)
   - [SDK-Based Health Checks](#sdk-based-health-checks)
+  - [System Metrics](#system-metrics)
   - [Security Events](#security-events)
 - [Framework Examples](#framework-examples)
   - [Express.js](#expressjs)
@@ -490,6 +491,75 @@ const results = [
 await monitor.submitHealthResults(results);
 ```
 
+### System Metrics
+
+The SDK automatically collects and reports server resource usage — CPU, RAM, and disk — to Ceon Monitor. No SDK configuration flag is needed; the feature activates based on the project settings configured in the Ceon Monitor dashboard.
+
+#### How It Works
+
+When the `MonitorClient` is created, it fetches your project settings from the server. If the project has **Enable Metric Collection** turned on, the SDK:
+
+1. Reads `metricsIntervalSeconds` from project settings (configured in the dashboard)
+2. Reads `metricsDiskPaths` from project settings (e.g. `["/", "/data"]`)
+3. Starts collecting metrics at that interval automatically
+4. POSTs metrics to the server — no manual calls needed
+
+#### What Is Collected
+
+| Metric | Method | Notes |
+|--------|--------|-------|
+| CPU usage % | Dual `os.cpus()` sample with 500 ms gap | Accurate active-cycle average |
+| RAM total | `os.totalmem()` | Bytes |
+| RAM used | `os.totalmem() - os.freemem()` | Bytes |
+| RAM % | `usedMemory / totalMemory * 100` | |
+| Disk total / used / free per path | `fs.statfs(path)` | Node.js 18.15+ built-in, zero external deps |
+
+Hostname is automatically set via `os.hostname()` and included with every report.
+
+#### Enable in Dashboard
+
+1. Open the **Ceon Monitor** dashboard
+2. Go to **Projects** and click **Edit** on your project
+3. Enable the **System Metrics** widget
+4. Click **Enable Metric Collection**
+5. Set the collection interval (e.g. every 60 seconds)
+6. Add disk paths to monitor (e.g. `/` for root, `/data` for a data volume)
+7. Configure CPU / RAM / disk alert thresholds
+8. Save
+
+The SDK will pick up the new settings on its next startup.
+
+#### Notifications
+
+When a metric exceeds a configured threshold, Ceon Monitor sends a `SYSTEM_METRIC_CRITICAL` notification to any user who has subscribed to **System Metric Alerts** for that project. Subscribe in **Settings → Subscriptions**.
+
+#### Node.js Version Requirement
+
+`fs.statfs()` (used for disk monitoring) requires **Node.js 18.15 or later**. No external packages are needed.
+
+#### Manual Metric Submission
+
+You can also submit a metric reading manually:
+
+```typescript
+await monitor.submitSystemMetric({
+  hostname: os.hostname(),
+  cpuPercent: 72.5,
+  memoryTotal: 8 * 1024 ** 3,   // 8 GB in bytes
+  memoryUsed:  5 * 1024 ** 3,   // 5 GB in bytes
+  memoryPercent: 62.5,
+  disks: [
+    {
+      path: '/',
+      total: 100 * 1024 ** 3,   // 100 GB
+      used:   60 * 1024 ** 3,   // 60 GB
+      free:   40 * 1024 ** 3,   // 40 GB
+      usedPercent: 60,
+    },
+  ],
+});
+```
+
 ### Security Events
 
 #### Report Security Event
@@ -1092,6 +1162,10 @@ Runs npm audit and sends results to the server.
 
 Runs npm audit on all directories configured in `auditPaths` and returns a combined summary.
 
+#### `submitSystemMetric(metric: SystemMetric): Promise<void>`
+
+Manually submits a system metric reading. Under normal usage this is called automatically by the SDK's internal collection loop — use this only if you need custom collection logic.
+
 #### `flush(): Promise<void>`
 
 Immediately sends all queued errors.
@@ -1160,6 +1234,23 @@ interface AuditPath {
   environment: string; // Environment label (e.g., 'server', 'client')
 }
 
+interface DiskMetric {
+  path: string;        // Mount path (e.g. '/', '/data')
+  total: number;       // Total bytes
+  used: number;        // Used bytes
+  free: number;        // Free bytes
+  usedPercent: number; // 0–100
+}
+
+interface SystemMetric {
+  hostname: string;
+  cpuPercent: number;
+  memoryTotal: number;
+  memoryUsed: number;
+  memoryPercent: number;
+  disks: DiskMetric[];
+}
+
 interface MultiAuditSummary {
   results: Array<{
     environment: string;

package/dist/index.d.mts

@@ -166,6 +166,7 @@ interface SdkHealthEndpoint {
     intervalMs: number;
     timeoutMs: number;
     expectedStatus: number;
+    allowInsecureTls?: boolean;
 }
 interface SdkHealthResult {
     endpointId: string;
@@ -231,6 +232,7 @@ declare class MonitorClient {
     private sdkErrorsInCurrentWindow;
     private sdkErrorWindowResetTimer;
     private metricsCollectionTimer;
+    private metricsSettingsCheckTimer;
     constructor(config: MonitorClientConfig);
     /**
      * Security: Validate and sanitize metadata to prevent oversized payloads
@@ -304,6 +306,12 @@ declare class MonitorClient {
      * Fetch with timeout to prevent hanging requests
      */
     private fetchWithTimeout;
+    /**
+     * Perform an HTTPS request with TLS certificate verification disabled.
+     * Used for health checks on servers with self-signed certificates.
+     * Uses Node.js built-in `https` module — works reliably in bundled environments.
+     */
+    private fetchInsecureHttps;
     private sendSingle;
     private sendBatch;
     private startFlushTimer;
@@ -491,6 +499,7 @@ declare class MonitorClient {
      * Collects CPU, RAM, and disk usage using built-in Node.js modules.
      */
     setupSystemMetricsCollection(): Promise<void>;
+    private startMetricsCollection;
     private stopMetricsCollection;
     /**
      * Collect system metrics (CPU, RAM, disk) using built-in Node.js modules

package/dist/index.d.ts

@@ -166,6 +166,7 @@ interface SdkHealthEndpoint {
     intervalMs: number;
     timeoutMs: number;
     expectedStatus: number;
+    allowInsecureTls?: boolean;
 }
 interface SdkHealthResult {
     endpointId: string;
@@ -231,6 +232,7 @@ declare class MonitorClient {
     private sdkErrorsInCurrentWindow;
     private sdkErrorWindowResetTimer;
     private metricsCollectionTimer;
+    private metricsSettingsCheckTimer;
     constructor(config: MonitorClientConfig);
     /**
      * Security: Validate and sanitize metadata to prevent oversized payloads
@@ -304,6 +306,12 @@ declare class MonitorClient {
      * Fetch with timeout to prevent hanging requests
      */
     private fetchWithTimeout;
+    /**
+     * Perform an HTTPS request with TLS certificate verification disabled.
+     * Used for health checks on servers with self-signed certificates.
+     * Uses Node.js built-in `https` module — works reliably in bundled environments.
+     */
+    private fetchInsecureHttps;
     private sendSingle;
     private sendBatch;
     private startFlushTimer;
@@ -491,6 +499,7 @@ declare class MonitorClient {
      * Collects CPU, RAM, and disk usage using built-in Node.js modules.
      */
     setupSystemMetricsCollection(): Promise<void>;
+    private startMetricsCollection;
     private stopMetricsCollection;
     /**
      * Collect system metrics (CPU, RAM, disk) using built-in Node.js modules

package/dist/index.js

@@ -101,6 +101,7 @@ var MonitorClient = class {
     this.sdkErrorWindowResetTimer = null;
     // System metrics collection (on-premise only, opt-in)
     this.metricsCollectionTimer = null;
+    this.metricsSettingsCheckTimer = null;
     if (!config.apiKey || config.apiKey.trim().length === 0) {
       throw new Error("[MonitorClient] API key is required");
     }
@@ -543,6 +544,45 @@ var MonitorClient = class {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * Perform an HTTPS request with TLS certificate verification disabled.
+   * Used for health checks on servers with self-signed certificates.
+   * Uses Node.js built-in `https` module — works reliably in bundled environments.
+   */
+  async fetchInsecureHttps(url, options, timeoutMs) {
+    const https = await import("https");
+    const parsed = new URL(url);
+    return new Promise((resolve, reject) => {
+      let req;
+      const timeoutId = setTimeout(() => {
+        req?.destroy();
+        reject(new Error(`Request timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+      req = https.request(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || 443,
+          path: parsed.pathname + parsed.search,
+          method: options.method || "GET",
+          headers: options.headers,
+          rejectUnauthorized: false
+        },
+        (res) => {
+          clearTimeout(timeoutId);
+          res.resume();
+          resolve({ status: res.statusCode || 0 });
+        }
+      );
+      req.on("error", (err) => {
+        clearTimeout(timeoutId);
+        reject(err);
+      });
+      if (options.body) {
+        req.write(options.body);
+      }
+      req.end();
+    });
+  }
   async sendSingle(error) {
     const response = await this.fetchWithTimeout(`${this.endpoint}/api/v1/errors`, {
       method: "POST",
@@ -1347,11 +1387,7 @@ var MonitorClient = class {
           "Content-Type": "application/json"
         };
       }
-      const response = await this.fetchWithTimeout(
-        endpoint.url,
-        requestOptions,
-        endpoint.timeoutMs
-      );
+      const response = endpoint.allowInsecureTls && endpoint.url.startsWith("https") ? await this.fetchInsecureHttps(endpoint.url, requestOptions, endpoint.timeoutMs) : await this.fetchWithTimeout(endpoint.url, requestOptions, endpoint.timeoutMs);
       const responseTimeMs = Date.now() - startTime;
       const statusCode = response.status;
       let status;
@@ -1487,16 +1523,33 @@ var MonitorClient = class {
   async setupSystemMetricsCollection() {
     const settings = await this.fetchProjectSettings();
     if (!settings?.metricsEnabled) {
+      this.metricsSettingsCheckTimer = setInterval(() => {
+        this.fetchProjectSettings().then((latestSettings) => {
+          if (latestSettings?.metricsEnabled) {
+            clearInterval(this.metricsSettingsCheckTimer);
+            this.metricsSettingsCheckTimer = null;
+            this.startMetricsCollection(latestSettings);
+          }
+        }).catch(() => {
+        });
+      }, 3e5);
       return;
     }
-    const intervalMs = Math.max(3e4, (settings.metricsIntervalSeconds ?? 60) * 1e3);
-    const diskPaths = settings.metricsDiskPaths ?? ["/"];
-    console.log(`[MonitorClient] System metrics collection enabled (every ${intervalMs / 1e3}s, paths: ${diskPaths.join(", ")})`);
-    this.collectAndSubmitMetrics(diskPaths).catch((err) => {
+    this.startMetricsCollection(settings);
+  }
+  startMetricsCollection(settings) {
+    const intervalMs = Math.max(3e4, (settings.metricsIntervalSeconds ?? 3600) * 1e3);
+    console.log(`[MonitorClient] System metrics collection enabled (every ${intervalMs / 1e3}s)`);
+    const initialDiskPaths = settings.metricsDiskPaths ?? ["/"];
+    this.collectAndSubmitMetrics(initialDiskPaths).catch((err) => {
       this.reportError("SYSTEM_METRICS", "Initial system metrics collection failed", err);
     });
     this.metricsCollectionTimer = setInterval(() => {
-      this.collectAndSubmitMetrics(diskPaths).catch((err) => {
+      this.fetchProjectSettings().then((latestSettings) => {
+        if (!latestSettings?.metricsEnabled) return;
+        const diskPaths = latestSettings.metricsDiskPaths ?? ["/"];
+        return this.collectAndSubmitMetrics(diskPaths);
+      }).catch((err) => {
         this.reportError("SYSTEM_METRICS", "Scheduled system metrics collection failed", err);
       });
     }, intervalMs);
@@ -1506,6 +1559,10 @@ var MonitorClient = class {
       clearInterval(this.metricsCollectionTimer);
       this.metricsCollectionTimer = null;
     }
+    if (this.metricsSettingsCheckTimer) {
+      clearInterval(this.metricsSettingsCheckTimer);
+      this.metricsSettingsCheckTimer = null;
+    }
   }
   /**
    * Collect system metrics (CPU, RAM, disk) using built-in Node.js modules

package/dist/index.mjs

@@ -65,6 +65,7 @@ var MonitorClient = class {
     this.sdkErrorWindowResetTimer = null;
     // System metrics collection (on-premise only, opt-in)
     this.metricsCollectionTimer = null;
+    this.metricsSettingsCheckTimer = null;
     if (!config.apiKey || config.apiKey.trim().length === 0) {
       throw new Error("[MonitorClient] API key is required");
     }
@@ -507,6 +508,45 @@ var MonitorClient = class {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * Perform an HTTPS request with TLS certificate verification disabled.
+   * Used for health checks on servers with self-signed certificates.
+   * Uses Node.js built-in `https` module — works reliably in bundled environments.
+   */
+  async fetchInsecureHttps(url, options, timeoutMs) {
+    const https = await import("https");
+    const parsed = new URL(url);
+    return new Promise((resolve, reject) => {
+      let req;
+      const timeoutId = setTimeout(() => {
+        req?.destroy();
+        reject(new Error(`Request timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+      req = https.request(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || 443,
+          path: parsed.pathname + parsed.search,
+          method: options.method || "GET",
+          headers: options.headers,
+          rejectUnauthorized: false
+        },
+        (res) => {
+          clearTimeout(timeoutId);
+          res.resume();
+          resolve({ status: res.statusCode || 0 });
+        }
+      );
+      req.on("error", (err) => {
+        clearTimeout(timeoutId);
+        reject(err);
+      });
+      if (options.body) {
+        req.write(options.body);
+      }
+      req.end();
+    });
+  }
   async sendSingle(error) {
     const response = await this.fetchWithTimeout(`${this.endpoint}/api/v1/errors`, {
       method: "POST",
@@ -1311,11 +1351,7 @@ var MonitorClient = class {
           "Content-Type": "application/json"
         };
       }
-      const response = await this.fetchWithTimeout(
-        endpoint.url,
-        requestOptions,
-        endpoint.timeoutMs
-      );
+      const response = endpoint.allowInsecureTls && endpoint.url.startsWith("https") ? await this.fetchInsecureHttps(endpoint.url, requestOptions, endpoint.timeoutMs) : await this.fetchWithTimeout(endpoint.url, requestOptions, endpoint.timeoutMs);
       const responseTimeMs = Date.now() - startTime;
       const statusCode = response.status;
       let status;
@@ -1451,16 +1487,33 @@ var MonitorClient = class {
   async setupSystemMetricsCollection() {
     const settings = await this.fetchProjectSettings();
     if (!settings?.metricsEnabled) {
+      this.metricsSettingsCheckTimer = setInterval(() => {
+        this.fetchProjectSettings().then((latestSettings) => {
+          if (latestSettings?.metricsEnabled) {
+            clearInterval(this.metricsSettingsCheckTimer);
+            this.metricsSettingsCheckTimer = null;
+            this.startMetricsCollection(latestSettings);
+          }
+        }).catch(() => {
+        });
+      }, 3e5);
       return;
     }
-    const intervalMs = Math.max(3e4, (settings.metricsIntervalSeconds ?? 60) * 1e3);
-    const diskPaths = settings.metricsDiskPaths ?? ["/"];
-    console.log(`[MonitorClient] System metrics collection enabled (every ${intervalMs / 1e3}s, paths: ${diskPaths.join(", ")})`);
-    this.collectAndSubmitMetrics(diskPaths).catch((err) => {
+    this.startMetricsCollection(settings);
+  }
+  startMetricsCollection(settings) {
+    const intervalMs = Math.max(3e4, (settings.metricsIntervalSeconds ?? 3600) * 1e3);
+    console.log(`[MonitorClient] System metrics collection enabled (every ${intervalMs / 1e3}s)`);
+    const initialDiskPaths = settings.metricsDiskPaths ?? ["/"];
+    this.collectAndSubmitMetrics(initialDiskPaths).catch((err) => {
       this.reportError("SYSTEM_METRICS", "Initial system metrics collection failed", err);
     });
     this.metricsCollectionTimer = setInterval(() => {
-      this.collectAndSubmitMetrics(diskPaths).catch((err) => {
+      this.fetchProjectSettings().then((latestSettings) => {
+        if (!latestSettings?.metricsEnabled) return;
+        const diskPaths = latestSettings.metricsDiskPaths ?? ["/"];
+        return this.collectAndSubmitMetrics(diskPaths);
+      }).catch((err) => {
         this.reportError("SYSTEM_METRICS", "Scheduled system metrics collection failed", err);
       });
     }, intervalMs);
@@ -1470,6 +1523,10 @@ var MonitorClient = class {
       clearInterval(this.metricsCollectionTimer);
       this.metricsCollectionTimer = null;
     }
+    if (this.metricsSettingsCheckTimer) {
+      clearInterval(this.metricsSettingsCheckTimer);
+      this.metricsSettingsCheckTimer = null;
+    }
   }
   /**
    * Collect system metrics (CPU, RAM, disk) using built-in Node.js modules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceon-oy/monitor-sdk",
-  "version": "1.3.0",
+  "version": "1.4.2",
   "description": "Client SDK for Ceon Monitor - Error tracking, health monitoring, security events, and vulnerability scanning",
   "author": "Ceon",
   "license": "MIT",