1 | # forever-monitor [![Build Status](https://secure.travis-ci.org/nodejitsu/forever-monitor.png)](http://travis-ci.org/nodejitsu/forever-monitor)
|
2 |
|
3 | The core monitoring functionality of forever without the CLI
|
4 |
|
5 | ## Usage
|
6 | You can also use forever from inside your own node.js code.
|
7 |
|
8 | ``` js
|
9 | var forever = require('forever-monitor');
|
10 |
|
11 | var child = new (forever.Monitor)('your-filename.js', {
|
12 | max: 3,
|
13 | silent: true,
|
14 | options: []
|
15 | });
|
16 |
|
17 | child.on('exit', function () {
|
18 | console.log('your-filename.js has exited after 3 restarts');
|
19 | });
|
20 |
|
21 | child.start();
|
22 | ```
|
23 |
|
24 | ### Spawning a non-node process
|
25 | You can spawn non-node processes too. Either set the `command` key in the
|
26 | `options` hash or pass in an `Array` in place of the `file` argument like this:
|
27 |
|
28 | ``` js
|
29 | var forever = require('forever-monitor');
|
30 | var child = forever.start([ 'perl', '-le', 'print "moo"' ], {
|
31 | max : 1,
|
32 | silent : true
|
33 | });
|
34 | ```
|
35 |
|
36 | ### Options available when using Forever in node.js
|
37 | There are several options that you should be aware of when using forever. Most of this configuration is optional.
|
38 |
|
39 | ``` js
|
40 | {
|
41 | //
|
42 | // Basic configuration options
|
43 | //
|
44 | 'silent': false, // Silences the output from stdout and stderr in the parent process
|
45 | 'uid': 'your-UID' // Custom uid for this forever process. (default: autogen)
|
46 | 'pidFile': 'path/to/a.pid', // Path to put pid information for the process(es) started
|
47 | 'max': 10, // Sets the maximum number of times a given script should run
|
48 | 'killTree': true // Kills the entire child process tree on `exit`
|
49 |
|
50 | //
|
51 | // These options control how quickly forever restarts a child process
|
52 | // as well as when to kill a "spinning" process
|
53 | //
|
54 | 'minUptime': 2000, // Minimum time a child process has to be up. Forever will 'exit' otherwise.
|
55 | 'spinSleepTime': 1000, // Interval between restarts if a child is spinning (i.e. alive < minUptime).
|
56 |
|
57 | //
|
58 | // Command to spawn as well as options and other vars
|
59 | // (env, cwd, etc) to pass along
|
60 | //
|
61 | 'command': 'perl', // Binary to run (default: 'node')
|
62 | 'options': ['foo','bar'], // Additional arguments to pass to the script,
|
63 | 'sourceDir': 'script/path' // Directory that the source script is in
|
64 |
|
65 | //
|
66 | // Options for restarting on watched files.
|
67 | //
|
68 | 'watch': false // Value indicating if we should watch files.
|
69 | 'watchIgnoreDotFiles': null // Dot files we should read to ignore ('.foreverignore', etc).
|
70 | 'watchIgnorePatterns': null // Ignore patterns to use when watching files.
|
71 | 'watchDirectory': null // Top-level directory to watch from.
|
72 |
|
73 | //
|
74 | // All or nothing options passed along to `child_process.spawn`.
|
75 | //
|
76 | 'spawnWith': {
|
77 | customFds: [-1, -1, -1], // that forever spawns.
|
78 | setsid: false
|
79 | },
|
80 |
|
81 | //
|
82 | // More specific options to pass along to `child_process.spawn` which
|
83 | // will override anything passed to the `spawnWith` option
|
84 | //
|
85 | 'env': { 'ADDITIONAL': 'CHILD ENV VARS' }
|
86 | 'cwd': '/path/to/child/working/directory'
|
87 |
|
88 | //
|
89 | // Log files and associated logging options for this instance
|
90 | //
|
91 | 'logFile': 'path/to/file', // Path to log output from forever process (when daemonized)
|
92 | 'outFile': 'path/to/file', // Path to log output from child stdout
|
93 | 'errFile': 'path/to/file' // Path to log output from child stderr
|
94 | }
|
95 | ```
|
96 |
|
97 | ### Events available when using an instance of Forever in node.js
|
98 | Each forever object is an instance of the node.js core EventEmitter. There are several core events that you can listen for:
|
99 |
|
100 | * **error** _[err]:_ Raised when an error occurs
|
101 | * **start** _[process, data]:_ Raised when the target script is first started.
|
102 | * **stop** _[process]:_ Raised when the target script is stopped by the user
|
103 | * **restart** _[forever]:_ Raised each time the target script is restarted
|
104 | * **exit** _[forever]:_ Raised when the target script actually exits (permenantly).
|
105 | * **stdout** _[data]:_ Raised when data is received from the child process' stdout
|
106 | * **stderr** _[data]:_ Raised when data is received from the child process' stderr
|
107 |
|
108 | ## Installation
|
109 |
|
110 | ``` bash
|
111 | $ npm install forever-monitor
|
112 | ```
|
113 |
|
114 | ## Run Tests
|
115 |
|
116 | ``` bash
|
117 | $ npm test
|
118 | ```
|
119 |
|
120 | #### License: MIT
|
121 | #### Author: [Charlie Robbins](http://github.com/indexzero)
|
122 | #### Contributors: [Fedor Indutny](http://github.com/indutny), [James Halliday](http://substack.net/), [Charlie McConnell](http://github.com/avianflu), [Maciej Malecki](http://github.com/mmalecki)
|