Node.js OS Module Guide

The os module provides operating system information and utilities. Here's how to use it.

Basic System Information#

const os = require('os');

// Operating system
console.log('Platform:', os.platform());     // 'darwin', 'win32', 'linux'
console.log('OS Type:', os.type());          // 'Darwin', 'Windows_NT', 'Linux'
console.log('Release:', os.release());       // '20.6.0'
console.log('Version:', os.version());       // 'Darwin Kernel Version 20.6.0'
console.log('Architecture:', os.arch());     // 'x64', 'arm64'

// Machine info
console.log('Hostname:', os.hostname());     // 'my-macbook'
console.log('Home Dir:', os.homedir());      // '/Users/username'
console.log('Temp Dir:', os.tmpdir());       // '/tmp'

// User info
const userInfo = os.userInfo();
console.log('Username:', userInfo.username);
console.log('UID:', userInfo.uid);
console.log('GID:', userInfo.gid);
console.log('Shell:', userInfo.shell);
console.log('Home:', userInfo.homedir);

CPU Information#

const os = require('os');

// CPU cores
const cpus = os.cpus();
console.log('CPU Count:', cpus.length);

// CPU details
cpus.forEach((cpu, index) => {
  console.log(`CPU ${index}:`);
  console.log(`  Model: ${cpu.model}`);
  console.log(`  Speed: ${cpu.speed} MHz`);
  console.log(`  Times:`, cpu.times);
});

// CPU usage calculation
function getCPUUsage() {
  const cpus = os.cpus();
  let totalIdle = 0;
  let totalTick = 0;

  cpus.forEach((cpu) => {
    for (const type in cpu.times) {
      totalTick += cpu.times[type];
    }
    totalIdle += cpu.times.idle;
  });

  return {
    idle: totalIdle / cpus.length,
    total: totalTick / cpus.length,
    usage: 100 - (100 * totalIdle / totalTick),
  };
}

// Monitor CPU usage over time
function monitorCPU(interval = 1000) {
  let previousUsage = getCPUUsage();

  setInterval(() => {
    const currentUsage = getCPUUsage();
    const idleDiff = currentUsage.idle - previousUsage.idle;
    const totalDiff = currentUsage.total - previousUsage.total;
    const cpuPercent = 100 - (100 * idleDiff / totalDiff);

    console.log(`CPU Usage: ${cpuPercent.toFixed(2)}%`);
    previousUsage = currentUsage;
  }, interval);
}

Memory Information#

const os = require('os');

// Total and free memory
console.log('Total Memory:', os.totalmem());
console.log('Free Memory:', os.freemem());

// Human readable
function formatBytes(bytes) {
  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
  let index = 0;
  let size = bytes;

  while (size >= 1024 && index < units.length - 1) {
    size /= 1024;
    index++;
  }

  return `${size.toFixed(2)} ${units[index]}`;
}

console.log('Total:', formatBytes(os.totalmem()));  // "16.00 GB"
console.log('Free:', formatBytes(os.freemem()));    // "4.23 GB"

// Memory usage percentage
function getMemoryUsage() {
  const total = os.totalmem();
  const free = os.freemem();
  const used = total - free;

  return {
    total,
    free,
    used,
    percentage: (used / total) * 100,
  };
}

const memory = getMemoryUsage();
console.log(`Memory: ${memory.percentage.toFixed(2)}% used`);

// Process memory (from process module)
const processMemory = process.memoryUsage();
console.log('Process Memory:');
console.log('  RSS:', formatBytes(processMemory.rss));
console.log('  Heap Total:', formatBytes(processMemory.heapTotal));
console.log('  Heap Used:', formatBytes(processMemory.heapUsed));
console.log('  External:', formatBytes(processMemory.external));

Network Interfaces#

const os = require('os');

// Get all network interfaces
const interfaces = os.networkInterfaces();

for (const [name, addresses] of Object.entries(interfaces)) {
  console.log(`Interface: ${name}`);
  addresses.forEach((addr) => {
    console.log(`  ${addr.family}: ${addr.address}`);
    console.log(`  MAC: ${addr.mac}`);
    console.log(`  Internal: ${addr.internal}`);
    console.log(`  Netmask: ${addr.netmask}`);
    console.log('---');
  });
}

// Get local IP address
function getLocalIP() {
  const interfaces = os.networkInterfaces();

  for (const addresses of Object.values(interfaces)) {
    for (const addr of addresses) {
      if (addr.family === 'IPv4' && !addr.internal) {
        return addr.address;
      }
    }
  }

  return '127.0.0.1';
}

console.log('Local IP:', getLocalIP());

// Get all non-internal IPv4 addresses
function getAllLocalIPs() {
  const interfaces = os.networkInterfaces();
  const ips = [];

  for (const addresses of Object.values(interfaces)) {
    for (const addr of addresses) {
      if (addr.family === 'IPv4' && !addr.internal) {
        ips.push(addr.address);
      }
    }
  }

  return ips;
}

System Uptime and Load#

const os = require('os');

// System uptime in seconds
const uptime = os.uptime();
console.log('Uptime:', uptime, 'seconds');

// Format uptime
function formatUptime(seconds) {
  const days = Math.floor(seconds / 86400);
  const hours = Math.floor((seconds % 86400) / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);

  const parts = [];
  if (days > 0) parts.push(`${days}d`);
  if (hours > 0) parts.push(`${hours}h`);
  if (minutes > 0) parts.push(`${minutes}m`);

  return parts.join(' ') || '< 1m';
}

console.log('Uptime:', formatUptime(os.uptime())); // "5d 12h 34m"

// Load average (Unix only)
const loadAvg = os.loadavg();
console.log('Load Average (1m, 5m, 15m):', loadAvg);
// [1.5, 1.2, 0.9]

// Load percentage based on CPU count
const cpuCount = os.cpus().length;
console.log('Load %:', loadAvg.map(load =>
  `${((load / cpuCount) * 100).toFixed(1)}%`
));

System Constants#

const os = require('os');

// End of line character
console.log('EOL:', JSON.stringify(os.EOL));
// '\n' on Unix, '\r\n' on Windows

// Priority constants
console.log('Priority Levels:');
console.log('  PRIORITY_LOW:', os.constants.priority.PRIORITY_LOW);
console.log('  PRIORITY_BELOW_NORMAL:', os.constants.priority.PRIORITY_BELOW_NORMAL);
console.log('  PRIORITY_NORMAL:', os.constants.priority.PRIORITY_NORMAL);
console.log('  PRIORITY_ABOVE_NORMAL:', os.constants.priority.PRIORITY_ABOVE_NORMAL);
console.log('  PRIORITY_HIGH:', os.constants.priority.PRIORITY_HIGH);
console.log('  PRIORITY_HIGHEST:', os.constants.priority.PRIORITY_HIGHEST);

// Signal constants
console.log('Signals:', os.constants.signals);
// { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, ... }

// Error constants
console.log('Error codes:', os.constants.errno);
// { E2BIG: 7, EACCES: 13, EADDRINUSE: 48, ... }

Process Priority#

const os = require('os');

// Get process priority
const pid = process.pid;
const priority = os.getPriority(pid);
console.log('Current priority:', priority);

// Set process priority
try {
  os.setPriority(pid, os.constants.priority.PRIORITY_HIGH);
  console.log('Priority set to HIGH');
} catch (err) {
  console.error('Failed to set priority:', err.message);
}

// Priority for another process
function getProcessPriority(pid) {
  try {
    return os.getPriority(pid);
  } catch {
    return null;
  }
}

System Health Check#

const os = require('os');

function getSystemHealth() {
  const cpus = os.cpus();
  const totalMemory = os.totalmem();
  const freeMemory = os.freemem();
  const loadAvg = os.loadavg();

  return {
    platform: os.platform(),
    arch: os.arch(),
    hostname: os.hostname(),
    uptime: formatUptime(os.uptime()),
    cpu: {
      model: cpus[0].model,
      cores: cpus.length,
      loadAverage: {
        '1m': loadAvg[0].toFixed(2),
        '5m': loadAvg[1].toFixed(2),
        '15m': loadAvg[2].toFixed(2),
      },
    },
    memory: {
      total: formatBytes(totalMemory),
      free: formatBytes(freeMemory),
      used: formatBytes(totalMemory - freeMemory),
      usagePercent: ((1 - freeMemory / totalMemory) * 100).toFixed(2) + '%',
    },
    network: getLocalIP(),
  };
}

console.log(JSON.stringify(getSystemHealth(), null, 2));

Monitoring Service#

const os = require('os');
const EventEmitter = require('events');

class SystemMonitor extends EventEmitter {
  constructor(options = {}) {
    super();
    this.interval = options.interval || 5000;
    this.memoryThreshold = options.memoryThreshold || 90;
    this.cpuThreshold = options.cpuThreshold || 80;
    this.previousCPU = null;
    this.timer = null;
  }

  start() {
    this.previousCPU = this.getCPUInfo();
    this.timer = setInterval(() => this.check(), this.interval);
    this.emit('started');
  }

  stop() {
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = null;
      this.emit('stopped');
    }
  }

  getCPUInfo() {
    const cpus = os.cpus();
    let idle = 0;
    let total = 0;

    cpus.forEach(cpu => {
      for (const type in cpu.times) {
        total += cpu.times[type];
      }
      idle += cpu.times.idle;
    });

    return { idle, total };
  }

  check() {
    // Memory check
    const memoryUsage = (1 - os.freemem() / os.totalmem()) * 100;
    if (memoryUsage > this.memoryThreshold) {
      this.emit('memoryWarning', { usage: memoryUsage });
    }

    // CPU check
    const currentCPU = this.getCPUInfo();
    const idleDiff = currentCPU.idle - this.previousCPU.idle;
    const totalDiff = currentCPU.total - this.previousCPU.total;
    const cpuUsage = 100 - (100 * idleDiff / totalDiff);

    if (cpuUsage > this.cpuThreshold) {
      this.emit('cpuWarning', { usage: cpuUsage });
    }

    this.previousCPU = currentCPU;
    this.emit('stats', { memory: memoryUsage, cpu: cpuUsage });
  }
}

// Usage
const monitor = new SystemMonitor({ interval: 2000 });

monitor.on('memoryWarning', ({ usage }) => {
  console.log(`Memory warning: ${usage.toFixed(2)}%`);
});

monitor.on('cpuWarning', ({ usage }) => {
  console.log(`CPU warning: ${usage.toFixed(2)}%`);
});

monitor.start();

Best Practices#

Information Gathering:
✓ Cache static values (platform, arch)
✓ Format values for readability
✓ Handle cross-platform differences
✓ Use appropriate units

Monitoring:
✓ Sample CPU over time intervals
✓ Set appropriate thresholds
✓ Log warnings and anomalies
✓ Consider system load in decisions

Performance:
✓ Don't poll too frequently
✓ Cache when appropriate
✓ Use events for notifications
✓ Consider worker threads for heavy monitoring

Avoid:
✗ Assuming specific OS behavior
✗ Ignoring platform differences
✗ Blocking the event loop
✗ Excessive system calls

The os module provides essential system information for monitoring, diagnostics, and platform-aware code. Use it to gather CPU, memory, and network details, monitor system health, and adapt behavior based on the operating system.