Free trial

Upload and manage symbol files

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

The Mobile symbolication offered by DESK enables you to manage the ProGuard mapping and iOS symbol extract files that are needed to interpret mobile stack traces received by DESK.

DESK supports three different ways of uploading symbol files: through a symbolication service known as De-obfuscation and Symbolication Service (DSS), via a REST API, and through the DESK web UI.

Upload symbol files through the DSSClient

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

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

The DSSClient is bundled with OneAgent for iOS and can be found in the release package under dss/DTXDssClient.

Which dSYM file should be used

For builds distributed with the AppStore or TestFlight the required .dSYM files can be downloaded from AppStore Connect or within Xcode, which adds it to the .xcarchive that was added to Xcode's Organizer window. This is necessary for all builds that have Bitcode enabled, as those binares 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, local builds) the .dSYM files from inside the app's .xcarchive or build dirrectory can be used.

Each build generates .dSYM files containing different UUIDs that have to be uploaded to DESK.

Note: The DSSClient can only be executed on machines running macOS.

Usage

The DSSClient can be customized in multiple ways. For a detailed overview of all possible parameters start it with -h.

Upload iOS symbols from folder (all dSYMs in the folder will be processed)

DTXDssClient -upload appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=ios bundleId=org.comp.app bundleName=App versionStr=1.0 version=1 symbolsfile=/usr/local/app.xcarchive/dSYMs server=https://server.com
Option Definition Where to find?
-upload The command flag. -
appId The application id DESK uses to identify the app. DESK: Applications -> Your App -> Instrumentation
apitoken A private token that is used for secure REST API communication. DESK: Settings -> Integrations -> DESK API
os The OS that should be processed (either 'tvOS' or 'iOS'). -
bundleId The app's bundleId. App's target -> General -> Bundle Identifier
bundleName The app's bundleName. App's target -> General -> Display Name
versionStr The app's version string. App's target -> General -> Version
version The app's version. App's target -> General -> Build
symbolsFile The path to the folder containing the app's dSYM files. your_app_name.xcarchive/dSYMs
server The URL to the DESK server (e.g. xyz.desk.com). -

Delete iOS symbols for version

DTXDssClient -delete appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=ios bundleId=org.comp.app versionStr=1.0 version=1 server=https://server.com
Option Definition Where to find?
-delete The command flag. -
appId The application id DESK uses to identify the app. DESK: Applications -> Your App -> Instrumentation
apitoken A private token that is used for secure REST API communication. DESK: Settings -> Integrations -> DESK API
os The OS that should be processed (either 'tvOS' or 'iOS'). -
bundleId The app's bundleId. App's target -> General -> Bundle Identifier
versionStr The app's version name. App's target -> General -> Version
version The app's version code. App's target -> General -> Build
server The URL to the DESK server (e.g. xyz.desk.com). -

Upload symbol files through the REST API

The REST API can be used to automate upload of Android ProGuard mapping files or iOS symbol files that have been preprocessed with the DSSClient (DTXDssClient -decode symbolsfile=appDsyms.zip).

Upload symbol files through the DESK web UI

To upload symbol files through the DESK web UI

  1. Select Settings from the navigation menu.
  2. Navigate to Web & mobile monitoring > Source maps & symbol files.
  3. Depending on your operating system, click the corresponding Upload files button.
  4. Select your application from the drop list.
  5. For Android, provide the Package name (i.e., the app's package name, for example, com.yourcompany.app). For iOS, provide the Bundle identifier (i.e., the app's bundleId which can be found at App's target > General > Bundle Identifier).
  6. For Android, enter the Version code and Version name which can be found in the build.gradle file. For iOS, enter the Bundle version that exists at App's target > General > Version and the Bundle version string that exists at App's target > General > Build.
  7. Click Select the file you want to upload and select your symbol file. iOS symbol files must be preprocessed with the DSSClient before they are uploaded: (DTXDssClient -decode symbolsfile=appDsyms.zip).
  8. Click Upload.

Manage the uploaded symbol files

Navigate to Settings > Web & mobile monitoring > Source maps & symbol files, to view your uploaded symbol files. At the top of the page, you can find the amount of storage that is currently used as well as the storage limit. For DESK SaaS, the limit is 1 GB. For DESK Managed, the default limit of 1 GB can be modified according to your requirements.

To free up space, you can manually delete the files that are no longer needed. A more automated approach is to activate the Pinned switch for the files that you want to keep. Once this is done, whenever the storage limit is reached, DESK begins deleting the symbol files that aren't pinned. The oldest files are deleted first.

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