forever-monitor

Core forever process monitor

forever-monitor

The core monitoring functionality of forever without the CLI

You can also use forever from inside your own node.js code.

  var forever = require('forever-monitor');
 
  var child = new (forever.Monitor)('your-filename.js', {
    max: 3,
    silent: true,
    args: []
  });
 
  child.on('exit', function () {
    console.log('your-filename.js has exited after 3 restarts');
  });
 
  child.start();

You can spawn non-node processes too. Either set the command key in the options hash or pass in an Array in place of the file argument like this:

  var forever = require('forever-monitor');
  var child = forever.start([ 'perl', '-le', 'print "moo"' ], {
    max : 1,
    silent : true
  });

There are several options that you should be aware of when using forever. Most of this configuration is optional.

  {
    // 
    // Basic configuration options 
    // 
    'silent': false,            // Silences the output from stdout and stderr in the parent process 
    'uid': 'your-UID',          // Custom uid for this forever process. (default: autogen) 
    'pidFile': 'path/to/a.pid', // Path to put pid information for the process(es) started 
    'max': 10,                  // Sets the maximum number of times a given script should run 
    'killTree': true,           // Kills the entire child process tree on `exit` 
 
    // 
    // These options control how quickly forever restarts a child process 
    // as well as when to kill a "spinning" process 
    // 
    'minUptime': 2000,     // Minimum time a child process has to be up. Forever will 'exit' otherwise. 
    'spinSleepTime': 1000, // Interval between restarts if a child is spinning (i.e. alive < minUptime). 
 
    // 
    // Command to spawn as well as options and other vars 
    // (env, cwd, etc) to pass along 
    // 
    'command': 'perl',         // Binary to run (default: 'node') 
    'args':    ['foo','bar'],  // Additional arguments to pass to the script, 
    'sourceDir': 'script/path',// Directory that the source script is in 
 
    // 
    // Options for restarting on watched files. 
    // 
    'watch': true,               // Value indicating if we should watch files. 
    'watchIgnoreDotFiles': null, // Whether to ignore file starting with a '.' 
    'watchIgnorePatterns': null, // Ignore patterns to use when watching files. 
    'watchDirectory': null,      // Top-level directory to watch from. 
 
    // 
    // All or nothing options passed along to `child_process.spawn`. 
    // 
    'spawnWith': {
      customFds: [-1, -1, -1], // that forever spawns. 
      setsid: false,
      uid: 0, // Custom UID 
      gid: 0  // Custom GID 
    },
 
    // 
    // More specific options to pass along to `child_process.spawn` which 
    // will override anything passed to the `spawnWith` option 
    // 
    'env': { 'ADDITIONAL': 'CHILD ENV VARS' },
    'cwd': '/path/to/child/working/directory',
 
    // 
    // Log files and associated logging options for this instance 
    // 
    'logFile': 'path/to/file', // Path to log output from forever process (when daemonized) 
    'outFile': 'path/to/file', // Path to log output from child stdout 
    'errFile': 'path/to/file', // Path to log output from child stderr 
 
    // 
    // ### function parseCommand (command, args) 
    // #### @command {String} Command string to parse 
    // #### @args    {Array}  Additional default arguments 
    // 
    // Returns the `command` and the `args` parsed from 
    // any command. Use this to modify the default parsing 
    // done by 'forever-monitor' around spaces. 
    // 
    'parser'function (commandargs) {
      return {
        command: command,
        args:    args
      };
    }
  }

Each forever object is an instance of the node.js core EventEmitter. There are several core events that you can listen for:

  • error [err]: Raised when an error occurs
  • start [process, data]: Raised when the target script is first started.
  • stop [process]: Raised when the target script is stopped by the user
  • restart [forever]: Raised each time the target script is restarted
  • exit [forever]: Raised when the target script actually exits (permanently).
  • stdout [data]: Raised when data is received from the child process' stdout
  • stderr [data]: Raised when data is received from the child process' stderr

When running the forever CLI tool, it produces debug outputs about which files have changed / how processes exited / etc. To get a similar behaviour with forever-monitor, add the following event listeners:

var child = new (forever.Monitor)('your-filename.js');
 
child.on('watch:restart', function(info) {
    console.error('Restaring script because ' + info.file + ' changed');
});
 
child.on('restart', function() {
    console.error('Forever restarting script for ' + child.times + ' time');
});
 
child.on('exit:code', function(code) {
    console.error('Forever detected script exited with code ' + code);
});
  $ npm install forever-monitor
  $ npm test

Author: Charlie Robbins

Contributors: Fedor Indutny, James Halliday, Charlie McConnell, Maciej Malecki