Enable Readable Stack Traces in Your Errors

A release version is a dynamic identifier that changes whenever you ship a new version of your code. When you give Sentry information about your releases, you unlock several features, including source mapping of minified JavaScript stack traces upon ingestion. Learn more in our Releases documentation. In this section, you will:

  1. Use the Sentry CLI during the build process to update your Sentry account by:

    • Creating a new release version
    • Uploading the project's latest source maps (and associate them with the new release version)
  2. Add the release version to the Sentry SDK configuration. This will associate any error captured by the SDK in our app to this specific release. Sentry will use the release's uploaded source maps to unminify the error's stack trace.

Step 1: Prepare the build environment

We use the Makefile in the frontend-monitoring project to handle Sentry related tasks using the sentry-cli. The CLI is already available through the project dependencies (see package.json) and requires several parameters to be available to run.

  1. Open the Makefile.

  2. Uncomment the commented environment variables SENTRY_AUTH_TOKEN , SENTRY_ORG, and SENTRY_PROJECT (remove the leading #).

    Initial Makefile

  3. To find the SENTRY_ORG and SENTRY_PROJECT values:

    • Open your Sentry account and click Settings > Projects.

    • Your organization ID, or the SENTRY_ORG value is part of the browser URL (for example, https://sentry.io/settings/**SENTRY_ORG**/projects/).

    • The SENTRY_PROJECT value is the name that appears in the project tile.

      Sentry CLI variables

    • Copy the values and paste them in the Makefile.

  4. To create a SENTRY_AUTH_TOKEN:

    • Click "Developer Settings" in the left side panel to create a new integration and org-level auth

      tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.

    • Click on "New Internal Integration".

      Create Auth Token 1

    • Enter a name.

    • Under "Permissions" select "Admin" in the "Release" dropdown, and "Read & Write" in the "Organization" dropdown.

      Token Permissions

    • Click "Save Changes".

    • Once the save is confirmed, scroll down to the bottom of the page and copy the allocated token under "TOKENS".

      Create Auth Token 2

    • Paste the token in the Makefile.

  5. The Makefile should look like this:

    Sentry CLI variables

Step 2: Create a release and upload source maps

Now we can invoke the sentry-cli to let Sentry know we have a new release, and then upload the project's source maps to it.

  • You can set a custom release version to suit your naming conventions or let the Sentry CLI propose a version.
  • To build the frontend-monitoring project, we use the react-scripts package that also generates source maps under ./build/static/js/.
  1. In the Makefile, add a new environment variable for the release version, using Sentry CLI to propose the version value:

    REACT_APP_RELEASE_VERSION=`sentry-cli releases propose-version`
  2. At the bottom of the Makefile, paste the following targets using the Sentry CLI to:

    • Create a new release entity in your Sentry account
    • Upload the project's source maps to the new release
        sentry-cli releases -o $(SENTRY_ORG) new -p $(SENTRY_PROJECT) $(REACT_APP_RELEASE_VERSION)
        sentry-cli releases -o $(SENTRY_ORG) -p $(SENTRY_PROJECT) files $(REACT_APP_RELEASE_VERSION) \
            upload-sourcemaps --url-prefix "~/static/js" --validate build/static/js

    The Makefile contains a setup_release target that is invoked from the package.json file when you run $ npm run deploy to build and run the project. We'll use this target to invoke all the release related tasks.

  3. Replace the existing setup_release with:

    setup_release: create_release upload_sourcemaps

    Your Makefile should look like this:

    Makefile with Release

    Now that you've created a release version, you can associate any errors captured in your app to that release through the SDK.

  4. Open the index.html file and add a new configuration option to the SDK. Assign the release version environment variable to the release key.

      dsn: "<YOUR DSN KEY>",
      release: "%REACT_APP_RELEASE_VERSION%",

    Note that the release version environment variable is set in the project.json during build time and is injected into the generated markup.

Step 3: Try your changes — generate another error

  1. If your terminal is still serving the demo app on localhost, click ^C to shut down the local server.

  2. Build, deploy, and rerun the project by running:

    > npm run deploy

    A Makefile is generally unforgiving when it comes to indentation. If you're getting unexpected errors while running the above command, make sure the sentry-cli commands are properly prefixed with a tab.

  3. Look at the terminal log. Notice that the minified scripts and source maps were uploaded to the release version.

    Release Created

  4. In your browser, make sure that the dev console is open and perform an "Empty Cache and Hard Reload" to make sure the updated code is being served.

    Release Created

  5. Generate the error again by adding products to your cart and clicking "Checkout".

  6. Check your Email for the alert about the new error and click "View on Sentry" to open the Issue Details page.

  7. Notice that:

    • The event is now tagged with the Release ID.
    • The error stack trace is now un-minified and includes the file name, method name, line and column number, and source code context in every stack frame.

    Release Created

Step 4: Explore the release

Creating a release version and uploading the source maps through the Sentry CLI, creates a Release entity in your Sentry account.

  1. In sentry.io, click "Releases" in the left side panel. Notice that a new release version was created:

    Release Created

  2. Click on the release and you'll see that the error in your app has been associated with this release and is listed as a "New Issue".

    Release Created

  3. Click on the "Artifacts" tab, and notice the minified resources and source maps are available for this release and are used to source map stack traces.

    Release Created


Now that we have all the information we need about the error and a clear stack trace, the next thing is to assign the right developer to handle it.

Enable Suspect Commits

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").