Upload dSYM files

Your app's dSYM files are stored in Xcode's dSYM archive path folder. This is the folder where New Relic Mobile gets the dSYM files that are used to symbolicate your crash reports.

New Relic provides a post-build script as part of the New Relic Mobile's iOS agent's install process and the tvOS agent's install process. This script automatically uploads your app's dSYM files.

This script uses Python 2. Starting October 2019 with Mac OS 10.15 (Catalina), Python won't be installed by default. If you're using the automatic script (recommended), you may need to manually install Python 2. If you're using Homebrew, see Python on Homebrew.

New Relic automatically uploads dSYM files only for release builds. Non-release builds must upload their files either manually or through the New Relic Mobile UI. Bitcode-enabled apps have their dSYM files generated by Apple. You must download the dSYM files for Bitcode-enabled apps from Apple and upload them to New Relic.

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.

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, a few indicators are available in the New Relic Mobile 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 New Relic Mobile UI

Automatically upload dSYM files form the New Relic Mobile UI.
Crash analysis > Crash list > Crash type summary > Upload dSYM: You can quickly upload your dSYM files directly from the New Relic Mobile UI.

You can easily upload your dSYM files directly form the New Relic Mobile UI. To upload your dSYM files:

  1. From rpm.newrelic.com/mobile, select your mobile application from the app index.
  2. View Crash analysis.
  3. Select a specific crash from the Crash types list.
  4. Click Upload dSYM. You can either drag and drop your dSYMs directly, or select the file form your computer.

    The maximum file size is 600 MB.

Manually upload dSYM files

In some circumstances, New Relic's automatic upload of dSYM files may fail. If a dSYM upload is attempted and fails, it creates a build error with a detailed message. For example, if there's a network failure and the dSYM upload isn't completed, Xcode will report an error. 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 with a maximum file size of 600 MB. 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).

To manually upload your dSYM files:

Via Python script (agent versions 6.0.0 or higher)

In iOS agent versions 6.0.0 or higher, the agent includes a Python script that automatically processes and uploads symbols. You can call this script from the command line:

NewRelicAgent.framework/Resources/generateMap.py "DSYM_ARCHIVE_PATH" "YOUR_NEW_RELIC_APPLICATION_TOKEN"
Via command line

To manually upload individual dSYM files from the command line:

  1. Zip up your dSYM file or files using the following command. Replace ~/ZIPPED_DSYM_PATH with your new dSYM archive path and file name (for example, Users/my-name/desktop). Also replace ~/dSYM_PATH with your existing dSYM file path.

    /usr/bin/zip --recurse-paths --quiet "~/ZIPPED_DSYM_PATH" "~/dSYM_PATH"
  2. Upload the dSYM zip file using the following command:

    curl -F dsym=@"~/DSYM_ZIP_PATH" -H "X-APP-LICENSE-KEY: YOUR_NEW_RELIC_APPLICATION_TOKEN" https://mobile-symbol-upload.newrelic.com/symbol

Troubleshooting

If a dSYM auto-upload failed, the Report Navigator may have a fully formed cURL command. You can use this cURL command to reattempt an upload. Depending on the error, you may also need to follow some of the dSYM manual upload steps.

Here is an example of a successful dSYM upload in the Report Navigator:

iOS-Agent-PostBuildScript-Example.png
Example: A successful dSYM upload in the Report Navigator.

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

For more help

Recommendations for learning more: