This post is sponsored by Rollbar, a Node Knockout 2013 service sponsor.

Rollbar is an error monitoring and analytics service that has plugins for a wide variety of languages and frameworks including Node.js, client-side Javascript, Rails, Django, PHP, and others. Thousands of developers use Rollbar to find errors in their apps and fix them faster.

Let’s create a simple server with some bugs to get started.

Installation

npm install rollbar
npm install express

Middleware

Most servers written in node use the Express.js framework which is built on top of Connect.js and makes it really easy to write and include custom middleware. Let’s include Rollbar’s error handling middleware and record our first error.

var express = require('express'),
    rollbar = require('rollbar');

var app = express();

app.use(app.router);

// Make sure this is below the app.router
app.use(rollbar.errorHandler('ACCESS_TOKEN'));

app.get('/', function(req, res) {
      throw new Error('Hello World!');
});

console.log('browse to http://localhost:8080/ and then to your ' +
    'rollbar project');
app.listen(8080);

Create a Rollbar project

If you haven’t created a project on Rollbar yet, head over to https://rollbar.com/signup and create a free account. Then, replace the ACCESS_TOKEN in the code above with your server-side access token.

Screenshot of post-signup page

Next, you should be able to run your server and see the following in your browser at http://localhost:8080:

Screenshot of node error page

And now in Rollbar:

Screenshot of Rollbar dashboard

Recording things other than errors

Recording errors is great but sometimes we just want to do the equivalent of console.log() and have it stored in one place even when running on multiple production servers.

Rollbar makes this dead simple. Just pass in the string to send over along with an optional level (or it will default to error). Choices for level include debug, info, warning, error and critical.

rollbar.reportMessage('Why the heck is this not working??? ' + (typeof myVar), 'debug');

And if you want to send over some useful request context…

rollbar.reportMessage('Oooooh, is it because the cookie is missing?', 
    'debug', req);

Tracking disaster with UncaughtException

Node.js has a super-handy and potentially dangerous event that it will trigger when there’s an uncaught exception at the top-most level of your code. These are the types of things that will kill your server so it’s good to know when and why they happened.

Thankfully, node.js makes it super-simple to track these and so does Rollbar.

rollbar.handleUncaughtExceptions();

UncaughtException example

var rollbar = require('rollbar');
rollbar.handleUncaughtExceptions('ACCESS_TOKEN');

var foo = bar();

Screenshot of Rollbar instance

More control

It’s important to have full control over when error reporting happens. Rollbar provides a few different options for when to report errors and messages back to Rollbar.

setInterval

This is the default handler if one is not specified. It will create a Timer function which will execute every N seconds, (where N is configurable using the handlerInterval option.)

e.g. Queue up any errors/messages and send to Rollbar every 10 seconds

rollbar.init("ACCESS_TOKEN", {handler: "setInterval", handlerInterval: 10});

or

app.use(rollbar.errorHandler("ACCESS_TOKEN", 
    {handler: "setInterval", handlerInterval: 10});

nextTick

This handler will schedule a callback which will send any queued up errors/messages to Rollbar on the next tick of the javascript runtime. This is useful for ensuring that any callbacks passed into the handleError or reportMessage functions is called asynchronously.

rollbar.init("ACCESS_TOKEN", {handler: "nextTick"});
rollbar.reportMessage("Record me asynchronously", "debug", function(rollbarErr) {
    if (err) {
        console.log("Problem sending message to rollbar: " + rollbarErr);
    } else {
        console.log("Recorded message to rollbar");
    }
});

inline

This handler will send any recorded messages or errors to rollbar as soon as they are processed. This is useful for debugging complex code and making sure that important errors are sent to Rollbar as soon as possible.

rollbar.init("ACCESS_TOKEN", {handler: "inline"});
rollbar.reportMessage("DATABASE IS DOWN!", "critical", function(rollbarErr) {
    if (err) {
        console.log("Problem sending message to rollbar: " + rollbarErr);
    } else {
        console.log("Recorded message to rollbar... shutting down");
        rollbar.shutdown();
        process.exit(1);
    }
});

Changing handler types

The Rollbar notifier also allows you to switch handler types whenever you want. If you notice that the queue is building up or you need to start pushing errors to Rollbar as soon as they’re available, it’s as simple as:

rollbar.changeHandler("inline");

or

rollbar.changeHandler("setInterval");

Everything is asynchronous…

Under the covers, the Rollbar node notifier is completely asynchronous and provides the ability to pass around callbacks that are executed after any i/o occurs.

e.g. Trigger a callback to make sure a message was queued to be sent to Rollbar:

rollbar.reportMessage("Something important", "info", function(rollbarErr) {
    // rollbarErr will be null if the message was queued
});

e.g. Execute some code after rollbar is cleanly shutdown:

rollbar.shutdown(function(rollbarErr) {
    // this function will be called after all queued items were sent 
    // to Rollbar or an error occurred
});

Next Steps

That’s really all there is to it. The above instructions should cover 90% of the average use cases.

Happy Hacking!

For the remaining 10%

If you’re using Coffeescript or another compiles-to-javascript language, you may want to set up Source Maps so that we can show correct file/line numbers in stack traces.

We’re continually adding new features to Rollbar and all of the notifiers. If you’re interested, take a look at the api.js code for some more functionality or at our API docs for even more.

Send us an email at support@rollbar.com or a pull request for bugfixes and/or new features!

  1. nodeknockout posted this
Blog comments powered by Disqus