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 Dynatrace enables you to manage the ProGuard mapping and iOS symbol extract files that are needed to interpret mobile stack traces received by Dynatrace.

Dynatrace supports three different ways of uploading symbol files: through a symbolication service known as De-obfuscation and Symbolication Service (DSS), via a REST API or through the Dynatrace 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 Dynatrace. 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.

The required .dSYM files can be downloaded from App Store Connect. For local builds and enterprise distribution, they can be found inside the app's .xcarchive.

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 Dynatrace uses to identify the app. Dynatrace: Applications -> Your App -> Instrumentation
apitoken A private token that is used for secure REST API communication. Dynatrace: Settings -> Integrations -> Dynatrace 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 Dynatrace server (e.g. xyz.dynatrace.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 Dynatrace uses to identify the app. Dynatrace: Applications -> Your App -> Instrumentation
apitoken A private token that is used for secure REST API communication. Dynatrace: Settings -> Integrations -> Dynatrace 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 Dynatrace server (e.g. xyz.dynatrace.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 Dynatrace web UI

To upload symbol files through the Dynatrace 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 respective 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 need to be preprocessed with the DSSClient before uploading them (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 also find out the amount of storage that is currently used as well as the storage limit. For Dynatrace SaaS, this limit is 1 GB. For Dynatrace Managed, 1 GB is the default storage limit, which can of course be modified according to your particular needs.

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 limit is reached, all files that aren't pinned will be automatically deleted.

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