Upload and manage symbol files for mobile applications
Android iOS tvOS
For details on source maps for web applications, see Source map support for JavaScript error analysis.
Deobfuscation (Android) or symbolication (iOS and tvOS) 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 or tvOS 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 and tvOS, for which the dSYM files have been provided. Symbolication of system library stack trace lines is not supported.
Note that you can upload a symbol file of up to 100 MiB compressed; the uncompressed file must not exceed 500 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.
The DSSClient enables you to deobfuscate mobile application crash reports or handled exceptions.
You can use the DSSClient only on machines running macOS.
Get the DSSClient
You can download the DSSClient from the Dynatrace web UI.
- Go to Mobile.
- Select the mobile application that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your application name.
- From the application settings, select 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:
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
android
).com.yourcompany.app
.build.gradle
filebuild.gradle
filebuild/outputs/mapping/release/mapping.txt
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
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.
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.
You can also use the Dynatrace web UI to upload your application's mapping files either via environment settings or application settings.
Upload symbol files for iOS and tvOS
For iOS or tvOS symbolication, you need to preprocess dSYM files using the DSSClient before you can upload them to Dynatrace.
The DSSClient enables you to symbolicate mobile application crash reports or handled exceptions.
Get dSYM files
Get the DSSClient
Preprocess dSYM files
Upload 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
Use the dSYM files from the app's .xcarchive
or build directory.
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.
You can download the DSSClient from the Dynatrace web UI.
- Go to Mobile.
- Select the mobile application that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your application name.
- From the application settings, select 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:
# For dSYM files downloaded using Xcode's app archiveDTXDssClient -decode symbolsfile=easyTravelApp.xcarchive# For dSYM files from App Store ConnectDTXDssClient -decode symbolsfile=appDsyms.zip
Upload 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
tvOS
or iOS
.your_app_name.xcarchive/dSYMs
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
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
Use the dSYM files from the app's .xcarchive
or build directory.
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.
You can download the DSSClient from the Dynatrace web UI.
- Go to Mobile.
- Select the mobile application that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your application name.
- From the application settings, select 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:
# For dSYM files downloaded using Xcode's app archiveDTXDssClient -decode symbolsfile=easyTravelApp.xcarchive# For dSYM files from App Store ConnectDTXDssClient -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.
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.
You can also use the Dynatrace web UI to upload symbol files to Dynatrace.
Get dSYM files
Get the DSSClient
Preprocess dSYM files
Upload processed files via Dynatrace web 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
Use the dSYM files from the app's .xcarchive
or build directory.
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.
You can download the DSSClient from the Dynatrace web UI.
- Go to Mobile.
- Select the mobile application that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your application name.
- From the application settings, select 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:
# For dSYM files downloaded using Xcode's app archiveDTXDssClient -decode symbolsfile=easyTravelApp.xcarchive# For dSYM files from App Store ConnectDTXDssClient -decode symbolsfile=appDsyms.zip
Upload processed files via Dynatrace web UI
You can also use the Dynatrace web UI to upload symbol files either via environment settings or application settings.
Manage uploaded symbol files
You can use the Dynatrace web UI to manage the previously uploaded Android mapping files and iOS or tvOS symbol extract files.
To list the uploaded symbol files for a particular application
- Go to Mobile.
- Select the mobile application that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your application name.
- From the application settings, select Symbol files.
To list the uploaded source maps and symbol files for all your applications
- Go to Settings.
- Select Web and mobile monitoring > Source maps and symbol files.
The page displays the amount of storage that is currently used and the storage limit. When the storage limit is reached, Dynatrace begins deleting source maps and symbol files, starting with the oldest ones.
For Dynatrace SaaS, the maximum storage size for source maps and symbol files is 1 GiB.
To free up space, you can manually delete files that you no longer need. Select Delete in the row of the file you want to delete.
To prevent files from being automatically deleted when the storage limit is reached, turn on Pinned for the source maps and symbol files that you want to keep.
Alternatively, you can use the Mobile Symbolication API to view, pin, or delete your symbol files.