Breadcrumbs Come to Node.js

Last year we announced a major new Sentry feature, breadcrumbs, supported by our biggest client libraries with one notable omission: Node error monitoring.

This wasn’t an oversight. Node’s asynchronous nature and cooperative concurrency made breadcrumbs tricky to implement properly. To make it happen, we went back to the drawing board and reworked the Node client library’s internals and API, resulting in:

• Proper asynchronous context tracking — think thread-local storage, but in a way that fits Node’s concurrency model
• Callbacks better following Node’s “errback” convention and firing more intuitively
• An API more closely resembling that of our browser JavaScript client; if you’ve used Raven-js before, Raven-node should feel familiar

But the most exciting part is that our Node client joins our browser JavaScript, Python, and PHP clients in having automatic breadcrumb support!

What are Breadcrumbs?

Breadcrumbs are a trail of events that occurred in your application leading up to a captured error. They can be as simple as generic logging messages, or they can contain rich metadata about the state of your application: network requests, database queries, UI events, navigation changes, or even earlier occurring errors.

Breadcrumbs can be incredibly helpful in reproducing the steps that led to the error you’re debugging. They add critical context to errors that a stack trace alone can’t provide. Once you use them, you won’t go back.

Getting Started

Get the latest version of Raven-node, 1.1.1:

$ npm install raven@1.1.1

Import and initialize the client library with automatic breadcrumbs enabled:

var Raven = require('raven');
Raven.config('your-dsn', {
  autoBreadcrumbs: true
}).install();

Without any further setup, we’ll now automatically record a handful of useful breadcrumbs:

• HTTP(S) requests via Node’s core modules
• Log statements via console.log, console.warn, etc
• PostgreSQL queries via the pg module

You can record your own custom breadcrumbs, too. In the example Express app below, a breadcrumb is captured to record the results of a cookie parsing step:

app.use(Raven.requestHandler());

// custom Express middleware
app.use(function (req, res, next) {
  // grab cookie headers, do some parsing
  Raven.captureBreadcrumb({
    message: 'Parsed cookie',
    category: 'log',
    data: {
      cookie: parsedCookie
    }
  });
  next();
});

app.get('/', function (req, res, next) {
  // do some route handling, knowing that if an exception happens here,
  // your parsed cookie breadcrumb will be associated with it in Sentry
});

app.use(Raven.errorHandler());

The Node client library’s middleware for Express error monitoring ensures that breadcrumbs captured in a route handler or middleware are associated with the correct request. You might use your own breadcrumbs to track major steps in your request handling pipeline, or to associate data that’s particularly useful for debugging.

For a more detailed summary of recent changes, take a look at the forum post announcement. Our Node client docs have also been updated to reflect the recent API changes and our new recommended usage patterns.

Looking Forward

Breadcrumbs to debug Node are still in the early phase, so we’re looking for feedback and suggestions on anything that we can make better or more useful. Our current plans are to tie automatic breadcrumbs into more database drivers and to eventually enable automatic breadcrumbs by default.

If you have feedback or run into trouble, let us know by posting on our forum or opening an issue on the raven-node GitHub repository.