Official Airbrake Notifier for Node.js


The official Airbrake notifier for capturing JavaScript errors in Node.js and
reporting them to Airbrake. If you're looking for
browser support, there is a
separate package.

Installation

Using yarn:

``sh
yarn add @airbrake/node
`

Using npm:

`sh
npm install @airbrake/node
`

Basic Usage

First, initialize the notifier with the project ID and project key taken from
Airbrake. To find your project_id and project_key
navigate to your project's _Settings_ and copy the values from the right
sidebar:

![][project-idkey]

`js
const { Notifier } = require('@airbrake/node');

const airbrake = new Notifier({
projectId: 1,
projectKey: 'REPLACE_ME',
environment: 'production',
});
`

Then, you can send a textual message to Airbrake:

`js
let promise = airbrake.notify(user id=${user_id} not found);
promise.then((notice) => {
if (notice.id) {
console.log('notice id', notice.id);
} else {
console.log('notify failed', notice.error);
}
});
`

or report errors directly:

`js
try {
throw new Error('Hello from Airbrake!');
} catch (err) {
airbrake.notify(err);
}
`

Alternatively, you can wrap any code which may throw errors using the wrap
method:

`js
let startApp = () => {
throw new Error('Hello from Airbrake!');
};
startApp = airbrake.wrap(startApp);

// Any exceptions thrown in startApp will be reported to Airbrake.
startApp();
`

or use the call shortcut:

`js
let startApp = () => {
throw new Error('Hello from Airbrake!');
};

airbrake.call(startApp);
`

Example configurations

- Express
- Node.js

Advanced Usage

$3

It's possible to annotate error notices with all sorts of useful information at
the time they're captured by supplying it in the object being reported.

`js
try {
startApp();
} catch (err) {
airbrake.notify({
error: err,
context: { component: 'bootstrap' },
environment: { env1: 'value' },
params: { param1: 'value' },
session: { session1: 'value' },
});
}
`

$3

Severity allows
categorizing how severe an error is. By default, it's set to error. To
redefine severity, simply overwrite context/severity of a notice object:

`js
airbrake.notify({
error: err,
context: { severity: 'warning' },
});
`

$3

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 properties. It also includes the single-element errors array
with its backtrace property and associated backtrace lines.

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

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

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

In the following example all errors triggered by admins will be ignored:

`js
airbrake.addFilter((notice) => {
if (notice.params.admin) {
// Ignore errors from admin sessions.
return null;
}
return notice;
});
`

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

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

$3

With the keysBlocklist option, you can specify a list of keys containing
sensitive information that must be filtered out:

`js
const airbrake = new Notifier({
// ...
keysBlocklist: [
'password', // exact match
/secret/, // regexp match
],
});
`

$3

To use the request HTTP client, pass
the request option which accepts a request wrapper:

`js
const airbrake = new Notifier({
// ...
request: request.defaults({ proxy: 'http://localproxy.com' }),
});
`

$3

@airbrake/node attempts to automatically instrument various performance
metrics. You can disable that behavior using the performanceStats option:

`js
const airbrake = new Notifier({
// ...
performanceStats: false,
});
`

$3

addPerformanceFilter allows for filtering performance data. Return null in
the filter to prevent that metric from being reported to Airbrake.

`js
airbrake.addPerformanceFilter((metric) => {
if (metric.route === '/foo') {
// Requests to '/foo' will not be reported
return null;
}
return metric;
});
``

[project-idkey]: https://s3.amazonaws.com/airbrake-github-assets/airbrake-js/project-id-key.png