Node.js Process Management

Understanding process management is essential for production Node.js applications. Here's what you need to know.

Process Information#

// Process basics
console.log('PID:', process.pid);
console.log('PPID:', process.ppid);
console.log('Platform:', process.platform);
console.log('Architecture:', process.arch);
console.log('Node version:', process.version);
console.log('Working directory:', process.cwd());

// Environment variables
console.log('NODE_ENV:', process.env.NODE_ENV);
console.log('All env:', process.env);

// Memory usage
const used = process.memoryUsage();
console.log('Memory:', {
  heapTotal: `${Math.round(used.heapTotal / 1024 / 1024)}MB`,
  heapUsed: `${Math.round(used.heapUsed / 1024 / 1024)}MB`,
  external: `${Math.round(used.external / 1024 / 1024)}MB`,
  rss: `${Math.round(used.rss / 1024 / 1024)}MB`,
});

// CPU usage
const startUsage = process.cpuUsage();
// ... do work ...
const endUsage = process.cpuUsage(startUsage);
console.log('CPU time:', {
  user: `${endUsage.user / 1000}ms`,
  system: `${endUsage.system / 1000}ms`,
});

// Uptime
console.log('Uptime:', process.uptime(), 'seconds');

Signal Handling#

// Common signals
// SIGTERM - Graceful shutdown request
// SIGINT - Ctrl+C interrupt
// SIGHUP - Terminal closed
// SIGKILL - Force kill (cannot be caught)

// Handle SIGTERM (graceful shutdown)
process.on('SIGTERM', () => {
  console.log('SIGTERM received, shutting down...');
  gracefulShutdown();
});

// Handle SIGINT (Ctrl+C)
process.on('SIGINT', () => {
  console.log('SIGINT received, shutting down...');
  gracefulShutdown();
});

// Handle SIGHUP (terminal closed)
process.on('SIGHUP', () => {
  console.log('SIGHUP received');
  // Reload configuration, rotate logs, etc.
});

// Windows equivalent
if (process.platform === 'win32') {
  const readline = require('readline');
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  rl.on('SIGINT', () => {
    process.emit('SIGINT');
  });
}

Graceful Shutdown#

const http = require('http');

class GracefulShutdown {
  constructor(server, options = {}) {
    this.server = server;
    this.timeout = options.timeout || 30000;
    this.connections = new Set();
    this.shuttingDown = false;

    // Track connections
    server.on('connection', (conn) => {
      this.connections.add(conn);
      conn.on('close', () => this.connections.delete(conn));
    });
  }

  async shutdown(signal) {
    if (this.shuttingDown) return;
    this.shuttingDown = true;

    console.log(`${signal} received, starting graceful shutdown...`);

    // Stop accepting new connections
    this.server.close(() => {
      console.log('Server closed');
    });

    // Set timeout for forced shutdown
    const forceShutdown = setTimeout(() => {
      console.error('Forcing shutdown...');
      process.exit(1);
    }, this.timeout);

    try {
      // Close database connections
      await this.closeDatabase();

      // Finish processing requests
      await this.closeConnections();

      // Clear timeout and exit
      clearTimeout(forceShutdown);
      console.log('Graceful shutdown complete');
      process.exit(0);
    } catch (error) {
      console.error('Error during shutdown:', error);
      process.exit(1);
    }
  }

  async closeConnections() {
    // End idle connections
    for (const conn of this.connections) {
      conn.end();
    }

    // Wait for connections to close
    await new Promise((resolve) => {
      const checkConnections = () => {
        if (this.connections.size === 0) {
          resolve();
        } else {
          setTimeout(checkConnections, 100);
        }
      };
      checkConnections();
    });
  }

  async closeDatabase() {
    // Close database pool
    if (global.db) {
      await global.db.end();
    }
  }
}

// Usage
const server = http.createServer(app);
const shutdown = new GracefulShutdown(server);

process.on('SIGTERM', () => shutdown.shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown.shutdown('SIGINT'));

Child Processes#

const { spawn, exec, execFile, fork } = require('child_process');

// spawn - Stream output
const ls = spawn('ls', ['-la']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`Process exited with code ${code}`);
});

// exec - Buffer output
exec('ls -la', (error, stdout, stderr) => {
  if (error) {
    console.error(`Error: ${error.message}`);
    return;
  }
  console.log(`stdout: ${stdout}`);
});

// exec with promise
const { promisify } = require('util');
const execPromise = promisify(exec);

async function runCommand() {
  const { stdout } = await execPromise('ls -la');
  console.log(stdout);
}

// fork - For Node.js scripts
const child = fork('./worker.js');

child.send({ task: 'process', data: [1, 2, 3] });

child.on('message', (result) => {
  console.log('Result:', result);
});

// worker.js
process.on('message', (msg) => {
  const result = processData(msg.data);
  process.send(result);
});

Process Pool#

const { fork } = require('child_process');
const os = require('os');

class WorkerPool {
  constructor(workerScript, poolSize = os.cpus().length) {
    this.workerScript = workerScript;
    this.poolSize = poolSize;
    this.workers = [];
    this.queue = [];

    this.initialize();
  }

  initialize() {
    for (let i = 0; i < this.poolSize; i++) {
      this.createWorker();
    }
  }

  createWorker() {
    const worker = fork(this.workerScript);

    worker.on('message', (result) => {
      worker.busy = false;
      worker.currentTask?.resolve(result);
      this.processQueue();
    });

    worker.on('error', (error) => {
      worker.currentTask?.reject(error);
      this.replaceWorker(worker);
    });

    worker.on('exit', (code) => {
      if (code !== 0) {
        this.replaceWorker(worker);
      }
    });

    worker.busy = false;
    this.workers.push(worker);
  }

  replaceWorker(deadWorker) {
    const index = this.workers.indexOf(deadWorker);
    if (index !== -1) {
      this.workers.splice(index, 1);
      this.createWorker();
    }
  }

  async execute(task) {
    return new Promise((resolve, reject) => {
      this.queue.push({ task, resolve, reject });
      this.processQueue();
    });
  }

  processQueue() {
    if (this.queue.length === 0) return;

    const availableWorker = this.workers.find((w) => !w.busy);
    if (!availableWorker) return;

    const { task, resolve, reject } = this.queue.shift();

    availableWorker.busy = true;
    availableWorker.currentTask = { resolve, reject };
    availableWorker.send(task);
  }

  async shutdown() {
    await Promise.all(
      this.workers.map(
        (worker) =>
          new Promise((resolve) => {
            worker.once('exit', resolve);
            worker.kill('SIGTERM');
          })
      )
    );
  }
}

// Usage
const pool = new WorkerPool('./worker.js', 4);

const results = await Promise.all([
  pool.execute({ type: 'compute', data: 1 }),
  pool.execute({ type: 'compute', data: 2 }),
  pool.execute({ type: 'compute', data: 3 }),
]);

Error Handling#

// Uncaught exceptions
process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  // Log error, clean up, then exit
  process.exit(1);
});

// Unhandled promise rejections
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
  // In Node.js 15+, this will crash the process by default
});

// Better: Use a proper error handler
process.on('uncaughtException', async (error) => {
  console.error('Uncaught Exception:', error);

  try {
    // Log to error monitoring service
    await logToService(error);

    // Graceful shutdown
    await gracefulShutdown();
  } catch (shutdownError) {
    console.error('Shutdown error:', shutdownError);
  }

  process.exit(1);
});

// Warning events
process.on('warning', (warning) => {
  console.warn('Warning:', warning.name, warning.message);
});

Exit Codes#

// Common exit codes
// 0 - Success
// 1 - General error
// 2 - Misuse of command
// 126 - Command not executable
// 127 - Command not found
// 128+N - Fatal signal N

// Exit with code
process.exit(0); // Success
process.exit(1); // Error

// Set exit code without exiting
process.exitCode = 1;

// Exit event
process.on('exit', (code) => {
  console.log(`Exiting with code ${code}`);
  // Only synchronous operations work here
});

// Before exit (can be async)
process.on('beforeExit', async (code) => {
  console.log(`Before exit with code ${code}`);
  // Can do async operations
  await cleanup();
});

Health Checks#

const http = require('http');

class HealthChecker {
  constructor() {
    this.checks = new Map();
  }

  addCheck(name, checkFn) {
    this.checks.set(name, checkFn);
  }

  async runChecks() {
    const results = {};
    let healthy = true;

    for (const [name, checkFn] of this.checks) {
      try {
        await checkFn();
        results[name] = { status: 'healthy' };
      } catch (error) {
        results[name] = { status: 'unhealthy', error: error.message };
        healthy = false;
      }
    }

    return { healthy, checks: results };
  }
}

// Usage
const health = new HealthChecker();

health.addCheck('database', async () => {
  await db.query('SELECT 1');
});

health.addCheck('redis', async () => {
  await redis.ping();
});

health.addCheck('memory', async () => {
  const used = process.memoryUsage();
  if (used.heapUsed > 500 * 1024 * 1024) {
    throw new Error('Memory usage too high');
  }
});

// Health endpoint
app.get('/health', async (req, res) => {
  const result = await health.runChecks();
  res.status(result.healthy ? 200 : 503).json(result);
});

Best Practices#

Signals:
✓ Handle SIGTERM for graceful shutdown
✓ Handle SIGINT for development
✓ Set timeout for forced shutdown
✓ Log shutdown progress

Error Handling:
✓ Catch uncaught exceptions
✓ Handle unhandled rejections
✓ Exit after uncaught exceptions
✓ Use proper exit codes

Production:
✓ Implement health checks
✓ Monitor memory usage
✓ Use process managers (PM2)
✓ Log to external service

Proper process management ensures reliable Node.js applications. Handle signals for graceful shutdown, manage child processes carefully, and always have proper error handling. Use health checks and monitoring for production visibility.