Node.js Integration Guide
Installation
First, install the npm package:
npm install @honeybadger-io/js --save
Then, require the honeybadger module and configure your API key:
const Honeybadger = require('@honeybadger-io/js');
Honeybadger.configure({
apiKey: '[ YOUR API KEY HERE ]'
});
By default Honeybadger will be notified automatically of all unhandled errors which crash your node processes. Many applications catch errors, however, so you may want to set up some additional framework integrations.
Express or Connect Framework
Errors which happen in Express or Connect apps can be automatically reported to Honeybadger by installing our middleware.
In order to function properly our middleware must be added before and after your normal app middleware, but before any other error handling middleware:
app.use(Honeybadger.requestHandler); // Use *before* all other app middleware.
// app.use(myMiddleware);
app.use(Honeybadger.errorHandler); // Use *after* all other app middleware.
// app.use(myErrorMiddleware);
Note: If you use the connect-domain middleware, you do not need to use Honeybadger.requestHandler
because they are essentially the same.
AWS Lambda
Honeybadger can automatically report errors which happen on AWS Lambda:
// Your handler function.
function handler(event, context) {
console.log('Event:', event);
console.log('Context:', context);
throw(new Error('Something went wrong.'));
console.log("Shouldn't make it here.");
}
// Build and export the function.
exports.handler = Honeybadger.lambdaHandler(handler);
Check out our example Lambda project for a complete example.
Reporting Errors
Honeybadger reports unhandled exceptions by default. You can also manually notify Honeybadger of errors and other events in your application code:
try {
// ...error producing code...
} catch(error) {
Honeybadger.notify(error);
}
See the full documentation for more options.
Identifying Users
Honeybadger can track what users have encountered each error. To identify the
current user in error reports, add a user identifier and/or email address with
Honeybadger.setContext
:
Honeybadger.setContext({
user_id: 123,
user_email: 'user@example.com'
});
Tracking Deploys
Honeybadger can also keep track of application deployments, and link errors to
the version which the error occurred in. Here’s a simple curl
script to record
a deployment:
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="git SHA/project version" \
HONEYBADGER_API_KEY="project api key" \
curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&api_key=$HONEYBADGER_API_KEY"
Be sure that the same revision is also configured in the honeybadger.js library. Read more about deploy tracking in the API docs.
Uncaught Exceptions
Honeybadger’s default uncaught exception handler logs the error and exits the
process after notifying Honeybadger of the uncaught exception. You can change
the default handler by replacing the afterUncaught
config callback with a
new handler function. Honeybadger will still be notified before your handler
is invoked. Note that it’s important to exit the process cleanly if you
replace the handler; see Warning: using ‘uncaughtException’
correctly
for additional information.
Examples
Honeybadger.configure({
afterUncaught: (err) => {
doSomethingWith(err);
process.exit(1);
}
});
Disable Honeybadger’s uncaught error handler
To disable Honeybadger’s handler entirely (restoring Node’s default behavior for uncaught exceptions), use the enableUncaught
option when calling Honeybadger.configure
for the first time:
Honeybadger.configure({
apiKey: '[ YOUR API KEY HERE ]'
enableUncaught: false
});
Sample Application
If you’d like to see the library in action before you integrate it with your apps, check out our sample Node.js/Express application.
You can deploy the sample app to your Heroku account by clicking this button:
Don’t forget to destroy the Heroku app after you’re done so that you aren’t charged for usage.
The code for the sample app is available on Github, in case you’d like to read through it, or run it locally.