By default Node.js prints uncaughtException, warning and mishandled promises (unhandledRejection, rejectionHandled, multipleResolves) on the console which is very useful. Unfortunately those process errors:

• show neither stack traces nor promise values for warning, rejectionHandled and multipleResolves making it hard to debug.
• are inconvenient to log to an external service.
• are printed each time the exact same error is repeated (except for warning).
• are not human-friendly.

log-process-errors fixes those issues:

Installation

$ npm install 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. Also this might lead to conflicts between libraries.

Usage

There are two ways to load this library. The first is to use the node -r CLI flag:

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

The second is:

const logProcessErrors = require('log-process-errors')
logProcessErrors(options)

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

options is an optional object with the following properties:

• log {function}
• level {object}
• message {function}
• colors {boolean}
• exitOn {string[]}

Custom logging

By default events will be logged to the console using console.error(), console.warn(), etc.

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), level (string) and info (object).

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).

Duplicate events are only logged once (whether the log option is defined or not).

Log level

The default log level is warn for warning, info for multipleResolves and error for the other events.

This can be overridden by using the level option. It should be an object whose:

• keys are the event names among default, uncaughtException, warning, unhandledRejection, rejectionHandled or multipleResolves.
• values are the log level which can be:
  • a string among debug, info, warn, error or silent.
  • undefined to use the default value.
  • a function using info as argument and returning a string or undefined (as above).

logProcessErrors({
  // Use `debug` log level for `multipleResolves` instead of `info`
  level: { multipleResolves: 'debug' },
})

logProcessErrors({
  // Skip some logs based on a condition
  level: {
    default() {
      if (shouldSkip()) {
        return 'silent'
      }
    },
  },
})

Log message

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

The message will be colorized unless the option colors is set to false.

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

Event information

The log, level and message options all receive as argument an info object.

info.eventName

String among uncaughtException, unhandledRejection, rejectionHandled, multipleResolves or warning.

info.error

Either the value thrown by uncaughtException or the error emitted by warning. Not defined with other events. It is usually an Error instance but could be anything.

info.promiseState

String indicating whether the promise was resolved or rejected. Only defined with unhandledRejection, rejectionHandled and multipleResolves.

info.promiseValue

Value resolved/rejected by the promise. Only defined with unhandledRejection, rejectionHandled and multipleResolves.

info.secondPromiseState, info.secondPromiseValue

Like promiseState and promiseValue but for the second time the promise was resolved/rejected. Only defined with multipleResolves.

info.level

Log level. Only defined with the message option.

info.colors

Chalk instance to colorize strings. Only defined with the message option. Disabled if the colors option is false.

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.
• we recommend using ['uncaughtException', 'unhandledRejection'] instead since this will be the future default behavior of Node.js.
• to prevent any process.exit(1) use []. Recommended if your process is long-running and does not automatically restart on exit.

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

Stop logging

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

const logProcessErrors = require('log-process-errors')

const stopLogging = logProcessErrors(options)

stopLogging()