Skip to content

Files

Latest commit

 Cannot retrieve latest commit at this time.

History

History
265 lines (212 loc) · 10.8 KB

upload-source-maps-api.mdx

File metadata and controls

265 lines (212 loc) · 10.8 KB
title metaDescription redirects freshnessValidatedDate
Upload source maps via API
For New Relic browser monitoring, how to upload and use source maps with the browser API.
/docs/push-source-maps-api
/docs/browser/new-relic-browser/browser-pro-features/push-source-maps-api
2024-01-02

Our supports the uploading of source maps, which are used to un-minify error stack traces on the Errors page. This document explains how to use the API to upload source maps using the browser API.

Prepare for using the source map API [#questions]

In order to upload source maps to browser via the API, you'll need:

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 browser, on the <DNT>**JS errors**</DNT> page. See [Browser monitoring source maps](/docs/new-relic-browser-source-maps) for more on finding these errors in the UI.

<Collapser id="release-id" title="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](#generate).

  If this <DNT>**doesn't**</DNT> 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](/docs/browser-api-newrelicaddrelease).

<Collapser id="repo-url" title="Is a repo URL or a build commit hash required?"

If you're interested in monitoring the performance of your code from your IDE using New Relic CodeStream, repository URL is required. If you'd like to investigate errors from your IDE as well, the build commit hash is recommended, but not required.

Learn more about [monitoring performance](/docs/codestream/how-use-codestream/performance-monitoring) by bringing observability into the IDE.

<Collapser id="limits" title="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 per account:

* You can upload a maximum of 1000 source maps per minute.
* You can upload a maximum of 15,000 source maps per day.
* Only one source map can be uploaded or published per API request.

  Source map files can be a maximum of 50Mb in size.

<Collapser id="app-id" title="Which application ID should be used?"

Both `YOUR_NEW_RELIC_APP_ID` and `YOUR_APP_ID` are valid values for `applicationId`.

Push source maps to New Relic [#publish]

Now that you have one or more source maps, you are ready to publish it to browser. You can use any of these methods to send source maps to browser:

Use npm module via command line or client-side script [#npm]

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](/docs/using-new-relic/welcome-new-relic/getting-started/introduction-eu-region-data-center). 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. 
```bash
npm install -g @newrelic/publish-sourcemap
publish-sourcemap PATH_TO_SOURCE_MAP_FILE (local or remote) PATH_TO_ORIGINAL_FILE --apiKey=YOUR_NEW_RELIC_USER_KEY --applicationId=YOUR_NEW_RELIC_APP_ID --repoUrl=GITHUB_REPOSITORY_URL --buildCommit=GIT_BUILD_COMMIT_HASH
```

<Collapser id="npm-list" title="npm command line: List published maps"

Here's an example of listing published source maps:

```bash
list-sourcemaps --applicationId=YOUR_APP_ID --apiKey=YOUR_NEW_RELIC_USER_KEY
[output]
[output] Options:
[output]   --applicationId  Browser application id
[output]   --apiKey         New Relic user API key
```

<Collapser id="npm-delete" title="npm command line: Delete"

Here's an example of deleting a source map:

```bash
delete-sourcemap --applicationId=YOUR_APP_ID --apiKey=YOUR_NEW_RELIC_USER_API_KEY --sourcemapId=YOUR_SOURCE_MAP_ID
[output] 
[output] Options:
[output]   --applicationId  Browser application id
[output]   --apiKey         New Relic user API key
[output]   --sourcemapId    Unique id generated for a source map
```

Here are some examples of using the npm module to publish from client-side JavaScript:

Here's an example of publishing a source map via a Node.js script: 
```js
var publishSourcemap = require('@newrelic/publish-sourcemap').publishSourcemap;

publishSourcemap({
  sourcemapPath: 'SOURCE_MAP_FULL_PATH',
  javascriptUrl: 'JS_URL',
  applicationId: YOUR_NEW_RELIC_APP_ID,
  apiKey: 'YOUR_NEW_RELIC_USER_API_KEY',
  repoUrl: 'GITHUB_REPOSITORY_URL',
  buildCommit: 'GIT_BUILD_COMMIT_HASH'
}, function(err) { console.log(err || 'Sourcemap upload done'); });
```

<Collapser id="npm-client-list" title="npm via Node.js script: List published maps"

Here's an example of listing all published source maps:

```js
var listSourcemaps = require('@newrelic/publish-sourcemap').listSourcemaps;;

listSourcemaps({
  applicationId: YOUR_NEW_RELIC_APP_ID,
  apiKey: 'YOUR_NEW_RELIC_USER_API_KEY',
  limit: MAX_NUMBER_OF_RESULTS_TO_RETURN || 20,
  offset: NUMBER_OF_RESULTS_TO_SKIP_BEFORE_RETURNING || 0,
}, function(err, res) { console.log(err || res.sourcemaps); });
```

<Collapser id="npm-client-delete" title="npm via Node.js script: Delete"

Here's an example of deleting a source map file via a Node.js script:

```js
var deleteSourcemap = require('@newrelic/publish-sourcemap').deleteSourcemap;

deleteSourcemap({
  sourcemapId: 'SOURCE_MAP_ID',
  applicationId: YOUR_NEW_RELIC_APP_ID,
  apiKey: 'YOUR_NEW_RELIC_USER_API_KEY',
}, function(err) { console.log(err || 'Deleted source map'); });
```

When you're done, go to the JS errors page in browser, select an error grouping, and see if your error stack traces have been un-minified.

Use API via curl [#api]

Below are some examples of using curl to publish, list, and delete source maps:

An example of using API via curl to publish maps to browser: 
```bash
curl -H "Api-Key: YOUR_NEW_RELIC_USER_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
```

```bash
curl -H "Api-Key: YOUR_NEW_RELIC_USER_API_KEY" \ 
     -F "sourcemap=@SOURCE_MAP_PATH" \ 
     -F "javascriptUrl=JS_URL" \ 
     -F "releaseId=YOUR_RELEASE_ID" \ 
     -F "releaseName=YOUR_UI_PAGE" \
     -F "repoUrl=GITHUB_REPOSITORY_URL" \
     -F "buildCommit=GIT_BUILD_COMMIT_HASH" \
     https://sourcemaps.service.newrelic.com/v2/applications/YOUR_NEW_RELIC_APP_ID/sourcemaps
```

<Collapser id="curl-list" title="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:

```bash
curl -H "Api-Key: YOUR_NEW_RELIC_USER_API_KEY" \ 
    https://sourcemaps.service.newrelic.com/v2/applications/YOUR_NEW_RELIC_APP_ID/sourcemaps
```

<Collapser id="curl-delete" title="curl: Delete map"

To delete a source map:

1. Use the GET endpoint to list existing source maps and locate the `SOURCEMAP_ID`.
2. Run the following command via curl:

   ```bash
   curl -X DELETE \
        -H "Api-Key: YOUR_NEW_RELIC_USER_API_KEY" \
        https://sourcemaps.service.newrelic.com/v2/applications/YOUR_NEW_RELIC_APP_ID/sourcemaps/SOURCEMAP_ID
   ```

When you're done, go to the Group errors tab in browser, select an error grouping, and see if your error stack traces have been un-minified.

Troubleshoot source maps [#troubleshoot]

If you are having trouble generating source maps from your build system, or if your errors in browser remain minified, see the source maps troubleshooting documentation.