In various browsers Sentry supports deminifying JavaScript via source maps. A source map is a file generated by your minifier which compresses a mapping of the minified file to the original uncompressed version(s).
One important thing to note is that even though we support mapping files, a users browser may not actually be able to collect the required information for the server to generate a sourcemap.
Sentry requires the following to be able to map tracebacks to their source:
- A source map header or footer
- A publicly accessible uncompressed version of the source
- A line of context that includes a line number, column number, and filename
The first two items are the responsibility of you, the end-user, and you can take care of publishing them as part of your build process. The latter however, with an individual line of context, is severely crippled in many browsers.
One thing to note is that Sentry will attempt to process the source map before storing (or grouping) an event. This ensures that if we are able to deminify the source, we'll be able to more effectively group similar events over time.
In our experiences, the only browser that routinely delivers usable error reports is Google Chrome.
For additional information, see this more up-to-date wiki page.
While there are several compression libraries which support source maps, as of writing our recommendation is to use UglifyJS. That said, many tools such as webpack and browserify.
As an example, we can look at how we used to do things with Sentry (pre-webpack):
node_modules/uglify-js/bin/uglifyjs {input} \
--source-map-root={relroot}/ \
--source-map-url={name}.map.js \
--source-map={relpath}/{name}.map.js -o {output}
We won't attempt to go into the complexities of source maps, so we recommend taking a stab at compiling them, and running them against a validator.
We maintain an online validation tool that can be used to test your source (and sourcemaps) against: sourcemaps.io.
In many cases your application may sit behind firewalls or you simply can't expose source code to the public. Sentry provides an abstraction called Releases which you can attach source artifacts to.
The release API is intended to allow you to store source files (and sourcemaps) within Sentry. This removes the requirement for them to be web-accessible, and also removes any inconsistency that could come from network flakiness (on either your end, or Sentry's end).
You can either interact with the API directly or you can upload sourcemaps with the help of the Sentry CLI (:ref:`upload-sourcemaps-with-cli`).
- Start by creating a new authentication token under [Account] > API.
- Ensure you you have
project:writeselected under scopes. - You'll use the Authorization header with the value of
Bearer: {TOKEN}with API requests.
Now you need to setup your build system to create a release, and attach the various source files. You will want to upload all dist files (i.e. the minified/shipped JS), the referenced sourcemaps, and the files that those sourcemaps point to.
# Create a new release
$ curl https://app.getsentry.com/api/0/projects/:organization_slug/:project_slug/releases/ \
-X POST \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json'
-d '{"version": "2da95dfb052f477380608d59d32b4ab9"}' \
{
"dateCreated": "2015-03-06T04:51:32.723Z",
"version": "2da95dfb052f477380608d59d32b4ab9"
}When uploading the file, you'll need to reference it just as it would be referenced if a browser (or filesystem) had to resolve its path. So for example, if your sourcemap reference is just a relative path, it's relative to the location of the referencing file.
So for example, if you have http://example.com/app.min.js, and the file contains the
reference to app.map.js, the name of the uploaded file should be http://example.com/app.map.js.
# Upload a file for the given release
$ curl https://app.getsentry.com/api/0/projects/:organization_slug/:project_slug/releases/2da95dfb052f477380608d59d32b4ab9/files/ \
-X POST \
-H 'Authorization: Bearer {TOKEN}' \
-F [email protected] \
-F name="http://example.com/app.js.map"
{
"dateCreated": "2015-03-06T04:53:00.308Z",
"headers": {
"Content-Type": "application/octet-stream"
},
"id": "1",
"name": "http://example.com/app.js.map",
"sha1": "22591348ed129fe016c535654f6493737f0f9df6",
"size": 452
}# If you make a mistake, you can also simply clear out the release
$ curl https://app.getsentry.com/api/0/projects/:organization_slug/:project_slug/releases/2da95dfb052f477380608d59d32b4ab9/ \
-H 'Authorization: Bearer {TOKEN}' \
-X DELETEAdditionally, you'll need to configure the client to send the release:
Raven.config({
release: '2da95dfb052f477380608d59d32b4ab9'
});Note: You dont have to upload the source files (ref'd by sourcemaps), but without them the grouping algorithm will not be as strong, and the UI will not show any contextual source.
Additional information can be found in the Releases API documentation.
You can also use the Sentry :ref:`sentry-cli` to manage releases and sourcemaps on Sentry. If you have it installed you can create releases with the following command:
$ sentry-cli releases -o MY_ORG -p MY_PROJECT new 2da95dfb052f477380608d59d32b4ab9
After you have run this, you can use the files command to automatically add all javascript files and sourcemaps below a folder. They are automatically prefixed with a URL or your choice:
$ sentry-cli releases -o MY_ORG -p MY_PROJECT files \ 2da95dfb052f477380608d59d32b4ab9 upload-sourcemaps --url-prefix \ https://mydomain.invalid/static /path/to/assets
All files that end with .js and .map below /path/to/assets are
automatically uploaded to the release 2da95dfb052f477380608d59d32b4ab9
in this case. If you want to use other extensions you can provide it with
the --ext parameter.
.. sentry:edition:: hosted
While the recommended solution is to upload your source artifacts to Sentry, sometimes it's necessary to allow communication from Sentry's internal IPs. For more information on Sentry's public IPs, see :ref:`ip-ranges`.
Source maps can sometimes be tricky to get going. If you're having trouble, try the following tips.
Some CDNs automatically strip comments from static files, including JavaScript files. This can have the effect of stripping your JavaScript file of its sourceMappingURL directive, because it is considered a comment. For example, CloudFlare has a feature called Auto-Minify which will strip sourceMappingURL if it is enabled.
Double-check that your deployed, final JavaScript files have sourceMappingURL present.
When uploading source maps to Sentry, you must name your source map files with the same name found in sourceMappingURL.
For example, if you have the following in a minified application file, app.min.js:
//-- end app.min.js
//# sourceMappingURL=https://example.com/dist/js/app.min.js.mapSentry will look for a matching artifact named exactly https://example.com/dist/js/app.min.js.map.
Note also that Sentry will resolve relative paths. For example, if you have the following:
// -- end app.min.js (located at https://example.com/dist/js/app.min.js)
//# sourceMappingURL=app.min.js.mapSentry will resolve sourceMappingURL relative to https://example.com/dist/js/ (the root path from which app.min.js was served). You will again need to name your source map with the full URL: https://example.com/dist/js/app.min.js.map.
Sentry expects that source code and source maps in a given release are uploaded to Sentry before errors occur in that release.
If you upload artifacts after an error is captured by Sentry, Sentry will not go back and retroactively apply any source annotations to those errors. Only new errors triggered after the artifact was uploaded will be affected.
For an individual artifact, Sentry accepts a max filesize of 20 MB.
Often users hit this limit because they are transmitting source files at an interim build stage. For example, after Webpack/Browserify has combined all your source files, but before minification has taken place. If possible, send the original source files.