@jsenv/os-metrics 0.0.1

package/README.md

@@ -0,0 +1,131 @@
+# @jsenv/os-metrics
+
+[![npm package](https://img.shields.io/npm/v/@jsenv/os-metrics.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/os-metrics)
+
+A lightweight library for monitoring CPU and memory usage of both your Node.js process and the operating system.
+
+## Features
+
+- Simple API for monitoring system resources
+- Process-specific and OS-wide metrics
+- Statistical analysis (min, max, median) for measurement periods
+- Zero dependencies
+
+## Installation
+
+```console
+npm install @jsenv/os-metrics
+```
+
+## CPU Usage Monitoring
+
+Monitor CPU usage for both the current process and the entire operating system:
+
+```js
+// Start monitoring
+const [processCpuMonitoring, osCpuMonitoring] = startMonitoringCpuUsage();
+
+// Take measurements at regular intervals
+const interval = setInterval(() => {
+  const processCpuUsage = processCpuMonitoring.measure(); // Returns value between 0-1
+  const osCpuUsage = osCpuMonitoring.measure(); // Returns value between 0-1
+
+  console.log(`Process CPU: ${(processCpuUsage * 100).toFixed(2)}%`);
+  console.log(`System CPU: ${(osCpuUsage * 100).toFixed(2)}%`);
+}, 500);
+
+// When finished monitoring
+clearInterval(interval);
+processCpuMonitoring.end();
+osCpuMonitoring.end();
+
+// Access statistical information
+const { info: processInfo } = processCpuMonitoring;
+console.log({
+  minCpuUsage: processInfo.min,
+  maxCpuUsage: processInfo.max,
+  medianCpuUsage: processInfo.median,
+});
+```
+
+## Measuring Usage Monitoring
+
+Track memory consumption for both the current process and the system:
+
+```js
+import { startMonitoringMemoryUsage } from "@jsenv/os-metrics";
+
+// Start monitoring
+const [processMemoryMonitoring, osMemoryMonitoring] =
+  startMonitoringMemoryUsage();
+
+// Take measurements at regular intervals
+const interval = setInterval(() => {
+  const processMemoryBytes = processMemoryMonitoring.measure(); // Returns bytes used
+  const osMemoryBytes = osMemoryMonitoring.measure(); // Returns bytes used
+
+  console.log(
+    `Process memory: ${(processMemoryBytes / 1024 / 1024).toFixed(2)} MB`,
+  );
+  console.log(`System memory: ${(osMemoryBytes / 1024 / 1024).toFixed(2)} MB`);
+}, 500);
+
+// When finished monitoring
+clearInterval(interval);
+processMemoryMonitoring.end();
+osMemoryMonitoring.end();
+
+// Access statistical information
+const { info: memoryInfo } = processMemoryMonitoring;
+console.log({
+  minMemoryUsage: `${(memoryInfo.min / 1024 / 1024).toFixed(2)} MB`,
+  maxMemoryUsage: `${(memoryInfo.max / 1024 / 1024).toFixed(2)} MB`,
+  medianMemoryUsage: `${(memoryInfo.median / 1024 / 1024).toFixed(2)} MB`,
+});
+```
+
+Each call to `measure()` returns memory usage (a number representing the number of bytes being used).
+`end()` stops the monitoring and fill `.info` of the memory metric.
+
+```js
+const { info } = processMemoryMonitoring;
+
+info.min; //  the min cpu usage between startMonitoringCpuUsage() and end()
+info.max; // the max cpu usage between startMonitoringCpuUsage() and end()
+info.median; // the median usage  between startMonitoringCpuUsage() and end()
+```
+
+## API Reference
+
+### `startMonitoringCpuUsage()`
+
+Starts monitoring CPU usage and returns two monitoring objects:
+
+- First: Process CPU monitoring
+- Second: OS-wide CPU monitoring
+
+### `startMonitoringMemoryUsage()`
+
+Starts monitoring memory usage and returns two monitoring objects:
+
+- First: Process memory monitoring
+- Second: OS-wide memory monitoring
+
+### Monitoring Object Methods
+
+Each monitoring object provides:
+
+- `measure()`: Take a measurement and return the current value
+- `end()`: Stop monitoring and calculate statistical information
+- `info`: Object containing min, max, and median values (available after calling end())
+
+## Use Cases
+
+- Performance testing and benchmarking
+- Resource usage optimization
+- System monitoring in Node.js applications
+- Detecting memory leaks and CPU spikes
+
+## Platform Support
+
+Works on all major operating systems supported by Node.js (Windows, macOS, Linux).

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jsenv/os-metrics",
+  "version": "0.0.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsenv/core",
+    "directory": "packages/independent/tooling/os-metrics"
+  },
+  "author": {
+    "name": "dmail",
+    "email": "dmaillard06@gmail.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/main.js",
+  "files": [
+    "/src/"
+  ],
+  "sideEffects": false
+}

package/src/available_cpu.js

@@ -0,0 +1,9 @@
+import { availableParallelism, cpus } from "node:os";
+
+export const countAvailableCpus = () => {
+  if (typeof availableParallelism === "function") {
+    return availableParallelism();
+  }
+  const cpuArray = cpus();
+  return cpuArray.length || 1;
+};

package/src/available_memory.js

@@ -0,0 +1,3 @@
+import { totalmem } from "node:os";
+
+export const getAvailableMemory = () => totalmem();

package/src/cpu_monitoring.js

@@ -0,0 +1,17 @@
+// https://gist.github.com/GaetanoPiazzolla/c40e1ebb9f709d091208e89baf9f4e00
+
+import { startMeasuringTotalCpuUsage } from "./cpu_usage.js";
+import { startMonitoringMetric } from "./metric_monitoring.js";
+
+export const startMonitoringCpuUsage = () => {
+  const cpuUsage = startMeasuringTotalCpuUsage();
+  const processCpuUsageMonitoring = startMonitoringMetric(() => {
+    return cpuUsage.thisProcess.active;
+  });
+  const osCpuUsageMonitoring = startMonitoringMetric(() => {
+    return cpuUsage.overall.active;
+  });
+  const result = [processCpuUsageMonitoring, osCpuUsageMonitoring];
+  result.stop = cpuUsage.stop;
+  return result;
+};

package/src/cpu_usage.js

@@ -0,0 +1,219 @@
+import { cpus } from "node:os";
+import { cpuUsage } from "node:process";
+
+export const startMeasuringTotalCpuUsage = () => {
+  let previousCpuArray = cpus();
+  let previousMs = Date.now();
+  let previousCpuUsage = cpuUsage();
+
+  const overall = {
+    inactive: 100,
+    active: 0,
+    system: 0,
+    user: 0,
+  };
+  const thisProcess = {
+    active: 0,
+    system: 0,
+    user: 0,
+  };
+  const details = previousCpuArray.map(() => {
+    return {
+      inactive: 100,
+      active: 0,
+      system: 0,
+      user: 0,
+    };
+  });
+
+  const samples = [];
+  const interval = setInterval(() => {
+    let cpuArray = cpus();
+    const ms = Date.now();
+    const ellapsedMs = ms - previousMs;
+    const cpuUsageSampleArray = [];
+    let overallSystemMs = 0;
+    let overallUserMs = 0;
+    let overallInactiveMs = 0;
+    let overallActiveMs = 0;
+    let overallMsEllapsed = 0;
+    let index = 0;
+    for (const cpu of cpuArray) {
+      const previousCpuTimes = previousCpuArray[index].times;
+      const cpuTimes = cpu.times;
+      const systemMs = cpuTimes.sys - previousCpuTimes.sys;
+      const userMs = cpuTimes.user - previousCpuTimes.user;
+      const activeMs = systemMs + userMs;
+      const inactiveMs = ellapsedMs - activeMs;
+      const cpuUsageSample = {
+        inactive: inactiveMs / ellapsedMs,
+        active: activeMs / ellapsedMs,
+        system: systemMs / ellapsedMs,
+        user: userMs / ellapsedMs,
+      };
+      cpuUsageSampleArray.push(cpuUsageSample);
+
+      overallSystemMs += systemMs;
+      overallUserMs += userMs;
+      overallInactiveMs += inactiveMs;
+      overallActiveMs += activeMs;
+      overallMsEllapsed += ellapsedMs;
+      index++;
+    }
+    const overallUsageSample = {
+      inactive: overallInactiveMs / overallMsEllapsed,
+      active: overallActiveMs / overallMsEllapsed,
+      system: overallSystemMs / overallMsEllapsed,
+      user: overallUserMs / overallMsEllapsed,
+    };
+    previousCpuArray = cpuArray;
+    previousMs = ms;
+
+    const processCpuUsage = cpuUsage();
+    const thisProcessSystemMs = Math.round(
+      (processCpuUsage.system - previousCpuUsage.system) / 1000,
+    );
+    const thisProcessUserMs = Math.round(
+      (processCpuUsage.user - previousCpuUsage.user) / 1000,
+    );
+    previousCpuUsage = processCpuUsage;
+
+    const thisProcessActiveMs = thisProcessSystemMs + thisProcessUserMs;
+    const thisProcessInactiveMs = overallMsEllapsed - thisProcessActiveMs;
+    const thisProcessSample = {
+      inactive: thisProcessInactiveMs / overallMsEllapsed,
+      active: thisProcessActiveMs / overallMsEllapsed,
+      system: thisProcessSystemMs / overallMsEllapsed,
+      user: thisProcessUserMs / overallMsEllapsed,
+    };
+    samples.push({
+      cpuUsageSampleArray,
+      overallUsageSample,
+      thisProcessSample,
+    });
+    if (samples.length === 10) {
+      per_cpu: {
+        let index = 0;
+        for (const detail of details) {
+          let systemSum = 0;
+          let userSum = 0;
+          let inactiveSum = 0;
+          let activeSum = 0;
+          for (const sample of samples) {
+            const { cpuUsageSampleArray } = sample;
+            const cpuUsageSample = cpuUsageSampleArray[index];
+            inactiveSum += cpuUsageSample.inactive;
+            activeSum += cpuUsageSample.active;
+            systemSum += cpuUsageSample.system;
+            userSum += cpuUsageSample.user;
+          }
+          Object.assign(detail, {
+            inactive: inactiveSum / samples.length,
+            active: activeSum / samples.length,
+            system: systemSum / samples.length,
+            user: userSum / samples.length,
+          });
+          index++;
+        }
+      }
+      all: {
+        let overallSystemSum = 0;
+        let overallUserSum = 0;
+        let overallInactiveSum = 0;
+        let overallActiveSum = 0;
+        for (const sample of samples) {
+          const { overallUsageSample } = sample;
+          overallSystemSum += overallUsageSample.system;
+          overallUserSum += overallUsageSample.user;
+          overallInactiveSum += overallUsageSample.inactive;
+          overallActiveSum += overallUsageSample.active;
+        }
+        Object.assign(overall, {
+          inactive: overallInactiveSum / samples.length,
+          active: overallActiveSum / samples.length,
+          system: overallSystemSum / samples.length,
+          user: overallUserSum / samples.length,
+        });
+      }
+      this_process: {
+        let thisProcessSystemSum = 0;
+        let thisProcessUserSum = 0;
+        let thisProcessInactiveSum = 0;
+        let thisProcessActiveSum = 0;
+        for (const sample of samples) {
+          const { thisProcessSample } = sample;
+          thisProcessSystemSum += thisProcessSample.system;
+          thisProcessUserSum += thisProcessSample.user;
+          thisProcessInactiveSum += thisProcessSample.inactive;
+          thisProcessActiveSum += thisProcessSample.active;
+        }
+        Object.assign(thisProcess, {
+          inactive: thisProcessInactiveSum / samples.length,
+          active: thisProcessActiveSum / samples.length,
+          system: thisProcessSystemSum / samples.length,
+          user: thisProcessUserSum / samples.length,
+        });
+      }
+      samples.length = 0;
+    }
+  }, 15);
+  interval.unref();
+
+  return {
+    overall,
+    thisProcess,
+    details,
+    stop: () => {
+      clearInterval(interval);
+    },
+  };
+};
+
+export const startMeasuringCpuUsage = () => {
+  let previousHrtime = process.hrtime();
+  let previousCpuUsage = process.cpuUsage();
+
+  const info = {
+    used: 0,
+  };
+
+  const interval = setInterval(() => {
+    const hrtime = process.hrtime(previousHrtime);
+    previousHrtime = hrtime;
+    const cpuUsage = process.cpuUsage(previousCpuUsage);
+    previousCpuUsage = cpuUsage;
+
+    const ellapsedMs = hrtime[0] * 1000 + hrtime[1] / 1000000;
+    const userMs = Math.round(cpuUsage.user / 1000);
+    const systemMs = Math.round(cpuUsage.system / 1000);
+    const activeMs = userMs + systemMs;
+    const usedRatio = activeMs / ellapsedMs;
+    const used = Math.round(usedRatio * 100) / 100;
+    info.used = used;
+  }, 15);
+  interval.unref();
+
+  return {
+    info,
+    stop: () => {
+      clearInterval(interval);
+    },
+  };
+};
+
+export const formatUsage = (usageInfo) => {
+  const { active, inactive, system, user } = usageInfo;
+
+  return `${ratioAsPercentage(active)} (system: ${ratioAsPercentage(
+    system,
+  )}, user: ${ratioAsPercentage(user)}), inactive: ${ratioAsPercentage(
+    inactive,
+  )}`;
+};
+
+export const ratioAsPercentage = (ratio) => {
+  const percentageAsNumber = ratio * 100;
+  const percentageAsNumberRounded = Math.round(percentageAsNumber);
+  const percentage = `${percentageAsNumberRounded}%`;
+  return percentage;
+};

package/src/cpu_usage.test_manual.js

@@ -0,0 +1,17 @@
+import {
+  formatUsage,
+  startMeasuringCpuUsage,
+  startMeasuringTotalCpuUsage,
+} from "./cpu_usage.js";
+
+const cpuUsage = startMeasuringCpuUsage();
+setInterval(() => {
+  console.log(cpuUsage.info.used);
+}, 400);
+
+const totalCpuUsage = startMeasuringTotalCpuUsage();
+setInterval(() => {
+  console.log(`overall: ${formatUsage(totalCpuUsage.overall)}
+this process: ${formatUsage(totalCpuUsage.thisProcess)}
+`);
+}, 400);

package/src/main.js

@@ -0,0 +1,12 @@
+export { countAvailableCpus } from "./available_cpu.js";
+export { getAvailableMemory } from "./available_memory.js";
+export { getOsVersion } from "./os_version.js";
+
+export { startMonitoringCpuUsage } from "./cpu_monitoring.js";
+export { startMonitoringMemoryUsage } from "./memory_monitoring.js";
+
+export {
+  startMeasuringCpuUsage,
+  startMeasuringTotalCpuUsage,
+} from "./cpu_usage.js";
+export { startMonitoringMetric } from "./metric_monitoring.js";

package/src/memory_monitoring.js

@@ -0,0 +1,21 @@
+import { freemem, totalmem } from "node:os";
+import { memoryUsage } from "node:process";
+import { startMonitoringMetric } from "./metric_monitoring.js";
+
+export const startMonitoringMemoryUsage = () => {
+  const processMemoryUsageMonitoring = startMonitoringMetric(() => {
+    return memoryUsage().rss;
+  });
+  const osMemoryUsageMonitoring = startMonitoringMetric(() => {
+    const total = totalmem();
+    const free = freemem();
+    return total - free;
+  });
+  const stop = () => {
+    processMemoryUsageMonitoring.stop();
+    osMemoryUsageMonitoring.stop();
+  };
+  const result = [processMemoryUsageMonitoring, osMemoryUsageMonitoring];
+  result.stop = stop;
+  return result;
+};

package/src/metric_monitoring.js

@@ -0,0 +1,44 @@
+export const startMonitoringMetric = (measure) => {
+  const metrics = [];
+  const takeMeasure = () => {
+    const value = measure();
+    metrics.push(value);
+    return value;
+  };
+
+  const info = {
+    start: takeMeasure(),
+    min: null,
+    max: null,
+    median: null,
+    end: null,
+  };
+  return {
+    info,
+    measure: takeMeasure,
+    end: () => {
+      info.end = takeMeasure();
+      metrics.sort((a, b) => a - b);
+      info.min = metrics[0];
+      info.max = metrics[metrics.length - 1];
+      info.median = medianFromSortedArray(metrics);
+      metrics.length = 0;
+    },
+  };
+};
+
+export const medianFromSortedArray = (array) => {
+  const length = array.length;
+  const isOdd = length % 2 === 1;
+  if (isOdd) {
+    const medianNumberIndex = (length - 1) / 2;
+    const medianNumber = array[medianNumberIndex];
+    return medianNumber;
+  }
+  const rightMiddleNumberIndex = length / 2;
+  const leftMiddleNumberIndex = rightMiddleNumberIndex - 1;
+  const leftMiddleNumber = array[leftMiddleNumberIndex];
+  const rightMiddleNumber = array[rightMiddleNumberIndex];
+  const medianNumber = (leftMiddleNumber + rightMiddleNumber) / 2;
+  return medianNumber;
+};

package/src/os_version.js

@@ -0,0 +1,3 @@
+import { release } from "node:os";
+
+export const getOsVersion = () => release();

package/src/process_memory_monitoring.js

@@ -0,0 +1,9 @@
+import { memoryUsage } from "node:process";
+import { startMonitoringMetric } from "./metric_monitoring.js";
+
+export const startMeasuringProcessMemoryUsage = () => {
+  const processMemoryUsageMonitoring = startMonitoringMetric(() => {
+    return memoryUsage().rss;
+  });
+  return processMemoryUsageMonitoring;
+};