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:

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.
Upload mapping files via DSSClientThe 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.
- In the Dynatrace menu, go to Mobile.
- Select the mobile app that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your app name.
- From the app settings, go to Symbol files.
- Scroll to the bottom of the page, and follow the DSSClient link.
- 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:
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 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 mapping file you want to upload. | build/outputs/mapping/release/mapping.txt |
server | The 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:
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 Dynatrace web UIYou can also use the Dynatrace web UI to upload your app's mapping files to Dynatrace.
- From the Dynatrace menu, go to Settings > Web and mobile monitoring > Source maps and symbol files.
- Under Android, select Upload files.
- Select your application from the list.
- Provide the Package name—the app's package name, such as
com.yourcompany.app
.
- Enter the Version code and Version name that you can find in the
build.gradle
file.
- Select Select the file you want to upload, and then choose your mapping file.
- 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 DSSClientThe 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
- Sign in to App Store Connect.
- Select My Apps > your application > Test Flight > Builds.
- From the list of builds, select the build number for which you need the dSYM files.
- Go to the Build Metadata tab, and select Download dSYM.
To download dSYM files using Xcode's app archive
- From the Xcode menu, select Window > Organizer > Archives > your mobile app.
- Select the archive with the required app version and build number.
- Select Download Debug Symbols.
- 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
- In the Dynatrace menu, go to Mobile.
- Select your mobile application.
- Select More (…) > Edit > Symbol files.
- Scroll to the bottom of the page, and follow the DSSClient link.
- 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:
DTXDssClient -decode symbolsfile=appDsyms.zip
Step 4. Upload iOS symbol extract files via DSSClient
Upload the processed files to Dynatrace using the DSSClient.
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 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—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, 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:
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 APIThe 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
- Sign in to App Store Connect.
- Select My Apps > your application > Test Flight > Builds.
- From the list of builds, select the build number for which you need the dSYM files.
- Go to the Build Metadata tab, and select Download dSYM.
To download dSYM files using Xcode's app archive
- From the Xcode menu, select Window > Organizer > Archives > your mobile app.
- Select the archive with the required app version and build number.
- Select Download Debug Symbols.
- 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
- In the Dynatrace menu, go to Mobile.
- Select your mobile application.
- Select More (…) > Edit > Symbol files.
- Scroll to the bottom of the page, and follow the DSSClient link.
- 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:
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 pluginYou 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 UIYou 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
- Sign in to App Store Connect.
- Select My Apps > your application > Test Flight > Builds.
- From the list of builds, select the build number for which you need the dSYM files.
- Go to the Build Metadata tab, and select Download dSYM.
To download dSYM files using Xcode's app archive
- From the Xcode menu, select Window > Organizer > Archives > your mobile app.
- Select the archive with the required app version and build number.
- Select Download Debug Symbols.
- 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
- In the Dynatrace menu, go to Mobile.
- Select your mobile application.
- Select More (…) > Edit > Symbol files.
- Scroll to the bottom of the page, and follow the DSSClient link.
- 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:
DTXDssClient -decode symbolsfile=appDsyms.zip
Step 4. Upload processed files to Dynatrace via UI
To upload symbol files through the Dynatrace web UI
- From the Dynatrace menu, go to Settings > Web and mobile monitoring > Source maps and symbol files.
- Under iOS or tvOS, select Upload files.
- Select your application from the dropdown list.
- Provide the Bundle identifier, in other words, the app's
bundleId
that can be found in App's target > General > Bundle Identifier.
- 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.
- Select Select the file you want to upload, and open your symbol file.
- 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.
To list your uploaded symbol files
- In the Dynatrace menu, go to Settings.
- 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.