Get most out of your JavaScript stack traces using Source Map

Fizer Khan -

We have good news: Atatus automatically fetches and applies source maps to stack traces generated by your errors. This means that you’ll see your original source code, and not minified and/or transpired code.

Source maps are files that map your minified JavaScript code back to your original source code. It allows you to see an unraveled stacktrace for an error, making it far easier to debug. With source maps, you can take advantage of the performance benefits of compressing your JavaScript code, and still be able to debug errors.

Here’s what a stack trace might have looked like before:

Cannot read property 'getSearchParams' of null

    File http://www.acme.com/scripts/128d8e56.scripts.js at line 3, col 3845 in new <anonymous>

    File http://www.acme.com/scripts/d982afc7.modules.js at line 1, col 23333 in at

    File http://www.acme.com/scripts/d982afc7.modules.js at line 1, col 22678 in k

    File http://www.acme.com/scripts/d982afc7.modules.js at line 1, col 22945 in at

Here’s the de-minified version:

Cannot read property 'getSearchParams' of null

    File /app/scripts/list-controller.js at line 16, col 48 in getSearchParams

    File /app/angular-ui/angular-ui.js at line 4018, col 27 in $controller

    File /app/angular-ui/angular-ui.js at line 3959, col 22 in $transclude

    File /app/angular-ui/angular-ui.js at line 3921, col 10 in updateView

Every time we capture an error in your JavaScript application, we’ll use your source maps to show you the exact line of code that crashed in your stacktrace. Basically, For the minified-to-source translation to work, we need:

  1. A stack trace with line and column numbers.
  2. A source map file: It can either be uploaded directly to us via our API call, or shall be downloaded by us, when we encounter errors in minified files that contains source map url location directive.

Option A: Automatic Source Maps Retrieval

For automatic source map retrieval, we need:

  1. The minified JavaScript files as specified in the stack trace must be publicly accessible.
  2. The source map file location to be correctly indicated in the minified JavaScript file using a footer comment. As specified in the Source Map Specification, following comment should be at the bottom of your minified JavaScript files:
//# sourceMappingURL=URL_TO_SOURCE_MAP

3.The source map file itself must be publicly accessible.

How it works: If we receive a JavaScript error, 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 cache it as the source map. Then for future errors, we’ll use the source map to translate the minified frames back to original frames.

Alternatively, instead of hosting source maps yourself, you can upload them directly to Atatus. That leads us to Option B.

Option B: Upload source maps

If you don’t want to expose your source map or code in the public web, you can upload them directly to Atatus. It also means that we won’t need to go to your servers to fetch the files every time an error is received (reducing the load on your servers).

To upload source maps you need to make a request to https://api.atatus.com/api/browser/sourcemap. You can specify the Admin API key for the project, the minified URL, and the source map file and it will be uploaded to our servers. We will then use that uploaded source map file whenever we receive an error event in that URL. You can also specify which version of your app the file applies to. You can learn more about this in the Atatus documentation

curl  https://api.atatus.com/api/browser/sourcemap \
  -H "Authorization: token YOUR_ADMIN_API_KEY_HERE" \
  -F url=http://www.acme.com/js/main.min.js \
  -F sourcemap=@js/main.min.map \
  -F version=version_string_here

Where:

  • url - The full URL of the minified file. Should start with http: or https:, which we’ll strip off.
  • sourcemap - The contents of the source map, as a multipart file upload.
  • version (optional) - A string identifying what version of your code this source map is for. The version number is necessary only if the script file name(url) is same across all deployments. If you set a version number in source map, you must set version in atatus snippet too by atatus.setVersion('version_string_here').

You just learned how Source Maps can save your skin by making your minified code easier to debug in production. Your build tools, most likely, already support source map generation. If not, it won’t take very long to configure, and the results are worth it.

Try Atatus with free 14 day trial – no credit card required. If you have any questions, we’d love to hear from you.