Overview

If you minify your JavaScript code for use in production, you've probably noticed that the stacktraces you see in Rollbar reference the minified code, not the original source code.

This feature makes use of JavaScript Source Maps to translate the minified code references back into the original source. The result is:

in stack traces, you'll see the original source filename, line number, method name, and code snippet

error grouping should be more resilient to code changes

Basic Setup

For the minified-to-source translation to work, we need:

A stack trace with column numbers

You'll get one of these if you give Rollbar an Error object, in a browser that provides column numbers. Like this:

try{thrownewError("Something went wrong");}catch(e){Rollbar.error(e);}

As far as we can tell, this currently works for caught errors in Chrome, IE10, and Firefox.

Uncaught errors (reported by the browser's top-level error handler, window.onerror) will have column numbers in the newest versions of Chrome and Firefox. The HTML5 Spec has been updated to require this, so other browsers may add this support in the future.

A source map file, along with (optionally) any or all of the original source files referenced by the source map

We'll call this all together a "source map package". It can either be uploaded directly to us via an API call, or downloaded by us when we encounter errors in minified files that source map url comment directives.

Step 1: Enable source maps

Add these two parameters to the _rollbarConfig object that you have included in the on-page javascript snippet:

var_rollbarConfig={// add these new params:payload:{client:{javascript:{source_map_enabled:true,code_version:"some version string, such as a version number or git sha",// Optionally have Rollbar guess which frames the error was thrown from// when the browser does not provide line and column numbers.guess_uncaught_frames:true}}}};

If you need to set this configuration after the Rollbar library has been initialized, use Rollbar.configure():

Rollbar.configure({payload:{client:{javascript:{source_map_enabled:true,code_version:"some version string, such as a version number or git sha",guess_uncaught_frames:true}}}});

Step 2: Provide your source map

If your source map is publicly web-accessible, we can download it automatically. Otherwise, you can upload it via our API.

Option A (Easiest): Automatic download

As specified in the Source Map Specification, you should place a comment like the following at the bottom of your minified JavaScript files:

//# sourceMappingURL=URL_TO_SOURCE_MAP

How it works: If we receive a JavaScript error, source maps are enabled, and we don't already have the source map for the current code version, we will schedule an attempt to download it. For each stack frame, we'll first download the minified source file and look for a sourceMappingUrl comment. If it has one, we'll try to download that file and save it as the source map. Then for future errors, we'll use the source map to translate the minified frames back to original frames.

This is the easiest method, but not suitable for all cases (i.e. if you don't want to expose your source map or code to the public web). It is also less reliable than the upload method, since the source map won't be downloaded yet when the first few errors come in. We recommend the upload method for production use.

Option B (Recommended): Upload pre-deploy

At the beginning of your deploy script (before the new code is in production), upload a source map package via our API.

Params

access_token

Your rollbar access token. Should be a post_server_item token (the same one that you use for sending deploy notifications).

version

A string identifying what version of your code this source map package is for. We recommend using the version number/string from your version control system, e.g. a full Git SHA. Note that you will need to pass this same string in the on-page JS snippet, as documented above.

minified_url

The full URL of the minified file. Should start with http: or https:, which we'll strip off.

source_map

The contents of the source map, as a multipart file upload.

(each source file)

(Optional) Param name should be the path to the unminified JS file, as defined in the source map. Value should be the contents of the source file, as a multipart file upload.

Response Codes

200 OK

Upload received successfully.

422 Unprocessable Entity

There was an error validating the upload. The error message should contain details of what went wrong.

We store the source map package by project+version+minified URL. If you upload it more than once, each subsequent upload will overwrite the previous data.

Explanation of the example

In the above example:

Our website is http://example.com

We have a minified javascript file at http://example.com/js/example.min.js

We built our minified file (static/js/example.min.js) and source map (static/js/example.min.map) by running the Closure Compiler from example/. It contains code from static/js/site.js and static/js/util.js.

Here's an example Closure Compiler command run from example/ to generate the above files:

Advanced Setup

Triggering an automatic download

If you're using the Automatic Download method, you can notify our API to trigger a download for each of your minified files. Doing this will reduce the number of errors that the source map isn't applied to (since we'll have a greater chance of downloading the source map before the first error after a deploy occurs).

Params

access_token

Your rollbar access token. Should be a post_server_item token (the same one that you use for sending deploy notifications).

version

A string identifying what version of your code this source map package is for. We recommend using the version number/string from your version control system, e.g. a full Git SHA. Must be the same string as in the on-page JS snippet, as documented above.

minified_url

The full URL of the minified file. Should start with http: or https:

Resources

If you use Gulp, try gulp-rollbar to integrate the upload step into your build process.

FAQ

What if I have more than one minified file?

That's fine -- just upload a source map package for each minified file, each time your code version changes. Note that the code version is global to your project, so you will have to upload the package for each one every time you deploy, even if only one of them changed.

Does it matter what tool I used to build the source map?

It shouldn't, as long as the tool builds source maps adhering the V3 of the source map spec.

It's not working. How can I debug this?

Missing one or both of the config params in the on-page JS snippet. See Step 1 and make sure you're setting both payload.client.javascript.source_map_enabled and payload.client.javascript.code_version

If using the Upload method: code_version used in the one-page snippet does not match the version provided in the upload call

If using the Download method: source map file or minified javascript source files are on a host that's not reachable from the public internet, or are gated behind an authorization wall. Fix: use the Upload method instead.

The Javascript error that you are expecting to be un-minified does not have column numbers, and you haven't enabled guess_uncaught_frames. We need column numbers to be able to apply the source map without guessing--see the first section of "Basic Setup" above for more details.

Some source map generation tools support an alternate representation of the map that combines multiple sub-maps into "sections" within the top level map. Each section can either be embedded source map or a reference to an external source map. Unfortunately, we don't yet support this source map format.

We're working on the tools to make debugging this setup easier, but for now, feel free to contact support and we'll walk you through it. Use the chat box or email support@rollbar.com