Uploading Debug Symbols (iOS)

Sentry requires dSYMs (debug information files) to symbolicate your stack traces. The symbolication process unscrambles the stack traces to reveal the function, file names, and line numbers of the crash.

Every solution requires a Sentry Auth Token. You can create tokens on the Organization Auth Tokens settings 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:

• sentry-cli
• Sentry Fastlane Plugin
• Xcode Build Phase

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 stack traces. 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.

For this to work, your project settings for DEBUG_INFORMATION_FORMAT must be set to DWARF with dSYM File, which is the default for release builds but not for debug builds.

sentry-cli debug-files upload --auth-token sntrys_YOUR_TOKEN_HERE \
  --include-sources \
  --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 stack traces. 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_debug_files_upload(
  auth_token: 'sntrys_YOUR_TOKEN_HERE',
  org_slug: 'example-org',
  project_slug: 'example-project',
  include_sources: true, # Optional. For source context.
)

url: '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:

1. Download and install sentry-cli.
2. 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 stack traces. 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.

For this to work, your project settings for DEBUG_INFORMATION_FORMAT must be set to DWARF with dSYM File, which is the default for release builds but not for debug builds. If you don't want Sentry to upload your source code, remove the --include-sources argument from the copied script.

if which sentry-cli >/dev/null; then
export SENTRY_ORG=example-org
export SENTRY_PROJECT=example-project
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
ERROR=$(sentry-cli debug-files upload --include-sources "$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

3. 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}

4. Set ENABLE_USER_SCRIPT_SANDBOXING in your Xcode project settings to NO. [enable-user-script-sandboxing](./img/enable_user_script_sandboxing.png

export SENTRY_URL=https://mysentry.invalid/