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.
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.
- 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
Add the Node Airbrake package to your package.json
:
{
"dependencies": {
"airbrake": "^2.1.3"
}
}
Invoke the following command from your terminal:
npm install airbrake
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);
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;
});
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 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);
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.
var airbrake = require('airbrake').createClient("your project ID", "your api key");
app.use(airbrake.expressHandler());
var airbrake = require('airbrake').createClient("your project ID", "your api key");
app.use(app.router);
app.use(airbrake.expressHandler());
var airbrake = require('airbrake').createClient("your project ID", "your api key");
app.error(airbrake.expressHandler());
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;
}
});
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 toerror
) - request.url: (
err.url
, seeairbrake.url
); - request.component: (
err.component
string if set); - request.action: (
err.action
string if set); - request.cgi-data: (
process.env
, merged all other properties oferr
) - 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.
This client supports Airbrake's deployment tracking:
var airbrake = require('airbrake').createClient("your project ID", "your api key");
var deployment = {
rev: '98103a8fa850d5eaf3666e419d8a0a93e535b1b2',
repo: 'git@github.com: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.
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.
Your application's Airbrake project ID.
Your application's Airbrake API key.
The name of the server environment this is running in.
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.
The root directory of this project.
The version of this app. Set to a semantic version number, or leave unset.
The protocol to use.
The timeout after which to give up trying to notify Airbrake in ms.
The HTTP/HTTPS proxy to use when making requests.
Additional request options that are merged with the default set of options that are passed to request
during notify()
and trackDeployment()
.
Names of environment variables to send.
Names of environment variables to filter out.
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.
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.
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.
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.
Notifies Airbrake about a deployment. params
is an object with the following
options:
env:
The environment being deployed, defaults toairbrake.env
.user:
The user doing the deployment, defaults toprocess.env.USER
.repo:
The github url of this repository. Defaults togit config --get remote.origin.url
.rev:
The revision of this deployment. Defaults togit rev-parse HEAD
.
The maximum size of an exception is 64KB. Exceptions that exceed this limit will be truncated to fit the size.
The library was originally created by Felix Geisendörfer. The project uses the MIT License. See LICENSE.md for details.