Javascript (Browser & Node.js)

Rollbar SDK for client-side Javascript & Node.js

Add Rollbar.js to your Node.js or browser-based JavaScript projects to automatically capture and report errors in your applications.

Quick Start

The docs linked below will help you get Rollbar up and running quickly in various JS platforms and toolchains.

Browser JS quick start

Node.js quick start

React quick start

Angular quick start

Vue.js quick start

Requirejs information

UMD information

Browserify information

Webpack information

AWS Lambda information

Rollbar.js supports Backbone.js with no additional configuration required

Community maintained Ember library: ember-rollbar-client by Maciej Kwaśniak

Community maintained Ember library: ember-cli-rollbar by Dave Wasmer

The following browser versions are supported on all major desktop and mobile operating systems:

IE 8+

Firefox 40+

Chrome 44+

Edge 10+

Opera 12+

Safari 8+

Source Maps

If you minify your JavaScript in production, you'll want to configure source maps so you get meaningful stack traces. See the source maps guide for instructions.

Usage

In addition to catching top-level errors, you can send caught errors or custom log messages. All of the following methods are fully-asynchronous and safe to call anywhere in your code after the <script> tag.

// Caught errors
try {
  doSomething();
} catch (e) {
  Rollbar.error("Something went wrong", e);
}

// Arbitrary log messages. 'critical' is most severe; 'debug' is least.
Rollbar.critical("Connection error from remote Payments API");
Rollbar.error("Some unexpected condition");
Rollbar.warning("Connection error from Twitter API");
Rollbar.info("User opened the purchase dialog");
Rollbar.debug("Purchase dialog finished rendering");

// Can include custom data with any of the above.
// It will appear as `message.extra.postId` in the Occurrences tab
Rollbar.info("Post published", {postId: 123});

// Callback functions
Rollbar.error(e, function(err, data) {
  if (err) {
    console.log("Error while reporting error to Rollbar: ", e);
  } else {
    console.log("Error successfully reported to Rollbar. UUID:", data.result.uuid);
  }
});

To set configuration options at runtime, use Rollbar.configure:

// Set the person data to be sent with all errors for this notifier.
Rollbar.configure({
  payload: {
    person: {
      id: 456,
      username: "foo",
      email: "foo@example.com"
    }
  }
});
// Unset the person data to be sent with all errors for this notifier.
Rollbar.configure({
  payload: {
    person: {
      id: null
    }
  }
});

There are configuration changes needed to use Rollbar.js with Segment, use Rollbar.js in a Chrome Extension, or use Rollbar.js inside an embedded component.

Upgrading from Previous Versions

If you are upgrading from node_rollbar, please see here.

The simplest approach to upgrading from one version of to the next is to replace the snippet with the one in this document. Depending on the timing of the release and CDNJS latency, it is possible that the snippet has a URL pointing to the full Rollbar library which will return a 404. This happens because of how CDNJS operates. The URL in the snippet is of the form:

https://cdnjs.cloudflare.com/ajax/libs/rollbar.js/X.X.X/rollbar.min.js

where X.X.X would be replaced with the version number of the latest release. Prior to pushing to production, we recommend ensuring that the URL with the version you are upgrading to returns a proper response. This is because new releases may take a few hours to get published on CDNJS.

Managing Sensitive Data

GDPR & HIPAA

If you are required to comply with GDPR or HIPAA, we have a few recommendations for how to manage the sensitive data you may be sending to Rollbar. We recommend setting up person tracking, customizing your data retention period (more info on this here), anonymizing or not capturing IP addresses, and scrubbing sensitive data before sending Rollbar items. For HIPAA compliance, we additionally recommend transforming the payload before sending Rollbar items, as sometimes sensitive data may be found in stack traces.

For information on setting up person tracking, please see here. You can simply send only the person.id and no other identifying information, such as an email address. If you have already sent Rollbar sensitive person data and wish to delete it, please see our documentation on deleting person data here.

You may also configure the captureIp setting in your config to either not capture IP addresses (by setting captureIp to false) or have the SDK do a semi-anonymization on the captured IP address by masking out the least significant bits (by setting captureIp to 'anonymize').

Rollbar.configure(
  {
    enabled: true, 
    captureIp: 'anonymize', 
    payload: {
      person: {
      id: 12345
      }
    }
);

Scrubbing Items

If you need to scrub certain data in the payload before sending it to Rollbar, there are a few options for how to go about doing so. To scrub telemetry data, please see here. To scrub other keys/fields/query parameters in the payload, you can use the scrubFields configuration option. For more detailed information about scrubFields and what keys in the payload are scrubbed by default, please see the Configuration Reference.

Rollbar.configure({scrubFields: ['creditCardNumber']});

Transforming the Payload

If you would like to change some of the data in the payload before sending an item to Rollbar, you may do so via the transform function. For more detailed information on transform, please see the Configuration Reference.

// For example, to set a custom fingerprint:
var transformer = function(payload) {
  payload.fingerprint = 'my custom fingerprint';
};

Rollbar.configure({transform: transformer});

Ignoring Items

If you would like to have the client ignore an item and not send it to Rollbar, you can use the checkIgnore function. It may be used to ignore uncaught exceptions based on its return value. For more detailed information on checkIgnore, please see the Configuration Reference.

Rollbar.configure({checkIgnore: function(isUncaught, args, payload) {
    // ignore all uncaught errors and all 'debug' items
    return isUncaught === true || payload.level === 'debug';
}});

You may also ignore items with specific exception messages using the ignoredMessages configuration option. For more information on that, please see here.

Features

Telemetry

We can capture a sequence of events leading up to an error/log message to enhance your visibility into the state of your application when something happens as a default. For information on how to configure and disable this, see Telemetry.

Disable sending error data to Rollbar

If you don't want to send error data to Rollbar, just set the enabled flag to false for each notifier instance.

Rollbar.error("This will be reported to Rollbar");
Rollbar.configure({enabled: false});
Rollbar.error("This will *not* be reported to Rollbar");

Ignoring specific exception messages

If you want to ignore a specific exception message, say for a third-party browser plugin that is throwing errors, you can add the message to the ignoredMessages array, and Rollbar will ignore exceptions matching those messages.

Rollbar.configure({ignoredMessages: ["Can't find Clippy.bmp. The end is nigh."]});

Person Tracking

If your application has authenticated users, you can track which user ("person" in Rollbar parlance) was associated with each event.

// To track the current user in Javascript you can alter your `_rollbarConfig`
// like so:

var _rollbarConfig = {
  // The usual
  payload: {
    // The usual
    person: {
      id: 42, // required 
      username: 'dadams',
      email: 'dadams@example.com'
    }
  }
}

// If you've already initialized Rollbar and need to set the user *after*
// initialization has already occurred you can use the `configure` method:

Rollbar.configure({
  payload: {
    person: {
      id: 456, // required
      username: "foo",
      email: "foo@example.com"
    }
  }
});

Note: in Rollbar, the id is used to uniquely identify a person; email and username are supplemental and will be overwritten whenever a new value is received for an existing id. The id is a string up to 40 characters long.

By default we only attempt to capture the id for a user. Use the boolean configuration options captureEmail and captureUsername to change this behavior.

Handling uncaught rejections

Rollbar.js supports the ability to catch and report unhandled Promise rejections, that is, Promise failures that do not have a corresponding .then(null, function(e) {}) handler. This support is best used for handling rejected exceptions, although rejected primitives will report (without a stack trace).

If you decide to use this option, you may also want to combine it with the checkIgnore configuration option to filter 'noisy' rejections, depending on the extent to which your application handles Promise failures, or rejects with a lot of primitives.

Verbose option

If you would like to see what is being sent to Rollbar in your console, use the verbose option.

Rollbar.configure({verbose: true, // This will now log to console.log, as well as Rollbar});

Synchronous option

By default, the snippet loads the full Rollbar source asynchronously. You can disable this, which will cause the browser to download and evaluate the full Rollbar source before evaluating the rest of the page.

More information can be found here and here.

Rollbar.configure({async: false});

Dealing with adblocker / browser extension exceptions

Unfortunately, some very popular browser extensions may modify a user's copy of your website in such a way as to break its functionality. This can result in Rollbar reporting exceptions that are not a direct result of your own code. There are multiple approaches to dealing with this issue, the simplest of which is covered in related documentation.

Configuration Options

For a listing of all configuration options available, see Configuration and Method Reference.

Plugins

The support for the different frameworks and libraries is organized into different plugin definitions. The plugins architecture documentation can be found in Plugins.

Help / Support

If you run into any issues, please email us at support@rollbar.com

For bug reports, please open an issue on GitHub.