Upload dSYM files

Xcode stores your app's dSYM files in the dSYM archive path folder. This is the folder where the iOS agent gets the dSYM files that it uses to symbolicate your crash reports. New Relic provides a post-build script as part of the iOS agent's install process. This script automatically converts your dSYM to the New Relic map file format and uploads the files needed for crash symbolication to New Relic.

Automatic script

The iOS agent includes run-symbol-tool, a shell script that you run from a Run Script build phase in Xcode. After each build, it runs run-symbol-tool.swift in the background, which converts your dSYM files to the New Relic map file format and uploads them to New Relic.

In Xcode 14 Apple changed the default setting on newly created projects to disable bitcode. The App Store now only accepts app submissions with bitcode turned off. See Xcode 14 release notes. If your project still has bitcode enabled you must disable it. The automatic script requires bitcode to be disabled.

Apple generates dSYM files for Bitcode-enabled apps. You must download the dSYM files for Bitcode-enabled apps from Apple and upload them to New Relic through the mobile monitoring UI.

If you see unreadable machine code in the Crashes page, your dSYM files may not be uploaded correctly. In some cases, you may need to manually upload dSYM files.

Add the Run Script build phase

1. In Xcode, select your project in the navigator, then select your app target.

2. Select the Build Phases tab.

3. Click + and choose New Run Script Phase.

4. Add the following lines to the new phase. Replace APP_TOKEN with your application token from New Relic.

   bash

   Copier

   $
   ARTIFACT_DIR="${BUILD_DIR%Build/*}"
   $
   SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
   $
   /bin/sh "${SCRIPT}" "APP_TOKEN"

In Xcode 15.3 or higher, set User Script Sandboxing to No so the script can read your dSYM files and write its log. See Automatic dSYM upload failures.

Optional arguments

Add optional arguments after the app token, in any order:

For example:

$
ARTIFACT_DIR="${BUILD_DIR%Build/*}"
$
SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
$
/bin/sh "${SCRIPT}" "APP_TOKEN" -appVersion "1.4.2" --debug

App version

New Relic matches uploaded symbols to your builds by app version. The script uses the first non-empty value from this list:

1. The -appVersion argument
2. The NEWRELIC_APP_VERSION environment variable
3. The MARKETING_VERSION build setting
4. The placeholder 1.2.3

When the script uses the placeholder, it logs a warning in upload_dsym_results.log.

Some projects don't set MARKETING_VERSION, such as apps versioned with agvtool or multi-target apps that use GENERATE_INFOPLIST_FILE = YES. For these projects, pass -appVersion or set NEWRELIC_APP_VERSION so your symbols match your builds.

Environment variables

You don't need to set these variables for a standard upload. To set one, add an export line above the script in the same Run Script phase:

$
export NEWRELIC_APP_VERSION="1.4.2"
$
ARTIFACT_DIR="${BUILD_DIR%Build/*}"
$
SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
$
/bin/sh "${SCRIPT}" "APP_TOKEN"

The script supports these environment variables:

How the script works

When it runs, the script does the following:

• The upload runs in the background, so your build doesn't wait for it to finish. The script writes results to upload_dsym_results.log.
• The script skips iOS simulator builds (EFFECTIVE_PLATFORM_NAME is -iphonesimulator).
• Bitcode-enabled builds (ENABLE_BITCODE = YES) exit without uploading and without failing the build.
• The script converts each dSYM in DWARF_DSYM_FOLDER_PATH to a map file, zips the map files, and uploads the zip to the /map endpoint.
• If a dSYM can't be converted, the script zips that dSYM and uploads it to the /symbol endpoint instead. If the map upload itself fails, the script logs the HTTP status code and doesn't fall back to a dSYM upload. In that case, upload the dSYM manually.
• In iOS agent version 7.7.2 and higher, if a zipped map file is larger than 200 MB, the script doesn't upload it. It sends only the file size and app version to New Relic. New Relic can't symbolicate crashes from that build unless you upload its dSYM manually.
• The script chooses the upload region (US, EU, or JP) from your application token. These are the same hosts used in the manual upload commands.

Identify missing dSYMs

When a Bitcode-enabled app is uploaded to Apple for App Store review or ad-hoc distribution, dSYMs need to be manually downloaded from Apple and uploaded to New Relic to allow the mobile crash reports to be properly symbolicated. These dSYMs can be downloaded through the archives organizer in Xcode within several minutes of uploading the app. In this situation follow the procedures to find the archive and download dSYMs.

If an app is missing a dSYM file, you'll see three indicators in the mobile monitoring UI:

• Banner notification: A banner warning appears on the Crash report page. The warning reads:

We were unable to locate your dsym.

• Upload prompt: From the Crash type summary page you will be automatically prompted to upload a dSYM file if it is missing.
• Machine code: The crash stack trace on the Crash report page displays machine code and not a human-readable error message.

Upload dSYM files through the mobile monitoring UI

You can easily upload your dSYM files directly from the New Relic UI. For size limits, see Limitations. To upload your dSYM files:

1. Go to one.newrelic.com > All capabilities > Mobile. Then select your app from the list.
2. View Crashes.
3. Select a specific crash from the Total crashes in Group crashes.
4. Click Upload dSYM. You can either drag and drop your dSYMs directly, or select the file from your computer.

Manually upload dSYM files

In some circumstances, New Relic's automatic upload of dSYM files may fail. For example, if there's a network failure and the upload isn't completed, upload_dsym_results.log records what went wrong. For additional information about how New Relic handles dSYM uploads, see New Relic's Online Technical Community.

If the automatic upload fails, you can manually upload your dSYM file. If you have multiple dSYM files, they can be within a single zip. For size limits, see Limitations. The YOUR_NEW_RELIC_APPLICATION_TOKEN value in the commands below is the same key used for +[NewRelic startWithApplicationToken:] (in Objective-C) or NewRelic.start(withApplicationToken:) (in Swift).

In the commands below, use full paths or $HOME. The shell doesn't expand ~ inside quotes.

To manually upload your dSYM files:

$
DWARF_DSYM_FOLDER_PATH="DSYM_FOLDER_PATH" /usr/bin/xcrun --sdk macosx swift "SCRIPT_PATH/run-symbol-tool.swift" "YOUR_NEW_RELIC_APPLICATION_TOKEN" -appVersion "APP_VERSION"

Troubleshooting

The run-symbol-tool script writes upload_dsym_results.log to your project's root directory on every build, whether the upload succeeds or fails. Each build overwrites the previous log. To write more detail to the log, add the --debug argument.

If your build log shows upload_dsym_results.log: Operation not permitted, see Automatic dSYM upload failures.

Missing dSYMs

If dSYM files are missing, you may need to check Xcode build settings to ensure the file is being generated. Frameworks which are built locally have separate build settings and may need to be updated as well.

Build settings:

Debug Information Format : Dwarf with dSYM File
Deployment Postprocessing: Yes
Strip Linked Product: Yes
Strip Debug Symbols During Copy : Yes

Limitations

Be aware of these size limits:

• Zipped dSYM uploads through the mobile monitoring UI or the command line can be up to 600 MB.
• The automatic script doesn't upload zipped map files larger than 200 MB. See How the script works.