Private source maps

Private source maps are a core feature available on all paid plans along with public source maps.

This guide assumes you have already installed Airbrake in your JavaScript app.

When to use private source maps

If you minify your JavaScript or Node.js code and do not publicly host your source maps, then you should use Airbrake’s private source maps to get properly de-minified backtraces for your Airbrake errors. To get started, generate your source map then upload and associate it to the minified file according to the steps below.

Generating source maps

Generating source maps can be done with minifying packages like uglifyjs, webpack, or terser (for ES6+ support). Here is an example that minifies and creates a source map for an app.js file:

uglifyjs app.js -o app.min.js -c -m \
  --source-map "root='https://example.com/',url='app.min.js.map'"

This command will create two new files, a minified app.min.js file and a source map named app.min.js.map. The source map file is what we will be uploading to Airbrake.

Uploading source maps

Continuing on with our above example, the next steps assume the minified version of app.js is publicly available at https://example.com/app.min.js.

The bottom of the app.min.js file should have a comment with the name of the of the source map.

//# sourceMappingURL=app.min.js.map

Upload your source map

You can use our CLI to upload source maps to Airbrake. The following curl command assumes that your source map file app.min.js.map is in the current directory:

airbrake sourcemaps create --project-id PROJECT_ID \
    --from-file 'app.min.js.map'
    --name 'unique-name'
    --pattern '%app.min.js'

Note: PROJECT_ID will need to be switched out for the real value from your project.

Pattern matching option

The optional pattern="%/app.min.js" is a SQL LIKE pattern and it tells Airbrake to apply the uploaded source map to all files that match the pattern. An underscore (_) in pattern stands for (matches) any single character; a percent sign (%) matches any sequence of zero or more characters.

If pattern is not provided Airbrake will automatically generate one using file field from the uploaded source map by prepending it with %/. For example, airbrake.iife.js.map has file defined as airbrake.iife.js so the autogenerated pattern will be %/airbrake.iife.js. The same can be achieved with pattern="%/${file}". Useful patterns can be:

  • %/dist/${file} to match file in some folder.
  • %domain.com/%/${file} to match file on some domain.

Custom source map URLs

If you need more control over which uploaded source map is used, please check out custom source map URLs.

Viewing your uploaded source maps

You can view a list of the source maps that you’ve uploaded to Airbrake using our CLI:

airbrake sourcemaps list --project-id PROJECT_ID

Note: PROJECT_ID will need to be switched out for the real value from your project.

Deleting updloaded source maps

To delete a source map that you’ve uploaded to Airbrake, use the sourcemap delete command via our CLI:

airbrake sourcemaps delete --project-id PROJECT_ID --sourcemap-id 123,345,567

This deletes three source maps with the IDs: 123, 345, and 567.

Troubleshooting

Source map file size limit

Public and private source maps have a file size limit of 32MB. source maps greater than 32MB will return a 400

{"code":400,"type":"Bad Request","message":"http: request body too large"}

Example of how Airbrake looks for your source maps

  • Your project sends an error to Airbrake
  • Airbrake processes the error and sees a filename http://localhost:3000/javascript/app.js
  • Airbrake tries to download http://localhost:3000/javascript/app.js to extract source map location, but it can’t since that file is on localhost
  • Airbrake then checks if you’re using custom source map URLs and looks at notice.context["sourceMaps"] in case you manually associated a source map with the http://localhost:3000/javascript/app.js file
  • From the sourceMaps value, Airbrake discovers that the source map is located at http://localhost:3000/javascript/maps/app.js.map, but Airbrake can’t download it since, again, it’s localhost
  • Airbrake then finally checks if you manually uploaded that file using this private source map feature