README

Utensil

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) {
  resp.end('woo')
})
$ utensil -p 8000
spawning 8 processes listening on 0.0.0.0:8000

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

CLI

-p 8000

--port 8000

The port to bind to.

--addr

--address 0.0.0.0

The address to bind to.

-c

--cpus 8

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

-p

--poll 2000

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

-a

--adaptor path/to/file.js

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

Messages passed to the Adaptor

Messages are of the form:

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

metrics

memory

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

request

{ "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`> } }

error

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> } }

console

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

{ "type": "console"
, "subtype": "error" | "warn" | "log"
, "data": [arguments to console] }

Example adaptor

// console.js

// simply output everything.
module.exports = function(pid, msg) {
  console.log('#%s %s/%s', pid, msg.type, msg.subtype, msg.data)
}

// run it with 
//     utensil --adaptor path/to/console.js

License

MIT

Usage no npm install needed!