log-process-errors

What is log-process-errors?

The log-process-errors npm package is designed to automatically log and handle process errors in Node.js applications. It provides a simple and consistent way to manage errors such as uncaught exceptions, unhandled promise rejections, and other process-level errors, making debugging and monitoring easier.

What are log-process-errors's main functionalities?

Automatic Error Logging

This feature automatically logs uncaught exceptions, unhandled promise rejections, and other process errors to the console or a specified logging service. By simply requiring and invoking the package, it starts monitoring and logging errors without additional configuration.

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

Custom Error Handlers

Allows you to define custom error handlers for different types of process errors. This example shows how to log a custom message for each error event.

const logProcessErrors = require('log-process-errors');
logProcessErrors({
  onError(error, event, originalError) {
    console.error(`Custom handler: ${event} - ${error.message}`);
  }
});

Integration with Logging Services

This feature allows integration with various logging services like Winston, Bunyan, or any other logging library. The example demonstrates how to use Winston to log process errors.

const logProcessErrors = require('log-process-errors');
const winston = require('winston');
const logger = winston.createLogger({
  transports: [
    new winston.transports.Console()
  ]
});
logProcessErrors({
  onError(error, event, originalError) {
    logger.error(`${event} - ${error.message}`);
  }
});

Other packages similar to log-process-errors

winston

Winston is a versatile logging library for Node.js that allows you to log messages to various transports (console, file, etc.). While it does not specifically handle process errors out of the box, it can be configured to log such errors with custom handlers.

bunyan

Bunyan is another logging library for Node.js that provides a simple and fast JSON logging solution. Similar to Winston, it does not automatically handle process errors but can be used in conjunction with custom error handlers to log such errors.

pino

Pino is a fast and low-overhead logging library for Node.js. It focuses on performance and can be used to log process errors by setting up custom error handlers. It does not provide automatic process error handling like log-process-errors.

README

📰 Medium article.

Show some ❤️ to Node.js process errors.

This improves process errors: uncaught exceptions, unhandled promises, promises handled too late and warnings.

Hire me

Please reach out if you're looking for a Node.js API or CLI engineer (11 years of experience). Most recently I have been Netlify Build's and Netlify Plugins' technical lead for 2.5 years. I am available for full-time remote positions.

Features

• Stack traces for warnings and rejectionHandled
• Single event handler for all process errors
• Ignore duplicate process errors
• Normalize invalid errors
• Process exit is graceful and can be prevented

Install

Production code (e.g. a server) can install this either as a production or development dependency:

npm install log-process-errors

However, libraries should install this as a development dependency:

npm install -D log-process-errors

This is because logging is modified globally and libraries users might not expect this side-effect. Also, this might lead to conflicts between libraries.

This package works in Node.js >=18.18.0.

This is an ES module. It must be loaded using an import or import() statement, not require(). If TypeScript is used, it must be configured to output ES modules, not CommonJS.

API

logProcessErrors(options?)

options object?
Return value: () => void

Start handling process errors.

import logProcessErrors from 'log-process-errors'
logProcessErrors(options)

The return value restores Node.js default behavior.

const restore = logProcessErrors(options)
restore()

Options

exit

Type: boolean

Whether to exit the process on uncaught exceptions or unhandled promises.

This is false by default if other libraries are listening to those events, so they can perform the exit instead. Otherwise, this is true.

If some tasks are still ongoing, the exit waits for them to complete up to 3 seconds.

onError

Type: (error, event) => Promise<void> | void
Default: console.error(error)

Function called once per process error. Duplicate process errors are ignored.

// Log process errors with Winston instead
logProcessErrors({
  onError: (error, event) => {
    winstonLogger.error(error.stack)
  },
})

error

Type: Error

The process error. This is guaranteed to be a normalized error instance. A short description of the event is also appended to its message.

event

Type: Event

Process event name among: 'uncaughtException', 'unhandledRejection', 'rejectionHandled', 'warning'.

Related projects

• modern-errors: Handle errors in a simple, stable, consistent way
• modern-errors-process: Handle process errors
• error-custom-class: Create one error class
• error-class-utils: Utilities to properly create error classes
• error-serializer: Convert errors to/from plain objects
• normalize-exception: Normalize exceptions/errors
• is-error-instance: Check if a value is an Error instance
• merge-error-cause: Merge an error with its cause
• set-error-class: Properly update an error's class
• set-error-message: Properly update an error's message
• wrap-error-message: Properly wrap an error's message
• set-error-props: Properly update an error's properties
• set-error-stack: Properly update an error's stack
• error-cause-polyfill: Polyfill error.cause
• handle-cli-error: 💣 Error handler for CLI applications 💥
• error-http-response: Create HTTP error responses
• winston-error-format: Log errors with Winston

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!

Thanks go to our wonderful contributors:

ehmicky 💻 🎨 🤔 📖

Steven Vachon 💬

Hongarc 📖 💻

Andy Brenneke 🐛