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
Example - Generate a source map file in the output
$ babel src --out-dir lib --source-maps
2. Use sourceMappingURL comment
Make sure that the transpiled source code includes the magic
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
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.
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).