Getting Things Set Up With New Relic Browser Source Maps

Source map support for New Relic Browser is now generally available. So when you want to start seeing the original source code for JavaScript errors in the apps you monitor with New Relic, it is pretty easy to get started. Generally speaking, you need to do three things:

1. Generate source maps as part of your bundling process.
2. Set up a unique identifier.
3. Publish your source maps to New Relic.

1. Generate source maps

The process of generating source maps varies from one build system to another. With webpack, for example, your config.devtool should be ‘source-map’ for your production build. (If you use Browserify, use the --debug and --source-map-include-sources options on the command line or enable debug in the options.) The sample code below shows how to use webpack to create the source map when building in production environments.

2. Set up a unique identifier

Because the source map changes every time you update the source code, it’s important to know which release caused the error. The easiest way to do this is to integrate the publishing of source maps into your build process. That way, every time you release a new version of your frontend code, you send a source map to New Relic, which is then used to unminify errors from that specific release.

If the URL of the JavaScript bundle is different each time you deploy your code, no further information is required. Our recommended best practice is to append a hash to the file name to create a unique file name for each build (i.e., app-155567618f4367cd1cb8.js), which makes for a straightforward versioning process. Many organizations already use a unique build number, md5 hash, or Git SHA checksum in the URL for cache-busting purposes. Additionally, some frontend deployment tools use the Jenkins build number, or the Git commit SHA in the filename of the deployed code, which is enough to uniquely determine the release that caused the error, and is the easiest way to get this set up.

However, in case the URL is not uniquely identifiable, New Relic also provides an API for uniquely identifying releases to the Browser agent and connecting that to the source maps for the release.

For example, one New Relic team uses a script on its Jenkins CI server that not only builds the frontend assets, but also pulls information from environmental variables that exist only at build time, to create a dynamic JavaScript file with the build version identifier, which is then bundled with the application. This file runs in the user’s browser and calls the New Relic source map API to pass this unique identifier for this release. As soon as possible after the page loads, newrelic.addRelease is called, so that all errors seen by the agent will be associated with that version of the JavaScript code. This could also be done with using a unique build number, md5 hash, or Git SHA checksum in the place of the environmental variable. This overall setup takes a few more steps compared to using a unique asset name as we recommend above, though we built our API to make sure we could support these additional configurations.

3. Publish your source maps

Using the API methods described in our source map support announcement blog post, you have a number of different ways to publish your source maps to New Relic: using our npm module or with a cURL command. You have flexibility to use whatever works best with your build systems. If you’re looking to check what URL your JavaScript files use, New Relic Browser automatically associates all captured errors with its originating URL, which you can see as part of every JavaScript error:

You’ve just integrated source maps as part of your build process. Great job!

Don’t miss Announcing Source Map Support for New Relic Browser. And stay tuned: An upcoming post will walk you through New Relic’s frontend software architecture and Jenkins build process, and how we’ve included source maps as part of this flexible workflow.