Upload and manage symbol files for mobile apps

Deobfuscation (Android) or symbolication (iOS) is the process of making classes and methods human-readable in a crash report stack trace.

The following example is an Android stack trace, before and after deobfuscation:

Android stack trace before and after deobfuscation

Dynatrace enables you to manage the ProGuard mapping and iOS symbol extract files required to interpret mobile stack traces received by Dynatrace.

Dynatrace supports three different ways of uploading symbol files:

  • Through a symbolication service known as "Deobfuscation and Symbolication Service" (DSS)
  • Via a REST API
  • Through the Dynatrace web UI

Upload symbol files through the DSSClient

The DSSClient enables you to deobfuscate (Android) or symbolicate (iOS) mobile application crash reports or handled exceptions.

You can use the DSSClient only on machines running macOS.

For Android, the ProGuard mapping files are uploaded in their original form. For iOS symbolication, the DSSClient processes the symbol files (.dSYMs) and uploads them to Dynatrace.

The DSSClient is bundled with OneAgent for iOS, and you can find it in the release package under Symbolication/DTXDssClient. If you haven't downloaded OneAgent for iOS, you can get the DSSClient from the Dynatrace UI.

To download the DSSClient from the Dynatrace web UI

  1. In the Dynatrace menu, go to Mobile.
  2. Select your mobile application.
  3. Select Browse () > Edit > Symbol files.
  4. Scroll to the bottom of the page, and follow the DSSClient link.

dSYM files to use

For builds distributed with the App Store or TestFlight, download the required .dSYM files from App Store Connect or Xcode, which adds them to the .xcarchive that was added to Xcode's Organizer window. This is necessary for all builds that have Bitcode enabled as those binaries are recompiled by Apple and the resulting .dSYM files have different UUIDs than in the original build.

For all other builds (not Bitcode-enabled, Ad-Hoc or Enterprise distribution, and local builds), use the .dSYM files from the app's .xcarchive or build directory.

Each build generates .dSYM files containing different UUIDs that you need to upload to Dynatrace.

macOS Catalina and later

On macOS Catalina, the system denies running the DSSClient on first launch and displays a warning dialog. Cancel the warning dialog, go to System Preferences > Security & Privacy, and select Open Anyway to allow running the DSSClient. You need to do that only once, and this behavior is caused by the DSSClient referencing Xcode's LLDB framework, which is not accepted by Gatekeeper, regardless of DSSClient being notarized.

Usage

You can customize the DSSClient in multiple ways. For a detailed overview of all possible parameters, start it with -h.

Upload Android mapping file

DTXDssClient -upload appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=android bundleId=org.comp.app versionStr=1.0 version=1 file=/usr/local/mapping.txt server=https://server.com
Option Definition Where to find
-upload The command flag.
appId The application ID Dynatrace uses to identify the app. Dynatrace menu > Mobile > your app settings > Instrumentation wizard
apitoken A private token that is used for secure REST API communication. Dynatrace menu > Access tokens
os The OS that should be processed (android).
bundleId The app's package name, for example, com.yourcompany.app.
versionStr The app's version name. build.gradle file
version The app's version code. build.gradle file
file The path to the ProGuard mapping file you want to upload. build/outputs/mapping/release/mapping.txt
server The URL to the Dynatrace server, for example, xyz.dynatrace.com.

Upload symbol files through the REST API

You can use the Mobile Symbolication API to automate the upload of Android ProGuard mapping files or iOS symbol files that have been preprocessed with the DSSClient (DTXDssClient -decode symbolsfile=appDsyms.zip). It comes with the following capabilities:

  • Global symbol management page for all apps in your environment
  • App-specific symbol management page
  • REST API to automate symbol file management
  • Fastlane plugin to automate the entire process, including bitcode symbol retrieval from iTunes Connect, converting the DSYMs, and uploading the symbols to Dynatrace

Upload symbol files through the Dynatrace web UI

To upload symbol files through the Dynatrace web UI

  1. From the Dynatrace menu, go to Settings > Web and mobile monitoring > Source maps and symbol files.
  2. Under Android, select Upload files.
  3. Select your application from the list.
  4. Provide the Package name—the app's package name, such as com.yourcompany.app.
  5. Enter the Version code and Version name that can be found in the build.gradle file.
  6. Select Select the file you want to upload, and then choose your symbol file.
  7. Select Upload.

Manage uploaded symbol files

To list your uploaded symbol files

  1. In the Dynatrace menu, go to Settings.
  2. Select Web and mobile monitoring > Source maps and symbol files.

This page displays the amount of storage that is currently used and the storage limit.

  • For Dynatrace SaaS, the limit is 1 GB.
  • For Dynatrace Managed, the default limit of 1 GB can be modified according to your requirements.

To free up space, you can manually delete files that you no longer need.

For a more automated approach to deleting unneeded files, turn on Pinned for the files that you want to keep. After that, whenever the storage limit is reached, Dynatrace begins deleting the symbol files that aren't pinned, starting with the oldest files.

Note that configuration rights are required for deleting or pinning an uploaded symbol file.