06Error tracking

Source maps

A production build turns your code into minified bundles, so a stack trace reads a.js:1:48210. A source map is the file your build can emit that maps the bundle back to your code. Upload the maps for each release and Errors → Issues shows the real file, line and function, with the lines around it.

Source maps are kept private. SnowAnalytics never serves them. It reads them only to open a minified stack, and nothing is shown to visitors.

Before you start

  • Tag your releases with data-release or window.SNOW_RELEASE. A map is matched to an error by release and file.
  • Make your build emit source maps. In most bundlers that is the sourcemap option.
  • Create a server key in Site settings → API keys, under Server keys. It carries the events:write scope the upload needs. See API keys.

Upload from your build

There is no CLI to install. The upload is one HTTP request that your build runs.

Send a POST to /api/v1/sourcemaps once a build, with the release and one entry for each bundle: the bundle's address on your site (a path or a full URL) and its map.

After the build
jq -n --arg release "2.14.1" --rawfile map dist/assets/app.js.map \
  '{release: $release, files: [{url: "/assets/app.js", map: $map}]}' \
  | curl -sS -X POST https://api.snowanalytics.app/api/v1/sourcemaps \
    -H "Authorization: Bearer $SNOW_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-

Keep the key in your CI's secrets. Issues → Source maps → Copy upload command copies this command with your newest release filled in.

Prop

Type

A success answers 200 with { "status": "success", "data": { "release": "2.14.1", "uploaded": 1 } }. Uploading the same release and file again replaces the earlier map.

StatusMeaning
400The body isn't JSON in this shape, or a map isn't a valid source map. The message names the entry.
401 or 403The key is missing, wrong or lacks the events:write scope.
413The body is over 25 MB. Send fewer files in one request.
423Tracking is paused until you upgrade.
429More than 60 uploads a minute from one key.

Check that it worked

Errors → Issues → Releases → Source maps lists your newest releases as Uploaded, with the number of files and when, or Missing, where stack traces stay minified.

On an issue, the stack card says source-mapped from the release when frames were mapped, and minified: no source map uploaded when none were. A frame whose file has no map for that release stays as it came.

Server errors

Server errors point at your server's own files, so they need no source maps.

On this page