Opbeat is joining forces with Elastic – Learn more about Elastic APM

Announcing Source Map Support in Node.js

Today we released v4.13.0 of the Opbeat Node.js Agent. It includes an exciting new feature that I’ve been looking forward to releasing for quite a while: Source map support for our Node.js stack. Learn how to prepare your source maps to work well with Opbeat in this blog post.

As always, you can check the CHANGELOG.md file in the root of our GitHub repository to see the important changes in each new release. But let’s get right to it:

Why source maps?

Opbeat have always shown snippets of your source code to help explain what’s going on in your application. For instance, when an error is captured, we show you a snippet of the offending code that caused the error. Or when highlighting performance issues in your application, we show you a code snippet of the actual location where the slow code is being executed.

But since it’s becoming increasingly popular to use tools like Babel to transpile source code before deploying it to production, we need to be able to understand the link between the actual code running in production and your original source code. And we need to be able to display that original source code in the code snippets in Opbeat.

Getting started with source maps

To leverage our source map support, simply make sure you do the following when deploying (the examples below use Babel, but any tool that generates source maps will work):

1. Generate source maps

Generate a source map when transpiling the source code. In Babel, you can use the --source-maps option.

Example - Generate a source map file in the output lib directory:

$ babel src --out-dir lib --source-maps

2. Use sourceMappingURL comment

Make sure that the transpiled source code includes the magic sourceMappingURL comment:

//# sourceMappingURL=/path/to/file.js.map

The above Babel command will add that for you automatically.

If you use --source-maps inline, the sourceMappingURL will include a base64 encoded version of the source map instead of a path to a .map file. Opbeat supports both variations.

3. Deploy your source maps

Make sure the source maps are deployed to your production server along with the transpiled source code.

4. Access to the original source code

Opbeat needs some form of access to the original source code to be able to show you meaningful snippets.

One way is to simply embed the original source code directly in the source map using the sourcesContent property. This is the default behavior when generating source maps using Babel.

If Opbeat can’t find the source code embedded inside the source map, we’ll follow the paths in the sources array and look for the source code on disk. This, of course, requires that you deploy the original source code to your production servers along with the transpiled version.

Finally, if the original source code is neither embedded in the source map nor found on disk, we’ll try to pull it from your git repo if you have given us access to do this. This also requires that you use the release tracking feature of Opbeat. Otherwise, we will not know which git revision to use as reference.


That’s it. If you have any feedback or questions related to our source maps support (or anything else for that matter), don’t hesitate to reach out by contacting support.

Upgrade now

To get source map support in your app, make sure you are running version 4.13.0 or higher of the Opbeat Node.js agent. If you still haven’t upgraded to version 4.x, simply follow our upgrade guide (it’s really, really simple).

About the author
Thomas Watson is our Node.js lead, speaker and commited open source contributor.
You can follow him on Twitter or GitHub.