• Home
  • How to use Dynatrace
  • RUM
  • How to use
  • Mobile and custom applications
  • Manage symbol files

Upload and manage symbol files for mobile applications

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 Android mapping files and iOS symbol extract files required to interpret mobile stack traces that Dynatrace receives.

Dynatrace supports three different ways of uploading these files:

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

Currently, Dynatrace only supports symbolication of stack trace lines from applications and third-party libraries on iOS, for which the dSYM files have been provided. Symbolication of system library stack trace lines is not supported.

You need the Change monitoring settings permission to upload source maps and symbol files.

Upload mapping files for Android

For Android, upload your app's mapping files in their original form. You do not need to preprocess these files.

To learn more about mapping files and where to find them, check the official Android documentation.

Upload mapping files via DSSClient

The DSSClient enables you to deobfuscate mobile application crash reports or handled exceptions.

You can use the DSSClient only on machines running macOS.

Step 1. Get the DSSClient

You can download the DSSClient from the Dynatrace web UI.

  1. In the Dynatrace menu, go to Mobile.
  2. Select the mobile app that you want to configure.
  3. Select More (…) > Edit in the upper-right corner of the tile with your app name.
  1. From the app settings, go to Symbol files.
  2. Scroll to the bottom of the page, and follow the DSSClient link.
  3. Run the DSSClient.

    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.
    This behavior is caused by the DSSClient referencing Xcode's LLDB framework, which is not accepted by Gatekeeper, regardless of the DSSClient being notarized.

Step 2. Upload mapping files via DSSClient

Upload your app's mapping file to Dynatrace in their original form. Run the following command in the DSSClient:

shell
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
OptionDefinitionWhere to find
-uploadThe command flag.—
appIdThe application ID Dynatrace uses to identify the app.Dynatrace menu > Mobile > your app settings > Instrumentation wizard
apitokenA private token used for secure REST API communication.Dynatrace menu > Access tokens
osThe OS that should be processed (android).—
bundleIdThe app's package name, for example, com.yourcompany.app.—
versionStrThe app's version name.build.gradle file
versionThe app's version code.build.gradle file
fileThe path to the mapping file you want to upload.build/outputs/mapping/release/mapping.txt
serverThe URL to the Dynatrace server, for example, xyz.dynatrace.com.—

For a detailed overview of all possible parameters, start the DTXDssClient binary with -h.

Should you need to delete the mapping files, use the following command:

shell
DTXDssClient -delete appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=android bundleId=org.comp.app versionStr=1.0 version=1 server=https://server.com
Upload mapping files via REST API

The Mobile Symbolication API allows you to automate the upload of Android mapping files.

To upload your app's mapping files to Dynatrace, use the PUT upload file for an app version method.

Upload mapping files via Fastlane plugin

You can leverage the Dynatrace Fastlane plugin to automate the entire process of delivering Android mapping files to Dynatrace.

For more information and detailed instructions, check the plugin documentation on GitHub.

Upload mapping files via Dynatrace web UI

You can also use the Dynatrace web UI to upload your app's mapping files to Dynatrace.

  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 you can find in the build.gradle file.
  6. Select Select the file you want to upload, and then choose your mapping file.
  7. Select Upload.

Upload symbol files for iOS

For iOS symbolication, you need to preprocess dSYM files using the DSSClient before you can upload them to Dynatrace.

Upload symbol files via DSSClient

The DSSClient enables you to symbolicate mobile application crash reports or handled exceptions.

For iOS, you need to get the dSYM files, preprocess them using the DSSClient, and then upload the resulting files to Dynatrace.

Step 1. Get dSYM files

The location of dSYM files depends on your app's build type:

  • Builds distributed with App Store or TestFlight: Download the required dSYM files from App Store Connect or Xcode, which adds them to the app's .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.

  • 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.

To download dSYM files from App Store Connect

  1. Sign in to App Store Connect.
  2. Select My Apps > your application > Test Flight > Builds.
  3. From the list of builds, select the build number for which you need the dSYM files.
  4. Go to the Build Metadata tab, and select Download dSYM.

To download dSYM files using Xcode's app archive

  1. From the Xcode menu, select Window > Organizer > Archives > your mobile app.
  2. Select the archive with the required app version and build number.
  3. Select Download Debug Symbols.
  4. Right-click the downloaded archive, and select Show in Finder. Use the revealed .xcarchive file as an input in the DSSClient.

Step 2. Get the DSSClient

You can use the DSSClient only on machines running macOS.

The DSSClient is bundled with OneAgent, and you can find it in the release package under Symbolication/DTXDssClient. If you haven't downloaded OneAgent, you can get the DSSClient from the Dynatrace web 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 More (…) > Edit > Symbol files.
  4. Scroll to the bottom of the page, and follow the DSSClient link.
  5. Run the DSSClient.

    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.
    This behavior is caused by the DSSClient referencing Xcode's LLDB framework, which is not accepted by Gatekeeper, regardless of the DSSClient being notarized.

Step 3. Preprocess dSYM files

Preprocess your app's dSYM files before you upload them to Dynatrace. Run the following command in the DSSClient:

shell
DTXDssClient -decode symbolsfile=appDsyms.zip

Step 4. Upload iOS symbol extract files via DSSClient

Upload the processed files to Dynatrace using the DSSClient.

shell
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
OptionDefinitionWhere to find
-uploadThe command flag.—
appIdThe application ID Dynatrace uses to identify the app.Dynatrace menu > Mobile > your app settings > Instrumentation wizard
apitokenA private token that is used for secure REST API communication.Dynatrace menu > Access tokens
osThe OS that should be processed—either tvOS or iOS.—
bundleIdThe app's bundleId.App's target > General > Bundle Identifier
bundleNameThe app's bundleName.App's target > General > Display Name
versionStrThe app's version string.App's target > General > Version
versionThe app's version.App's target > General > Build
symbolsFileThe path to the folder containing the app's dSYM files.your_app_name.xcarchive/dSYMs
serverThe URL to the Dynatrace server, for example, xyz.dynatrace.com.—

For a detailed overview of all possible parameters, start the DTXDssClient binary with -h.

Should you need to delete the symbol files, use the following command:

shell
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
Upload symbol files via REST API

The Mobile Symbolication API enables you to automate the upload of your symbol files.

For iOS, you need to get the dSYM files, preprocess them using the DSSClient, and then upload the resulting files to Dynatrace.

Step 1. Get dSYM files

The location of dSYM files depends on your app's build type:

  • Builds distributed with App Store or TestFlight: Download the required dSYM files from App Store Connect or Xcode, which adds them to the app's .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.

  • 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.

To download dSYM files from App Store Connect

  1. Sign in to App Store Connect.
  2. Select My Apps > your application > Test Flight > Builds.
  3. From the list of builds, select the build number for which you need the dSYM files.
  4. Go to the Build Metadata tab, and select Download dSYM.

To download dSYM files using Xcode's app archive

  1. From the Xcode menu, select Window > Organizer > Archives > your mobile app.
  2. Select the archive with the required app version and build number.
  3. Select Download Debug Symbols.
  4. Right-click the downloaded archive, and select Show in Finder. Use the revealed .xcarchive file as an input in the DSSClient.

Step 2. Get the DSSClient

You can use the DSSClient only on machines running macOS.

The DSSClient is bundled with OneAgent, and you can find it in the release package under Symbolication/DTXDssClient. If you haven't downloaded OneAgent, you can get the DSSClient from the Dynatrace web 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 More (…) > Edit > Symbol files.
  4. Scroll to the bottom of the page, and follow the DSSClient link.
  5. Run the DSSClient.

    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.
    This behavior is caused by the DSSClient referencing Xcode's LLDB framework, which is not accepted by Gatekeeper, regardless of the DSSClient being notarized.

Step 3. Preprocess dSYM files

Preprocess your app's dSYM files before you upload them to Dynatrace. Run the following command in the DSSClient:

shell
DTXDssClient -decode symbolsfile=appDsyms.zip

Step 4. Upload processed files to Dynatrace via API

Upload the processed symbol files using the PUT upload file for an app version method.

Upload symbol files via Fastlane plugin

You can leverage the Dynatrace Fastlane plugin to automate the entire process, including getting dSYMs files from App Store Connect, preprocessing the files, and uploading the files to Dynatrace.

For more information and detailed instructions, check the plugin documentation on GitHub.

Upload symbol files via Dynatrace web UI

You can also use the Dynatrace web UI to upload iOS symbol files to Dynatrace.

For iOS, you need to get the dSYM files, preprocess them using the DSSClient, and then upload the resulting files to Dynatrace.

Step 1. Get dSYM files

The location of dSYM files depends on your app's build type:

  • Builds distributed with App Store or TestFlight: Download the required dSYM files from App Store Connect or Xcode, which adds them to the app's .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.

  • 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.

To download dSYM files from App Store Connect

  1. Sign in to App Store Connect.
  2. Select My Apps > your application > Test Flight > Builds.
  3. From the list of builds, select the build number for which you need the dSYM files.
  4. Go to the Build Metadata tab, and select Download dSYM.

To download dSYM files using Xcode's app archive

  1. From the Xcode menu, select Window > Organizer > Archives > your mobile app.
  2. Select the archive with the required app version and build number.
  3. Select Download Debug Symbols.
  4. Right-click the downloaded archive, and select Show in Finder. Use the revealed .xcarchive file as an input in the DSSClient.

Step 2. Get the DSSClient

You can use the DSSClient only on machines running macOS.

The DSSClient is bundled with OneAgent, and you can find it in the release package under Symbolication/DTXDssClient. If you haven't downloaded OneAgent, you can get the DSSClient from the Dynatrace web 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 More (…) > Edit > Symbol files.
  4. Scroll to the bottom of the page, and follow the DSSClient link.
  5. Run the DSSClient.

    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.
    This behavior is caused by the DSSClient referencing Xcode's LLDB framework, which is not accepted by Gatekeeper, regardless of the DSSClient being notarized.

Step 3. Preprocess dSYM files

Preprocess your app's dSYM files before you upload them to Dynatrace. Run the following command in the DSSClient:

shell
DTXDssClient -decode symbolsfile=appDsyms.zip

Step 4. Upload processed files to Dynatrace via 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 iOS or tvOS, select Upload files.
  3. Select your application from the dropdown list.
  4. Provide the Bundle identifier, in other words, the app's bundleId that can be found in App's target > General > Bundle Identifier.
  5. Enter the Bundle version that exists in App's target > General > Version and the Bundle version string that exists in App's target > General > Build.
  6. Select Select the file you want to upload, and open your symbol file.
  7. Select Upload.

Manage uploaded symbol files

You can use the Dynatrace web UI to manage the previously uploaded Android mapping files and iOS symbol extract files.

Alternatively, you can use the Mobile Symbolication API to view, pin, or delete your 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 maximum storage size for symbol and mapping files is 1 GB.
  • For Dynatrace Managed, the default storage size for symbol and mapping files is 1 GB. You can modify the storage size 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.