Uploading Debug Symbols
Sentry requires dSYMs (debug information files) to symbolicate your stacktraces. The symbolication process unscrambles the stacktraces to reveal the function, file names, and line numbers of the crash.
Every solution requires a Sentry Auth Token. We recommend using internal integrations for managing Auth Tokens. Create a new internal integration with the permission project:read&write
, if you don't have one already. After saving it, you can copy the Auth Token from the integration page.
To view uploaded dSYMs in your project, select an existing project from the "Projects" page, then go to Settings > Debug Files. You can upload dSYMs using:
Starting with Xcode 13, newly generated projects don't automatically create a required Info.plist
configuration file.
If this is your situation, please read Info.plist Is Missing in Xcode 13 — Here's How To Get It Back.
Sentry-cli
Use the sentry-cli debug-files upload
command to upload dSYMs to Sentry. The command will recursively scan the provided folders or ZIP archives. Files that have already been uploaded will be skipped automatically.
Sentry can display snippets of your code next to the event stacktraces. This feature is called source context. When setting the --include-sources
option, sentry-cli will scan your debug files to find references to the source code files, resolve them in the local file system, bundle them up, and upload them to Sentry.
sentry-cli debug-files upload --auth-token YOUR_AUTH_TOKEN \
--org example-org \
--project example-project \
PATH_TO_DSYMS
Visit the sentry-cli docs for more information.
Sentry Fastlane Plugin
If you're already using Fastlane, you can use the Sentry Fastlane plugin to upload your dSYMs to Sentry.
Sentry can display snippets of your code next to event stacktraces. This feature is called source context. When setting the include_sources
parameter to true
, the Fastlane plugin will scan your debug files to find references to the source code files, resolve them in the local file system, bundle them up, and upload them to Sentry.
sentry_upload_dif(
auth_token: 'YOUR_AUTH_TOKEN',
org_slug: 'example-org',
project_slug: 'example-project',
include_sources: true, # Optional. For source context.
)
On Prem
By default fastlane will connect to sentry.io. For on-prem you need to provide the api_host parameter to instruct the tool to connect to your server:
api_host: 'https://mysentry.invalid/'
Xcode Build Phase
Your project's dSYM can be uploaded during Xcode's build phase as a Run Script. To do this, set the DEBUG_INFORMATION_FORMAT to DWARF with a dSYM file. By default, an Xcode project will only have DEBUG_INFORMATION_FORMAT set to DWARF with a dSYM file in release, so make sure everything is properly set up in your build settings.
Follow these steps to upload the debug symbols:
- Download and install sentry-cli.
- Copy the script below into a new Run Script and set your AUTH_TOKEN, ORG_SLUG, and PROJECT_SLUG.
Sentry can display snippets of your code next to the event stacktraces. This feature is called source context. When setting the --include-sources
option, sentry-cli will scan your debug files to find references to the source code files, resolve them in the local file system, bundle them up, and upload them to Sentry. Simply change sentry-cli debug-files upload
to sentry-cli debug-files upload --include-sources
in the copied script.
Warnings vs. Errors
Depending on your needs, you may want to emit warnings to the Xcode build log to let the build pass, or emit errors to fail it. For example, in a CI deployment where debug symbols may be harder to recover, and you might not realize symbols couldn't be symbolicated until after release, it might be better to fail the build.
Another option is to use warnings, and then set GCC_TREAT_WARNINGS_AS_ERRORS
to YES
in build settings for configurations you use to deploy to production.
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 debug-files upload "$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
- You also need to add the following line to the Input Files section in the Run Script from step 2:
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
Self Hosted
By default sentry-cli will connect to sentry.io. For on-prem you need to export the SENTRY_URL environment variable to instruct the tool to connect to your server:
export SENTRY_URL=https://mysentry.invalid/
App Store Connect Integration
Source Context
The App Store Connect integration doesn't support source context. To get it to work, choose one of the methods above.
When you use the App Store Connect integration, Sentry will automatically discover and fetch dSYMs for builds as they become available on App Store Connect.
To configure the integration, select an existing project from the "Projects" page, then go to 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.
Note
Organizations using Developer and Team plans are limited to one App Store Connect source per project. To be able to use multiple App Store Connect sources per project, upgrade to a Business or Enterprise plan or contact sales@sentry.io.
Setting up an App Store Connect custom repository requires an 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. In order to be able to fetch build details, your API Key needs to be assigned the Developer role.
Invalid Credentials
If your App Store Connect API key is revoked on the Apple side, the Sentry custom repository using this key's credentials will no longer be able to discover and fetch dSYM files. You'll see the following warnings in Sentry's user interface:
Issue Details
Project Settings
Custom Repositories
When using Fastlane's upload_to_testflight action, it's recommended to pass the skip_waiting_for_build_processing parameter to speed up the action.
Bitcode
As of April 25th, 2023, the App Store no longer accepts submissions with bitcode enabled.
If you’re using Xcode 13, you’ll need to download the dSYMs from App Store Connect after it finishes processing your build, and then upload them to Sentry using one of the methods below:
- Download Fastlane's download_dsyms action and then upload the dSYMs with the Sentry Fastlane plugin.
- Use the Sentry App Store Connect integration, which fetches the dSYMS directly from App Store Connect.
- Download manually from App Store Connect:
- Open Xcode Organizer, go to your app, and click Download dSYMs...
- Log in to App Store Connect, go to your app > “Activity".
- Click the build number to go into the "detail" page, and click Download dSYM.
- Manually upload the dSYMs with sentry-cli.
These dSYMs contain obfuscated symbol names and paths. You must upload the BCSymbolMap file stored in your xcarchive so Sentry can properly symbolicate your crash reports. You can do this by using the debug-files upload
command of either sentry-cli or the Sentry Fastlane plugin, which will automatically find and upload all BCSymbolMap files when specifying the path to the app's xcarchive.
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").
- Package:
- cocoapods:sentry-cocoa
- Version:
- 8.7.3
- Repository:
- https://github.com/getsentry/sentry-cocoa