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:

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.

Step 1

Get the DSSClient

Step 2

Upload mapping files via DSSClient

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. Go to Mobile.
  2. Select the mobile application that you want to configure.
  3. Select More (…) > Edit in the upper-right corner of the tile with your application name.
  4. From the application settings, select Symbol files.
  5. Scroll to the bottom of the page, and follow the DSSClient link.
  6. 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 web UI > Mobile > your app settings > Instrumentation wizard
apitoken
A private token used for secure REST API communication.
Dynatrace web UI > 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

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.

Step 1

Get dSYM files

Step 2

Get the DSSClient

Step 3

Preprocess dSYM files

Step 4

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.

Step 1 Get dSYM files

Use the dSYM files from the app's .xcarchive or build directory.

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

Step 2 Get the DSSClient

You can use the DSSClient only on machines running macOS.

You can download the DSSClient from the Dynatrace web UI.

  1. Go to Mobile.
  2. Select the mobile application that you want to configure.
  3. Select More (…) > Edit in the upper-right corner of the tile with your application name.
  4. From the application settings, select Symbol files.
  5. Scroll to the bottom of the page, and follow the DSSClient link.
  6. 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 one of the following commands in the DSSClient:

# 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

Step 4 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
Option
Definition
Where to find
-upload
The command flag.
—
appId
The application ID Dynatrace uses to identify the app.
Dynatrace web UI > Mobile > your app settings > Instrumentation wizard
apitoken
A private token that is used for secure REST API communication.
Dynatrace web UI > 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

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

Step 1

Get dSYM files

Step 2

Get the DSSClient

Step 3

Preprocess dSYM files

Step 4

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.

Step 1 Get dSYM files

Use the dSYM files from the app's .xcarchive or build directory.

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

Step 2 Get the DSSClient

You can use the DSSClient only on machines running macOS.

You can download the DSSClient from the Dynatrace web UI.

  1. Go to Mobile.
  2. Select the mobile application that you want to configure.
  3. Select More (…) > Edit in the upper-right corner of the tile with your application name.
  4. From the application settings, select Symbol files.
  5. Scroll to the bottom of the page, and follow the DSSClient link.
  6. 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 one of the following commands in the DSSClient:

# 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

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

Step 1

Get dSYM files

Step 2

Get the DSSClient

Step 3

Preprocess dSYM files

Step 4

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.

Step 1 Get dSYM files

Use the dSYM files from the app's .xcarchive or build directory.

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

Step 2 Get the DSSClient

You can use the DSSClient only on machines running macOS.

You can download the DSSClient from the Dynatrace web UI.

  1. Go to Mobile.
  2. Select the mobile application that you want to configure.
  3. Select More (…) > Edit in the upper-right corner of the tile with your application name.
  4. From the application settings, select Symbol files.
  5. Scroll to the bottom of the page, and follow the DSSClient link.
  6. 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 one of the following commands in the DSSClient:

# 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

Step 4 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

  1. Go to Mobile.
  2. Select the mobile application that you want to configure.
  3. Select More (…) > Edit in the upper-right corner of the tile with your application name.
  4. From the application settings, select Symbol files.

To list the uploaded source maps and symbol files for all your applications

  1. Go to Settings.
  2. 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 Remove 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.