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.
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.
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.
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.
Setting up App Store Connect currently requires two separate credentials.
- 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.
- 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.
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.
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.
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.
sentry-cli upload-dif command will automatically find and upload all BCSymbolMap files, given the path to the app's
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.
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
Download the dSYM from App Store Connect. After that, you can upload the dSYM using sentry-cli.
- Open Xcode Organizer, go to your app, and click “Download dSYMs...”
- 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:
sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org example-org --project example-project PATH_TO_DSYMS
When not using Bitcode you can directly upload the symbols to Sentry as part of your build.
If you are already using Fastlane you can use it in this situation as well:
lane :build do gym # building your app sentry_upload_dsym( auth_token: 'YOUR_AUTH_TOKEN', org_slug: 'example-org', project_slug: 'example-project', ) end
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.
- Download and install sentry-cli
- You will need to copy the script below into a new Run Script and set your AUTH_TOKEN, ORG_SLUG, and PROJECT_SLUG
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
- 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: