Your data. Anywhere you go.

New Relic for iOS or Android


Download on the App Store    Android App on Google play


New Relic Insights App for iOS


Download on the App Store


Learn more

Close icon

Relic Solution: iOS dSYM upload deep-dive

mobile

#1

One of the most useful features of the New Relic mobile SDK is crash reporting. When a crash occurs you want to be able to see the stack trace and figure out what’s causing the crash. It’s not very helpful when all you see is machine-readable memory addresses. In this post, I’ll cover how to get your iOS dSYM file to New Relic and some common issues.

What is a dSYM?

Let’s get this out of the way first. When you create a build of an iOS or tvOS application, the names of methods and classes are stripped, leaving only machine-readable memory addresses. When the application crashes, the stack trace consists of this machine-readable code.

A dSYM file is an Xcode project file that stands for debug symbols. It contains the debugging symbols that allow for translation of the initial crash report to human-readable information. This process is known as symbolication.

How to create a dSYM?

There are several build settings to confirm to be sure your Project Target is creating a dSYM.

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

Uploading dSYMs to New Relic

There’s more than one way to upload your dSYM to New Relic. The easiest option is to use the post build script which is included with the SDK. To set this up follow step 6 of our install and configuration doc.

Add a build script to your target’s Build Phases. Ensure the new build script is the very last script. Then paste the following, replacing PUT_NEW_RELIC_APP_TOKEN_HERE with your application token:

SCRIPT=`/usr/bin/find "${SRCROOT}" -name newrelic_postbuild.sh | head -n 1`
/bin/bash "${SCRIPT}" "PUT_NEW_RELIC_APP_TOKEN_HERE"

Now your dSYM files will be automatically uploaded to New Relic after building for production or to a physical test device.

Note: Starting in Agent version 5.7.0 the post build script will upload all dSYMs associated with the app to symbolicate embedded frameworks. Before this version only the one dSYM for the app was uploaded. Please update to the latest version to take advantage of this and other improvements.

What if I need to manually upload a dSYM?

There are a few options for manually uploading the dSYM file. From the browser, you can navigate to a specific crash detail page and use our drag and drop upload UI.

There are two options for uploading dSYMs from the terminal. The dSYMs can be zipped and sent using a curl command.

Note: Be sure to use /usr/bin/zip --recurse-paths. Using a different command to archive such as tar or bzip and failing to recurse paths will cause problems.

The other option is to use the Python script included with the agent files. 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"

The DSYM_ARCHIVE_PATH can be a single zip file containing one or more dSYMs or a folder containing multiple dSYMs or zip files.

How do I make sure I’ve got the right dSYM for a crash?

To find the build uuid for a crash in Crash Analysis refer to our Find Build UUIDs for unsymbolicated crashes doc.

Use the command dwarfdump --uuid on the dSYM file to show the build uuid.

You can also use this helpful script to search a folder of dSYMs for a specific build uuid.

What if my app is Bitcode enabled?

A little background on what’s happening with dSYMs for Bitcode enabled apps. If your app is Bitcode enabled, it will be fully compiled by Apple after submitting to the App Store as Bitcode is an intermediary compile step. The dSYM needs to be downloaded from iTunes Connect.

The file that is downloaded can have more than one dSYM - one for your application binary, and others for dynamically built frameworks used by your app. This zip file can be uploaded using the curl command, Python script, or navigate to a specific crash and use our drag and drop upload UI.

What if I have a lot of dSYMs to upload?

If you have several dSYMs to upload at once, the Python script mentioned above can be used. You can specify a folder containing multiple dSYM or zip files as the DSYM_ARCHIVE_PATH value.

Troubleshooting

I’m looking at a crash report and a banner says, “We were unable to locate your dSYM.” What’s up with that?

  • You see this message if no dSYM has been uploaded or the dSYM that was uploaded did not match the build uuid for the crash. Please see above for how to find the build uuid.

I uploaded a dSYM and see this banner “We have received your dSYM and are working on processing it” But it’s been over an hour?

  • The structure of the dSYM is not correct. This can happen if you don’t recurse the paths when using zip
  • The dSYM or zip file is corrupted. Try zipping and uploading the file again

My app code is symbolicated but one or more of my 3rd party libraries still show memory addresses.

  • Dynamic libraries which are compiled when your app is built have separate build settings. These build settings should also match the settings given for the main app.
  • Static libraries my not always include symbols when they were built. These symbols are only accessible if included when originally built. New Relic includes symbols for our library.

Crash Reporting not symbolicated
Not able to symbolicate the crash
Relic Solutions: How to use different app tokens in Xcode post build script for Release vs Debug
Add API method to send custom crash
Getting error: unable to open '' when running app in XCode 10.1
Best Practices Guide: Mobile