@dotcom-reliability-kit/crash-handler

@dotcom-reliability-kit/crash-handler

Warning This Reliability Kit package is experimental and should be used with caution in production applications. Please also let the Customer Products Reliability team know if you intend on using this.

A method to bind an uncaught exception handler to ensure that fatal application errors are logged. It is a replacement for Sentry fatal error logging. This module is part of FT.com Reliability Kit.

• Usage
  • registerCrashHandler
  • configuration options
    • process
• Compatibility
  • Migrating from Sentry
• Contributing
• License

Usage

Install @dotcom-reliability-kit/crash-handler as a dependency:

npm install --save @dotcom-reliability-kit/crash-handler

Include in your code:

import registerCrashHandler from '@dotcom-reliability-kit/crash-handler';
// or
const registerCrashHandler = require('@dotcom-reliability-kit/crash-handler');

registerCrashHandler

The registerCrashHandler function can be used to bind an event handler to the Node.js process.uncaughtException event. This ensures that your application logs a final message before crashing in the event on an unexpected error or promise rejection.

This function should only ever be called once in your app, normally alongside all your setup code (e.g. alongside creating an Express app).

Note It's not a requirement, but generally the earlier the better with registering an uncaught exception handler – the sooner you register it the more likely you are to catch uncaught exceptions.

registerCrashHandler();

If an error is thrown which will crash your application, error information will be logged and then the process will exit with the value of process.exitCode or 1.

Warning This function will not work as expected if your app is using n-raven or n-express without the withSentry option set to false. This is because the way we set up Sentry prevents registering any other uncaught exception handlers. You'll need to migrate away from Sentry to use this module.

Configuration options

Config options can be passed into the registerCrashHandler function as an object with any of the keys below.

registerCrashHandler({
    // Config options go here
});

options.process

The Node.js Process object to bind the error handling event to. You may use this if you are using a child process or want to mock the process object in your tests.

registerCrashHandler({
    process: myProcessObject
});

Compatibility

Migrating from Sentry

The Reliability Kit crash handler is a replacement for Sentry's uncaught exception handling, which your app is likely using. You'll need to migrate away from Sentry in order to use this module. You can do so by:

1. Remove any references to n-raven in your codebase. You may be importing this module yourself, and if you do then registerCrashHandler will not work as expected.

2. If you're using n-express, it must be on v26.3.0 or higher. This version of n-express introduces the ability to turn off Sentry.

3. Configure n-express to disable Sentry by setting the withSentry option to false. Find your n-express setup and add the option:

   express({
       withSentry: false
   });
   

4. Follow the instructions in the usage guide to set up Reliability Kit's crash handler.

Contributing

See the central contributing guide for Reliability Kit.

License

Licensed under the MIT license.
Copyright © 2022, The Financial Times Ltd.