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 and allow JavaScript and iOS Sentry projects to proactively unminify or symbolicate your error stack traces. For more information, see Releases.

Description & Objectives

Releases are used for applying source maps to minified JavaScript to view original, untransformed source code in the stack traces of errors associated with the respective release. This is particularly useful for debugging minified code (for example, UglifyJS), or transpiled code from a higher-level language (for example, TypeScript, ES6).

In this tutorial, we will:

  1. Utilize the Sentry Command Line Interface (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 source maps we uploaded to unminify the error’s stack trace.

Note: As part of the CI/CD workflow for this app demo, we’re using a Makefile to handle the sentry-cli related tasks through make tasks (targets). If you’re using a different code base, you can still apply the settings and commands described below to your specific setup or run them directly in a command line shell. For more information, see Command Line Interface.

Step 1: Prepare the Build Environment

We will use the Makefile in the sentry-react-demo project to handle Sentry related tasks utilizing 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 Projects
    • Your Organization ID is part of the browser URL (for example, https://sentry.io/organizations/SENTRY_ORG/issues/?project=1523617)
    • 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 on the Company Org name from the top of the left side panel to open the Org and User Settings
    • Select API Keys
    • Click on Create New Token from the Auth Tokens page

      Create Auth Token 1

    • Accept the selected token scopes and click Create Token

      Create Auth Token 2

    • Once the token is created, click on the copy icon to copy the token value and paste it in the Makefile

      Create Auth Token 3

  5. The Makefile should look like this:

    Sentry CLI variables

Step 2: Create a Release & Upload Source Maps

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

  • You can set a custom release version to suit your own delivery processes or let the Sentry CLI calculate and generate a version.
  • To build the sentry-react-demo 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, utilizing 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 utilizing the Sentry CLI to:
    • Create a new release (object) 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 running $ 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 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: 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 Change — 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
  3. Take a 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 page

  7. Notice that the error stack trace is now available

    Release Created

Step 4: Explore the Release

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

  1. Click on Releases from the left side panel, notice that a new release version was created

    Release Created

  2. Click on the release, notice that the error in your app has been associated with this release and is listed as a New Issue in this Release

    Release Created

  3. Click on the Artifacts tab, notice the minified resources and source maps are available for this release and will be used to unminify error 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.

Integrate your Source Code Repository