Javascript (Browser & 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.

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

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 and custom data to be sent with all errors for this notifier.
Rollbar.configure({
  payload: {
    person: {
      id: 456,
      username: "foo",
      email: "[email protected]"
    },
    custom: {
       customertype: "premium"
    }
  }
});
// 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. The URL in the snippet is of the form:

Rollbar.js 2.15.0 and later

https://cdn.rollbar.com/rollbarjs/refs/tags/vX.X.X/rollbar.min.js

Rollbar.js earlier than 2.15.0

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.

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 and scrubPaths configuration options. For more detailed information about scrubFields, scrubPaths, and what keys in the payload are scrubbed by default, please see the Configuration Reference.

Rollbar.configure({
  scrubFields: ['creditCardNumber'],
  scrubPaths: ['request.query_string']
});

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 example, to change the environment:
var transformer = function(payload) {
  payload.environment = 'backend-2';
};

Rollbar.configure({transform: transformer});

Starting in v2.23.0, async transform functions are also supported by returning a Promise or thenable from your transform function.

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");

Reporting CSP (Content Security Policy) error data to Rollbar

Browsers use Content Security Policy directives (provided in the HTTP response header, or in a meta tag) to govern what resources can and can't be loaded. When an attempt to load a resource is blocked, an error is written to the dev console, but no exception is thrown. Instead, the browser sends a contentsecuritypolicy event.

Rollbar listens for these events and records the error as a telemetry event, and if errorOnContentSecurityPolicy is set, sends a Rollbar error occurrence.

To enable/disable the feature, use these autoInstrument flags:

config.autoInstrument = {
  contentSecurityPolicy: true, // enables telemetry tracking, enabled by default
  errorOnContentSecurityPolicy: true // send a Rollbar error message, disabled by default
}

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."]});

ignoredMessages must be an array of strings and/or regular expression objects. Both strings and regular expression objects are treated as case insensitive regular expressions.

Given the message:

Rollbar.info("This is an ignored message")

Any of the following examples will match successfully.

[
  "This". // substring match
  "this", // case insensitive match
  "^This is an .{7} message$", // valid regular expression syntax
  /^This is an .{7} message$/  // valid regular expression object (no string quotation marks)
]

Because ignoredMessages matchers are actually regular expressions, when matching a literal string, some characters must be escaped. Characters that may need to be escaped include: ^, $, ., |, ?, *, +, (), [], and {}. In order for these to remain escaped in the regex matcher, they should be doubled escaped when passed in the config.

Note: When passing a valid regular expression object there are no quotation marks.

Example:

Rollbar.info("Match these characters: (*+?)")

This will match successfully:

Rollbar.configure({ignoredMessages: ["\\(\\*\\+\\?\\)"]}); // Substring match. All literals are double escaped.

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: '[email protected]'
    }
  }
}

// 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: "[email protected]"
    }
  }
});

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.

UUIDs

The Rollbar.js SDK generates a UUID for every event reported back to the Rollbar platform. This UUID can be used to track customer issues, correlate exceptions to automated test sessions, and more. In Javascript, when the item/occurrence object is created, it will have a property called uuid with the value for that given object. The value is set in the utility.js file.

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 [email protected]

For bug reports, please open an issue on GitHub.