npm install uncaught-exceptionHandle uncaught exceptions.
Supports 0.10 only. Designed for robustness and garaunteed
eventual termination of the process.
``js
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)
`
See docs.mli for type definitions
`js`
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'uncaughtException'
handling function that can be passed to
listener of the .
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.fatal()
It's expected to have a 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.immediateIncrement()
It's expected to have a 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 isos.hostname()
logged when an uncaught exception occurs. You might want to
put the 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.statsd
The node implementation of UDP which the 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" asoptions.backupFile
the property. If you set it to either"stdout"
or "stderr" then it will synchronously write toprocess.stdout
and process.stderr respectively.
Caveat: If you are running windows and have set
options.backupFile to "stdout" or "stderr" then it's notprocess.stdout
garaunteed to be synchronous. In windows any writes to
when process.stdout is a PIPE will benode foo.js | tee file
asynchronous. i.e. will involvebackupFile
asynchronous writing to the .
#### options.abortOnUncaught
If options.abortOnUncaught is set to true the uncaught handlerprocess.abort()
will call graceful shutdown and 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 totrue.
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 totrue.
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.
npm install uncaught-exception
npm test`
- Raynos
- dfellis
- squamos