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:

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.
Note that you can upload symbol files up to 100 MiB.

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.

Get the DSSClient

Upload mapping files via DSSClient

You can use the DSSClient only on machines running macOS.

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.

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

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:

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.

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 DSSClient

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

Get dSYM files

Get the DSSClient

Preprocess dSYM files

Upload iOS symbol extract files via DSSClient

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

Get dSYM files

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

Bitcode-enabled builds distributed to App Store using Xcode 13

For builds done with Xcode 13 and 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.

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.

All other builds

Use the dSYM files from the app's .xcarchive or build directory in the following cases:

All other builds done with Xcode 13 (not Bitcode-enabled, Ad-Hoc or Enterprise distribution, and local builds)
All builds done with Xcode 14+

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 (see next step).

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

Preprocess dSYM files

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

shell
# For dSYM files downloaded using Xcode's app archive
DTXDssClient -decode symbolsfile=easyTravelApp.xcarchive

# For dSYM files from App Store Connect
DTXDssClient -decode symbolsfile=appDsyms.zip

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

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:

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.

Get dSYM files

Get the DSSClient

Preprocess dSYM files

Upload processed files to Dynatrace via API

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

Get dSYM files

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

Bitcode-enabled builds distributed to App Store using Xcode 13

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.

All other builds

Use the dSYM files from the app's .xcarchive or build directory in the following cases:

All other builds done with Xcode 13 (not Bitcode-enabled, Ad-Hoc or Enterprise distribution, and local builds)
All builds done with Xcode 14+

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 (see next step).

Get the DSSClient

You can use the DSSClient only on machines running macOS.

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

Preprocess dSYM files

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

shell
# For dSYM files downloaded using Xcode's app archive
DTXDssClient -decode symbolsfile=easyTravelApp.xcarchive

# For dSYM files from App Store Connect
DTXDssClient -decode symbolsfile=appDsyms.zip

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.

Get dSYM files

Get the DSSClient

Preprocess dSYM files

Upload processed files to Dynatrace via UI

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

Get dSYM files

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

Bitcode-enabled builds distributed to App Store using Xcode 13

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.

All other builds

Use the dSYM files from the app's .xcarchive or build directory in the following cases:

All other builds done with Xcode 13 (not Bitcode-enabled, Ad-Hoc or Enterprise distribution, and local builds)
All builds done with Xcode 14+

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 (see next step).

Get the DSSClient

You can use the DSSClient only on machines running macOS.

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

Preprocess dSYM files

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

shell
# For dSYM files downloaded using Xcode's app archive
DTXDssClient -decode symbolsfile=easyTravelApp.xcarchive

# For dSYM files from App Store Connect
DTXDssClient -decode symbolsfile=appDsyms.zip

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.

Alternatively, you can use the Mobile Symbolication API to view, pin, or delete your symbol 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.