a utensil to fork and monitor servers across cpus


A command-line tool for running node.js servers.

  • Uses cluster to automatically fork server processes into the background
  • Uses adaptors to send process metrics to monitoring
  • Uses node 0.8's domain module to catch and report errors per-request
  • Programmatic interface as well as CLI
  • Catches uncaughtExceptions and closes the request they were associated with and reports the error!
  • Redirects all console.log statements to your adaptor module.
$ ls .
package.json        node_modules/       app.js
$ cat app.js
module.exports = http.createServer(function(req, resp) {
$ utensil -p 8000
spawning 8 processes listening on

Zing! utensil will also handle unhandled exceptions for you, serving up a 500 page where appropriate (without taking down your node process!)

The port to bind to.

The address to bind to.

The number of processes to fork. Defaults to the number of cpus reported by require('os').cpus().length.

The millisecond interval that child process should report their memory usage.

Path to a JavaScript module that exports a single function taking pid and msg.

Messages are of the form:

{ "type": "metrics" | "error" | "console"
, "subtype": <subtype>
, "data": <message> }

data will include the output of process.memoryUsage().

{ "type": "metrics"
, "subtype": "request"
, "data": { "start": <unix ms epoch timestamp>
          , "elapsed": <ms from request received till response>
          , "status": <HTTP status code of response>
          , "url": <contents of `req.url`> } }

For global, pre-runtime errors:

{ "type": "error"
, "subtype": "application"
, "data": { "err": <err+''>
          , "stack": <err.stack if available> } } 

For errors during the duration of a request:

{ "type": "error"
, "subtype": "request"
, "data": { "err": <err+''>
          , "start": <unix ms epoch timestamp>
          , "elapsed": <ms from request received till response>
          , "stack": <err.stack if available> } } 

All console output will be redirected to the adaptor, as well.

{ "type": "console"
, "subtype": "error" | "warn" | "log"
, "data": [arguments to console] } 
// console.js 
// simply output everything. 
module.exports = function(pidmsg) {
  console.log('#%s %s/%s', pid, msg.type, msg.subtype, msg.data)
// run it with  
//     utensil --adaptor path/to/console.js