airbrake

Node Airbrake

DEPRECATION WARNING: Node Airbrake is deprecated in favour of @airbrake/node (https://www.npmjs.com/package/@airbrake/node). Please migrate to it as soon as possible. See migration guide.

• Node Airbrake README

Introduction

DEPRECATION WARNING: Node Airbrake is deprecated in favour of @airbrake/node (https://www.npmjs.com/package/@airbrake/node). Please migrate to it as soon as possible.

Node Airbrake is a Node.js notifier for Airbrake, the leading exception reporting service. The library provides minimalist API that enables the ability to send any Node exception to the Airbrake dashboard. Node Airbrake provides out-of-box integration with the Express web framework.

Key features

• Send chosen environment variables (whitelist or blacklist)
• Detect and fix circular references in error context information
• Support for all features of the 2.1 notification API
• Support for long-stack-traces
• Optional auto-handler for uncaughtException events
• Provides notification URL linking to Airbrake in notify() callback
• Timeout Airbrake requests after 30 seconds, you never know
• Express web application framework support
• hapi web application framework support

Installation

NPM

Add the Node Airbrake package to your package.json:

{
  "dependencies": {
    "airbrake": "^2.1.3"
  }
}

Manual

Invoke the following command from your terminal:

npm install airbrake

Examples

Basic example

This is the minimal example that you can use to test Node Airbrake with your project. The common use case for this module is to catch all 'uncaughtException' events on the process object and send them to Airbrake:

var airbrake = require('airbrake').createClient(
  '105138', // Project ID
  'fd04e13d806a90f96614ad8e529b2822' // Project key
);
airbrake.handleExceptions();

throw new Error('I am an uncaught exception');

Note: the above will re-throw the exception after it has been successfully delivered to Airbrake, causing your process to exit with status 1.

This can optionally be disabled by passing false to handleExceptions (not recommended):

airbrake.handleExceptions(false);

Filtering errors

There may be some errors thrown in your application that you're not interested in sending to Airbrake, such as errors thrown by 3rd-party libraries.

The Airbrake notifier makes it simple to ignore this chaff while still processing legitimate errors. Add filters to the notifier by providing filter functions to addFilter.

addFilter accepts the entire error notice to be sent to Airbrake, and provides access to the context, environment, params, and session values submitted with the notice, as well as the single-element errors array with its backtrace element and associated backtrace lines.

The return value of the filter function determines whether or not the error notice will be submitted.

• If null value is returned, the notice is ignored.
• Otherwise returned notice will be submitted.

An error notice must pass all provided filters to be submitted.

In the following example errors triggered with a message of 'this should not be posted to airbrake' will be ignored:

airbrake.addFilter(function(notice) {
  if (notice.errors[0].message === 'this should not be posted to airbrake') {
    // Ignore errors with this messsage
    return null;
  }
  return notice;
});

Filters can be also used to modify notice payload, e.g. to set environment and application version:

airbrake.addFilter(function(notice) {
  notice.context.environment = 'production';
  notice.context.version = '1.2.3';
  return notice;
});

Manual error delivery

If you want more control over the delivery of your errors, you can also manually submit errors to Airbrake:

var airbrake = require('airbrake').createClient("your project ID", "your api key");
var err = new Error('Something went terribly wrong');
airbrake.notify(err, function(err, url) {
  if (err) throw err;

  // Error has been delivered, url links to the error in airbrake
});

Severity

Severity allows categorizing how severe an error is. By default, it's set to error. To redefine severity, simply set an error's severity property. For example:

var err = new Error();
err.severity = 'critical';

airbrake.notify(err);

Express integration

The library provides out-of-box integration with the Express framework. It supports even old Express versions (starting from 2.x). Select your version below and configure accordingly.

Express 4.x

var airbrake = require('airbrake').createClient("your project ID", "your api key");
app.use(airbrake.expressHandler());

Express 3.x

var airbrake = require('airbrake').createClient("your project ID", "your api key");
app.use(app.router);
app.use(airbrake.expressHandler());

Express 2.x

var airbrake = require('airbrake').createClient("your project ID", "your api key");
app.error(airbrake.expressHandler());

hapi integration

The library provides out-of-box integration with the hapi framework. To integrate Airbrake with a hapi application simply install our handler:

const Hapi = require('hapi');
const server = new Hapi.Server();
const Airbrake = require('airbrake').createClient(
  "your project ID",
  "your api key"
);

Airbrake.env = 'production';

server.register(Airbrake.hapiHandler(), err => {
  if (err) {
    throw err;
  }
});

API

Adding context to errors

The notify() method automatically adds the following context information to each delivered error:

• error.class: (err.type string if set, or 'Error')
• error.message: (err.message string)
• error.backtrace: (err.stack as parsed by stack-trace)
• error.severity: (err.severity defaults to error)
• request.url: (err.url, see airbrake.url);
• request.component: (err.component string if set);
• request.action: (err.action string if set);
• request.cgi-data: (process.env, merged all other properties of err)
• request.params: (err.params object if set)
• request.session: (err.session object if set)
• server-environment.project-root: (airbrake.projectRoot string if set)
• server-environment.environment-name: (airbrake.env string)
• server-environment.app-version: (`airbrake.appVersion string if set)

You can add additional context information by modifying the error properties listed above:

var airbrake = require('airbrake').createClient("your project ID", "your api key");
var http = require('http');

http.createServer(function(req, res) {
  if (req.headers['X-Secret'] !== 'my secret') {
    var err = new Error('403 - Permission denied');
    req.writeHead(403);
    req.end(err.message);

    err.url = req.url;
    err.params = {ip: req.socket.remoteAddress};
    airbrake.notify(err);
  }
});

Unfortunately uncaughtException events cannot be traced back to particular requests, so you should still try to handle errors where they occur.

Tracking deployments

This client supports Airbrake's deployment tracking:

var airbrake = require('airbrake').createClient("your project ID", "your api key");
var deployment = {
  rev: '98103a8fa850d5eaf3666e419d8a0a93e535b1b2',
  repo: '[e-mail]:felixge/node-airbrake.git',
};

airbrake.trackDeployment(deployment, function(err, params) {
  if (err) {
    throw err;
  }

  console.log('Tracked deployment of %s to %s', params.rev, params.env);
});

Check out the airbrake.trackDeployment() API docs below for a list of all options.

Configuration

var airbrake = Airbrake.createClient(projectId, key, [env])

Airbrake.createClient() returns a new Airbrake instance.

Options

• projectId - Your application's Airbrake project ID.
• key - Your application's Airbrake API key.
• env - The name of the server environment this is running in.

airbrake.projectId = null

Your application's Airbrake project ID.

airbrake.key = null

Your application's Airbrake API key.

airbrake.env = process.env.NODE_ENV || 'development'

The name of the server environment this is running in.

airbrake.host = 'https://' + os.hostname()

The base url for errors. If err.url is not set, airbrake.host is used instead. If err.url is a relative url starting with '/', it is appended to airbrake.host. If err.url is an absolute url, airbrake.host is ignored.

airbrake.projectRoot = process.cwd()

The root directory of this project.

airbrake.appVersion = null

The version of this app. Set to a semantic version number, or leave unset.

airbrake.protocol = 'https'

The protocol to use.

airbrake.timeout = 30 * 1000

The timeout after which to give up trying to notify Airbrake in ms.

airbrake.proxy = null

The HTTP/HTTPS proxy to use when making requests.

airbrake.requestOptions = {}

Additional request options that are merged with the default set of options that are passed to request during notify() and trackDeployment().

airbrake.whiteListKeys = []

Names of environment variables to send.

airbrake.blackListKeys = []

Names of environment variables to filter out.

airbrake.handleExceptions()

Registers a process.on('uncaughtException') listener. When an uncaught exception occurs, the error is sent to Airbrake, and then re-thrown to kill the process.

airbrake.handlePromiseRejections()

Registers a process.on('unhandledRejection') listener. When an uncaught exception occurs inside a promise, the error is sent to Airbrake, and then re-thrown to kill the process.

airbrake.expressHandler(disableUncaughtException)

A custom error handler that is used with Express. Integrate with Express middleware using app.use().

Options:

• disableUncaughtException: Disables re-throwing and killing process on uncaught exception.

airbrake.notify(err, [cb])

Sends the given err to airbrake.

The callback parameter receives two arguments, err, url. err is set if the delivery to Airbrake failed.

If no cb is given, and the delivery fails, an error event is emitted. If there is no listener for this event, node will kill the process as well. This is done to avoid silent error delivery failure.

airbrake.trackDeployment([params, [cb]])

Notifies Airbrake about a deployment. params is an object with the following options:

• env: The environment being deployed, defaults to airbrake.env.
• user: The user doing the deployment, defaults to process.env.USER.
• repo: The github url of this repository. Defaults to git config --get remote.origin.url.
• rev: The revision of this deployment. Defaults to git rev-parse HEAD.

Additional notes

Exception limit

The maximum size of an exception is 64KB. Exceptions that exceed this limit will be truncated to fit the size.

License

The library was originally created by Felix Geisendörfer. The project uses the MIT License. See LICENSE.md for details.

Changelog

[v2.1.3][v2.1.3] (April 23, 2020)

• Updated migration guide link