uncaught-exception

Handle uncaught exceptions.

Supports 0.10 only. Designed for robustness and garaunteed eventual termination of the process.

Example

var uncaughtHandler = require('uncaught-exception');
 
var myLogger = {
    fatal: function fatal(message, metaObj, callback) {
        // must call the callback once logged
    }
}
var myStatsd = {
    immediateIncrement: function inc(key, count, callback) {
        // call the callback once incremented.
    }
}
 
var onError = uncaughtHandler({
    logger: myLogger,
    statsd: myStatsd,
    meta: { 'hostname': require('os').hostname() },
    abortOnUncaught: true, // opt into aborting on uncaught
    backupFile: '/path/to/uncaught-handler.log',
    gracefulShutdown: function (callback) {
        // perform some graceful shutdown here.
 
        // for example synchronize state of your app to redis
        // for example communicate to master process in cluster
        // and ask for a new worker to be started
 
        // must call callback once gracefully shutdown
        // after you call the callback the process will shutdown
    }
})
 
process.on('uncaughtException', onError)

Docs

Type definitions

See docs.mli for type definitions

var onError = uncaughtHandler(options)

uncaught-exception/uncaught := (options: {
    logger: {
        fatal: (String, Object, Callback) => void
    },
    statsd: {
        immediateIncrement: (String, Number, Callback) =>void
    },
    meta?: Object,
    statsdKey?: String,
    statsdWaitPeriod?: Number,
    backupFile?: "stdout" | "stderr" | String,
    abortOnUncaught?: Boolean,
    loggerTimeout?: Number,
    statsdTimeout?: Number,
    shutdownTimeout?: Number,
    gracefulShutdown?: (Callback) => void,
    preAbort?: () => void
}) => onError: (Error) => void

uncaughtHandler takes an options object and returns an error handling function that can be passed to 'uncaughtException' listener of the process.

You must pass the uncaughtHandler a logger with a fatal() method.

The uncaughtHandler will exit your process once it's done logging the error.

options.logger

options.logger is a logger object used to log the exception. It's expected to have a fatal() method that takes a string, an error object and a callback.

The logger should invoke the callback once it's flushed it to all the logging backends you support, (i.e. disk, sentry, etc)

options.statsd

options.statsd is a statsd object used to increment counters. It's expected to have a immediateIncrement() method that takes a string, a number and a callback.

The statsd should invoke the callback once it's flushed it to the stats service.

options.meta

options.meta allows you to configure the meta object that is logged when an uncaught exception occurs. You might want to put the os.hostname() in the meta object.

options.statsdKey

options.statsdKey allows you to configure what kind of statsd key we increment when we have an uncaught exception.

The key defaults to "service-crash".

options.statsdWaitPeriod

options.statsdWaitPeriod is a configurable waiting period. The node implementation of UDP which the statsd client will probably uses invokes the callback too early.

If you abort() synchronously there is no garantuee that we've actually send the statsd out of the process.

To work around this we have an "arbitrary" waiting period after we get the statsd callback.

options.statsdWaitPeriod defaults to 1500 milliseconds

options.backupFile

options.backupFile is a filePath that will be appended to synchronously incase anything goes wrong inside the uncaught exception handler.

It's highly recommended you pass a backup file path in case your logger fails.

Inspecting the backupFile and looking at the core dump will give you a deep insight into exactly what happened at the end of your node process.

You may also pass the string literal "stdout" or "stderr" as the options.backupFile property. If you set it to either "stdout" or "stderr" then it will synchronously write to process.stdout and process.stderr respectively.

Caveat: If you are running windows and have set options.backupFile to "stdout" or "stderr" then it's not garaunteed to be synchronous. In windows any writes to process.stdout when process.stdout is a PIPE will be asynchronous. i.e. node foo.js | tee file will involve asynchronous writing to the backupFile.

options.abortOnUncaught

If options.abortOnUncaught is set to true the uncaught handler will call graceful shutdown and process.abort() for you.

If this is set to undefined or false the uncaught handler will not call graceful shutdown and it will not call process abort

options.loggerTimeout

The uncaughtHandler will assume that your logger might fail or hang so it times out the fatal logging call.

The default timeout is 30 seconds, you can pass loggerTimeout if you want to overwrite it.

options.statsdTimeout

The uncaughtHandler will assume that your statsd might fail or hang so it times out the statsd increment call.

The default timeout is 5 seconds, you can pass statsdTimeout if you want to overwrite it.

options.gracefulShutdown

The uncaught-exception module supports doing a graceful shutdown. Normally when an uncaught exception happens you want to close any servers that are open and wait for all sockets to exit cleanly.

This function only gets called if abortOnUncaught is set to true.

Ideally you want to empty the event loop and do a full graceful shutdown.

You may also want to communicate to the master process if you are running under cluster.

For more information on proper error handling see the node domain documentation

options.shutdownTimeout

The uncaughtHandler will assume that your gracefulShutdown might fail or hang so it times out the graceful shutdown call.

The default timeout is 30 seconds, you can pass shutdownTimeout if you want to overwrite it.

options.preAbort

You can specify your own preAbort handler that MUST be a synchronous function.

This function only gets called if abortOnUncaught is set to true.

The main use case is to invoke your own exit strategy instead of the default exit strategy which is calling process.abort()

For example you may want to process.exit(1) here instead.

Installation

npm install uncaught-exception

tests

npm test

Contributors

• Raynos
• dfellis
• squamos

MIT Licenced