Uploading Debug Symbols

Sentry requires a dSYM upload to symbolicate your crash logs. The symbolication process unscrambles Apple’s crash logs to reveal the function, file names, and line numbers of the crash. Upload the dSYM file using either sentry-cli, the Fastlane action, or set up the Sentry App Store Connect integration for Bitcode builds. Every solution requires a Sentry Auth Token with the correct permissions. You can create one here.

With Bitcode

If Bitcode is enabled in your project, dSYM files will only be available after App Store Connect finishes processing the build. Sentry can fetch dSYM files automatically as they become available from App Store Connect when setting up the App Store Connect integration. Alternatively, the dSYM files can be downloaded either with Fastlane or manually, and uploaded with Fastlane or sentry-cli.

Using App Store Connect

When you use the App Store Connect integration, Sentry will automatically discover and fetch dSYM files for Bitcode builds as they become available on App Store Connect. These dSYM files however contain obfuscated symbol names and paths. An additional BCSymbolMap file needs to be uploaded to provide properly symbolicated crash reports. These BCSymbolMap files can be uploaded using either sentry-cli or Fastlane.

To configure the integration, go to [Project] > Settings > Debug Files and add "App Store Connect" in the "Custom Repositories" section.

Adding an App Store Connect Integration to a project

Once the integration is set up it will ensure that new builds are detected and fetched within an hour of being available on App Store Connect.

A fully set-up App Store Connect Integration

Setting up App Store Connect currently requires two separate credentials.

  1. App Store Connect API Key:

Follow the documentation on Creating API Keys for App Store Connect API and provide the Issuer, Key ID, and Private Key. The API Key needs to have the Developer role in order to fetch build details.

  1. iTunes Credentials:

An iTunes user and password are required, in addition to the normal App Store Connect API Key, due to limitations of the App Store Connect API. The App Store Connect API Key alone will only allow detection of new builds; an iTunes user is required to fetch the associated dSYM files.

Create a new Apple ID specifically for this integration and provide its credentials. The user needs to have the Developer role in the appropriate App Store Organization.

These credentials will need to be verified by a two-factor authentication token that you can choose to have sent by SMS.

Re-authentication

The iTunes credentials and two-factor authentication are short-lived and need to be refreshed on a regular basis. Sentry will prompt users to re-authenticate in the Issue Details pages of a project, in the settings menu of a project, as well as in the "Custom Repositories" section of a project's "Debug Files" settings once their iTunes credentials expire.

Issue Details

Warning to update credentials in an issue's details

Project Settings

Warning to update credentials in sidebar

Custom Repositories

Warning to update credentials in Custom Repositories

Upload BCSymbolMaps Using Fastlane

As dSYM download will be handled by sentry, it is not necessary to use the download_dsyms or sentry_upload_dsym commands. Instead, use the sentry_upload_dif command to upload the BCSymbolMap.

Copied
sentry_upload_dif(
  auth_token: 'YOUR_AUTH_TOKEN',
  org_slug: 'example-org'
  project_slug: 'example-project',
  path: '/path/to/files' # Optional. Well default to '.' when no value is provided.
)

When using the upload_to_testflight action, it is recommended to pass the skip_waiting_for_build_processing parameter to speed up the action.

Upload BCSymbolMaps Using sentry-cli

The sentry-cli upload-dif command will automatically find and upload all BCSymbolMap files, given the path to the app's .xcarchive.

Using Fastlane

Use the Fastlane action, download_dsyms, to download the dSYMs from App Store Connect and upload to Sentry. The dSYM won’t be generated until after the app is done processing on App Store Connect so this should be run in its own lane.

Copied
lane :upload_symbols do
  download_dsyms # this is the important part
  sentry_upload_dsym(
    auth_token: 'YOUR_AUTH_TOKEN',
    org_slug: 'example-org',
    project_slug: 'example-project',
  )
end

Using sentry-cli

Download the dSYM from App Store Connect. After that, you can upload the dSYM using sentry-cli.

  1. Open Xcode Organizer, go to your app, and click “Download dSYMs...”
  2. Login to App Store Connect, go to your app, go to “Activity", click the build number to go into the detail page, and click “Download dSYM”

Afterwards manually upload the symbols with sentry-cli:

Copied
sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org example-org --project example-project PATH_TO_DSYMS

Without Bitcode

When not using Bitcode you can directly upload the symbols to Sentry as part of your build.

Using Fastlane

If you are already using Fastlane you can use it in this situation as well:

Copied
lane :build do
  gym # building your app
  sentry_upload_dsym(
    auth_token: 'YOUR_AUTH_TOKEN',
    org_slug: 'example-org',
    project_slug: 'example-project',
  )
end

Uploading Symbols with sentry-cli

Your project’s dSYM can be upload during the build phase as a “Run Script”. For this you need to set the DEBUG_INFORMATION_FORMAT to be DWARF with dSYM File. By default, an Xcode project will only have DEBUG_INFORMATION_FORMAT set to DWARF with dSYM File in Release so make sure everything is set in your build settings properly.

You need to have an Auth Token for this to work. You can create an Auth Token here.

  1. Download and install sentry-cli
  2. You will need to copy the script below into a new Run Script and set your AUTH_TOKEN, ORG_SLUG, and PROJECT_SLUG
Copied
if which sentry-cli >/dev/null; then
export SENTRY_ORG=example-org
export SENTRY_PROJECT=example-project
export SENTRY_AUTH_TOKEN=YOUR_AUTH_TOKEN
ERROR=$(sentry-cli upload-dif "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null)
if [ ! $? -eq 0 ]; then
echo "warning: sentry-cli - $ERROR"
fi
else
echo "warning: sentry-cli not installed, download from https://github.com/getsentry/sentry-cli/releases"
fi
  1. If you are using Xcode 10 or newer, you also need to add the following line to the Input Files section in the Run Script from step 2:
Copied
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
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").