New Relic Browser supports the uploading of source maps, which are used to un-minify error stack traces on the JS errors page. This document explains how to use the API to publish (upload) source maps to Browser.
Access to this feature depends on your subscription level.
Prepare for using the source map API
In order to upload source maps to New Relic Browser via the API, you'll need this information:
- An admin API key for the New Relic account
- The New Relic application ID for the deployed app
- The full JavaScript file URL
- Optionally, if the JavaScript URL doesn't automatically have release info appended to it, the release name and ID
- What is the JavaScript URL?
-
Every time the agent captures an error in your code, it's associated with the URL of the JavaScript in which it occurred. This is the
src
attribute of the script tag in your HTML. This full JavaScript URL is required when sending source maps to Browser.You can find the URL for an error's JavaScript file in New Relic Browser, on the JS errors page. See New Relic Browser source maps for more on finding these errors in the UI.
- Is a release name and ID required?
-
Many organizations include a version number or hash in the JavaScript URL. This is generally added to "bust" caches to ensure your users get the most recent version of your code. This type of URL might look something like:
https://example.com/assets/application-59.min.js
https://example.com/assets/bundle-d6d031.min.js
https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.js
If your app's URLs automatically have the version info appended to it, the Browser agent has everything it needs in order to match errors with your code. You can move ahead to generating source maps.
If this doesn't apply to you, and JS URLs do not have version info appended, you’ll have to assist the agent by specifying a release name and ID with the API.
- Are there limits to source map uploads?
-
There is no limit to the overall number of source maps you can upload. However, the API is rate-limited:
- You can upload a maximum of 100 source maps per minute
- You can upload a maximum of 5,000 source maps per day
Source map files can be a maximum of 50Mb in size.
Push source maps to New Relic
Now that you have one or more source maps, you are ready to publish it to New Relic Browser. You can use any of these methods to send source maps to Browser:
- Use the New Relic npm module with the API via the command line or via a client-side JavaScript build/deploy script like Gulp or Grunt.
- Use API cURL commands.
- Use the Browser UI.
Use npm module via command line or client-side script
The easiest and recommended way to upload source maps to Browser is to use the our new @newrelic/publish-sourcemap npm module. It provides a command line tool and Javascript API to accomplish this task. More documentation is available in the npm repo.
Here are some examples of using the npm module via the command line.
The following examples are for US accounts. For EU accounts, the endpoint is https://sourcemaps.service.eu.newrelic.com
. For more information, see Introduction to the EU region data center.
- npm command line: Publish
-
Here's an example of uploading source maps using the npm module via the command line. Note that the source map can come from a local file or a remote URL.
npm install -g @newrelic/publish-sourcemap publish-sourcemap PATH_TO_SOURCE_MAP_FILE (local or remote) PATH_TO_ORIGINAL_FILE --nrAdminKey=YOUR_NEW_RELIC_ADMIN_API_KEY --applicationId=YOUR_NEW_RELIC_APP_ID
- npm command line: List published maps
-
Here's an example of listing published source maps:
list-sourcemaps --applicationId=YOUR_APP_ID --nrAdminKey=YOUR_NEW_RELIC_ADMIN_KEY Options: --applicationId Browser application id --nrAdminKey New Relic admin API key
- npm command line: Delete
-
Here's an example of deleting a source map:
delete-sourcemap --applicationId=YOUR_APP_ID --nrAdminKey=YOUR_NEW_RELIC_ADMIN_API_KEY --sourcemapId=YOUR_SOURCE_MAP_ID Options: --applicationId Browser application id --nrAdminKey New Relic admin API key --sourcemapId Unique id generated for a source map
Here are some examples of using the npm module to publish from client-side JavaScript:
- npm via Node.js script: Publish
-
Here's an example of publishing a source map via a Node.js script:
var publishSourcemap = require(‘@newrelic/publish-sourcemap’).publishSourcemap publishSourcemap({ sourcemapPath: 'SOURCE_MAP_FULL_PATH', javascriptUrl: 'JS_URL', applicationId: YOUR_NEW_RELIC_APP_ID, nrAdminKey: 'YOUR_NEW_RELIC_ADMIN_API_KEY' }, function (err) { console.log(err || 'Sourcemap upload done')})
- npm via Node.js script: List published maps
-
Here's an example of listing all published source maps:
var listSourcemaps = require(‘@newrelic/publish-sourcemap’).listSourcemaps listSourcemaps({ sourcemapPath: 'SOURCE_MAP_FULL_PATH', javascriptUrl: 'JS_URL', applicationId: YOUR_NEW_RELIC_APP_ID, nrAdminKey: 'YOUR_NEW_RELIC_ADMIN_API_KEY', }, function (err, res) { console.log(err || res.body)})
- npm via Node.js script: Delete
-
Here's an example of deleting a source map file via a Node.js script:
var deleteSourcemap = require(‘@newrelic/publish-sourcemap’).deleteSourcemap deleteSourcemap({ sourcemapId: 'SOURCE_MAP_ID', applicationId: YOUR_NEW_RELIC_APP_ID, nrAdminKey: 'YOUR_NEW_RELIC_ADMIN_API_KEY', }, function (err) { console.log(err || 'Deleted source map')})
When you're done, go to the JS errors page in New Relic Browser, select an error grouping, and see if your error stack traces have been un-minified.
Use API via cURL
Below are some examples of using cURL to publish, list, and delete source maps:
- cURL: Upload maps
-
An example of using API via cURL to publish maps to Browser:
curl -H "Newrelic-Api-Key: YOUR_NEW_RELIC_ADMIN_API_KEY" \ -F "sourcemap=@SOURCE_MAP_PATH" \ -F "javascriptUrl=JS_URL" \ -F "releaseId=YOUR_RELEASE_ID" \ -F "releaseName=YOUR_UI_PAGE" \ https://sourcemaps.service.newrelic.com/v2/applications/YOUR_NEW_RELIC_APP_ID/sourcemaps
- cURL: List existing maps
-
Below is an example of how to get a list of source maps previously uploaded to New Relic via cURL. New Relic returns the source map's unique
SOURCEMAP_ID
and its components:curl \ -H "Newrelic-Api-Key: YOUR_NEW_RELIC_ADMIN_API_KEY" \ https://sourcemaps.service.newrelic.com/v2/applications/YOUR_NEW_RELIC_APP_ID/sourcemaps
- cURL: Delete map
-
To delete a source map:
- Use the GET endpoint to list existing source maps and locate the
SOURCEMAP_ID
. - Run the following command via cURL:
curl -X DELETE \ -H "Newrelic-Api-Key: YOUR_NEW_RELIC_ADMIN_API_KEY" \ https://sourcemaps.service.newrelic.com/v2/applications/YOUR_NEW_RELIC_APP_ID/sourcemaps/SOURCEMAP_ID
- Use the GET endpoint to list existing source maps and locate the
When you're done, go to the JS errors page in New Relic Browser, select an error grouping, and see if your error stack traces have been un-minified.
Troubleshoot source maps
If you are having trouble generating source maps from your build system, or if your errors in New Relic Browser are remaining minified, see the source maps troubleshooting documentation.