Log all process errors on the console (or using a custom logger): uncaughtException, unhandledRejection, rejectionHandled, multipleResolves and warning.

While Node.js already prints those errors on the console, log-process-errors provides with the following additional features:

• more detailed messages, including stack traces and promise values for warning, rejectionHandled and multipleResolves (which are not printed otherwise)
• nicer looking and more descriptive messages
• log repeated events only once
• custom logging
• control whether to process.exit() or not

Installation

$ npm install -D log-process-errors

log-process-errors modifies logging globally. It should not be installed as a production dependency inside libraries since:

• users might not expect this side effect
• this might lead to conflicts between libraries

Usage (simple)

$ node -r log-process-errors/register ...

Usage (custom)

const { init } = require('log-process-errors')

init(options)

init() should be called as early as possible in the code.

options is an optional object with the following properties:

• log {function}
• getLevel {function}
• getMessage {function}
• colors {boolean} (default: true)
• skipEvent {function}
• exitOn {string[]} (default: ['uncaughtException'])

Duplicate events

Duplicate events are only logged once.

It is recommended to use the --no-warnings CLI flag or the NODE_NO_WARNINGS=1 environment variable to prevent warnings being logged twice.

Process exit

The exitOn option specifies which event should trigger process.exit(1):

• the default value is ['uncaughtException']. This is the default behavior of Node.js. It's also recommended by the official documentation.
• we recommend using ['uncaughtException', 'unhandledRejection'] instead since this will be the future default behavior of Node.js
• to prevent any process.exit(1), use []

process.exit(1) will only be fired after successfully logging the event.

Custom logging

By default events will be logged to the console (e.g. console.error()).

This behavior can be overridden with the log option. For example to log events with Winston instead:

logProcessErrors({
  log(message, level, info) {
    winstonLogger[level](message)
  },
})

The function's arguments are:

• message {string}: nice and detailed description of the event. Can be customized with the getMessage option.
• level {string}: log level. Can be customized with the getLevel option.
• info {object}: event information

If logging is asynchronous, the function should return a promise (or use async/await). This is not necessary if logging is using streams (like Winston).

Log level

By default the log level will be warn for warning events and error for the other events.

This can be overridden by using the getLevel option. It should be a function function using info as argument and returning a string among error, warn, info or debug.

logProcessErrors({
  getLevel({ eventName }) {
    return eventName === 'uncaughtException' ? 'error' : 'warn'
  },
})

Log message

A nice-looking and descriptive log message is generated by default.

The message will be colorized unless either:

• the output does not support colors
• the option colors is set to false

The message generation can be overridden by using the getMessage option. It should be a function using info as argument and returning a string.

Skipping events

Events can be skipped with the skipEvent option. It should be a function using info as argument and returning true or false.

For example to skip warning events:

logProcessErrors({
  skipEvent({ eventName }) {
    return eventName === 'warning'
  },
})

Event information

The options log, getLevel, getMessage and skipEvent all receive as argument an info object with information about the event. It has the following properties:

• eventName {string}: can be uncaughtException, unhandledRejection, rejectionHandled, multipleResolves or warning
• error {any}:
  • either the value thrown by uncaughtException
  • or the error emitted by warning. error.code and error.detail might be defined.
  • it is usually an Error instance but could technically be anything
• promiseState {string}: whether the promise was resolved or rejected
• promiseValue {any}: value resolved/rejected by the promise
• secondPromiseState, secondPromiseValue: like promiseState and promiseValue but for the second time the promise was resolved/rejected

Whether the properties above are defined or not depends on the event name:

• eventName: always present
• error: only on uncaughtException and warning
• promiseState, promiseValue: only on unhandledRejection, rejectionHandled and multipleResolves
• secondPromiseState, secondPromiseValue: only on multipleResolves

The following properties are also defined with the getMessage option:

• level {string}
• colors {object}: Chalk instance to colorize strings (disabled if the option colors is false)

Stop logging

Logging can be stopped by firing the function returned by logProcessErrors()

const { init } = require('log-process-errors')

const stopLogging = init(options)

stopLogging()