Mobile symbolication service

The Symbolication Service (also known as DSS, or De-obfuscation and Symbolication Service) allows you to symbolicate (iOS) or de-obfuscate (Android) mobile application crash reports or handled exceptions. This allows you to view the classes and methods in the stack trace in plain text.

Enable the symbolication service and set storage

By default the Symbolication Service is not enabled at the time the AppMon Server is installed. To enable the service:

  1. In the AppMon Client, select the Settings menu > Dynatrace Server > Services item > Symbolication Service tab. Select the Enable Deobfuscation and Symbolication Service check box and click OK.
  2. Return to the Symbolication Service tab and set the File Storage Location and Limit as needed for crash reports and unhandled exceptions. The default value of 0 indicates there is no storage limit for these files.

Symbolication service REST API

The symbolication service provides a set of REST calls to manage the ProGuard mapping and iOS symbol extract files needed to interpret the mobile stack traces when they arrive at the AppMon Server.

By default the REST server service is available at https://<DynatraceServer>:8021/rest/dss (SSL) or http://<DynatraceServer>:8020/rest/dss or ay the port, configured for HTTP(S). You can check these at Settings menu > Dynatrace Server > Services item > Management tab.

Use a REST client to execute the calls or the DSS Client (wrapper for REST) described below for additional command line functionality.

Path & Description Method
rest/dss/status

Gets DSS status. The dss-* header items tells whether the ProGuard libraries or the Symbol File Manager are configured and the DSS is enabled / running.
HEAD
rest/dss/info

Tells the DSS status plus the version, the number of mapping files, disk space available and used and disk quota (if any).
HEAD
rest/dss/symbolfiles

Lists all iOS symbol extract files and ProGuard mapping files
GET
rest/dss/symbolfiles/ios

Lists all symbol extract files
GET
rest/dss/symbolfiles/ios/apps/{AppName}

Lists all symbol extract files for {AppName}
GET
rest/dss/symbolfiles/ios/apps/{AppName}/versions/{AppVersion}

Lists all symbol extract files for {AppName} version {AppVersion}
GET
rest/dss/symbolfiles/android

Lists all mapping files
GET
rest/dss/symbolfiles/android/apps/{AppName}

Lists all mapping files for {AppName}
GET
rest/dss/symbolfiles/android/apps/{AppName}/versions/{AppVersion}

Lists all mapping files for {AppName} version {AppVersion}
GET
rest/dss/symbolfiles/ios/apps/{AppName}/versions/{AppVersion}/builds/{uuid}/time/{buildtime}

Uploads a symbol extract file for {AppName} version {AppVersion} with {uuid} and build time {buildtime}, where {uuid} must be in the form of architecture.uuid. For example arm64.020a290c987237f6a7d5dbb08d11ed5d.

Be sure to specify the content-type of application/zip if the content is in PKZip format.
PUT
rest/dss/symbolfiles/android/apps/{AppName}/versions/{AppVersion}

Uploads a mapping file for {AppName} version {AppVersion}. Be sure to specify the content-type of application/zip if the content is in PKZip format.
PUT
rest/dss/symbolfiles/ios/apps/{AppName}/versions/{AppVersion}
rest/dss/symbolfiles/android/apps/{AppName}/versions/{AppVersion}

Deletes symbol extract/mapping files for {AppName} version {AppVersion}
DELETE
rest/dss/symbolfiles/ios/apps/{AppName}?versionsOlderThan=1.2.3
rest/dss/symbolfiles/android/apps/{AppName}?versionsOlderThan=1.2.3

Deletes symbol extract/mapping files for {AppName} versions older than 1.2.3
DELETE

DSS client

Beyond a GET in the browser address bar or a REST client GUI, the DSS client provides command line functionality for automation.

As of AppMon 6.3 you can find DSS clients in the Mobile ADK zip.
The dss-client.bat and dss-client shell script to start the Java-based utility are in the <MobileADKUnzipDir>/Android/dss/bin.
The <MobileADKUnzipDir>/Android/dss/lib/dss-client-<version>.jar referenced in the OS-specific shell scripts can also be directly used as shown further below.
The Mac-native DTXDssClient utility is in <MobileADKUnzipDir>/iOS/dss.
You must make the Linux and Mac versions executable first with chmod +x <filename>, as this attribute is not preserved by the zip container.

Generic syntax

<dss-client-for-platform-file> server=<protocol>://<DynatraceServer>:<port> username=<user> password=<pass> [-help|-info|-status|-delete|-list|-file=<file>] [os=ios|android] [appname=<appname> [uuid=<uuid> buildtime=<buildtime>]] [version=<version> | versionsOlderThan=<version> ]

Use the following to test if the command works and the file is executable. No AppMon Server connection is necessary:

cd <locationOfDssClient>  
dss-client -help

Use the following Windows SSL local example to see if the ProGuard files copy correctly and the DSS is enabled:

cd <locationOfDssClient>  
dss-client.bat server=https://localhost:8021 username=admin password=admin -info

Required parameters

Option Value
server The full URL, including protocol and port of the AppMon Server running the DSS service. For example, server=https://localhost:8021.
username A username to connect to this Server, as used in the AppMon Client.
password You are prompted for a password if you don't specify one in the command line parameters.

Flags

The -info, -status, -list, -delete and -file flags are equivalent to the REST /<subPathOrMethod>. Only one flag is allowed for each DSS Client operation.

Options

Use the following options with previously listed flags to upload files, filter list output, delete single or multiple files.

Option Value
os Operating system. Must be either iOS or Android.
version An integer representing the version number of your application. On Android, this corresponds to android:versionCode in AndroidManifest.xml. On iOS, this corresponds to CFBundleVersion.
appname The name of your application.
uuid iOS only: The UUID for the build of a particular architecture. Must be used in conjunction with buildime.
buildtime iOS only: The build time for a particular architecture. Must be used in conjunction with uuid.
versionsOlderThan Used in conjunction with the -delete flag: Delete all versions older than this integer. Example: versionsOlderThan=6 would delete versions 1-5.

Examples

Using the .jar directly:

List all Android symbol files:

java -jar dss-client.jar server=http://server.com username=user password=pass -list os=android

Upload a mapping file for Android app MyApp version 1:

java -jar dss-client.jar server=http://server.com username=user password=pass -file=myfile.zip os=android appname=MyApp version=1

Delete a mapping file for iOS app MyApp version 5:

java -jar dss-client.jar server=http://server.com username=user password=pass -delete os=ios appname=MyApp version=5

Integration with build systems

Apache ant

The dss-client.jar file is built to be directly compatible with Apache Ant builds. This can be configured automatically with the included dss.xml file, or you can define your own taskdef.

Getting started with ant - automatically detecting versionCode and app name

First, copy the dss.properties and dss-client.jar file into your project where your Android build.xml file is located. Modify the dss.properties file and set the dss.username, dss.password, dss.server, and dss.jarfile properties:

dss.username=admin
dss.password=admin
dss.server=http://myserver.local:8020
dss.jarfile=dss-client.jar
dss.mapping.file=bin/proguard/mapping.txt
dss.properties

Next, edit your Android build.xml file, which is usually located at the root of your Android project. Create a new task that depends on the Android 'release' build, imports our taskdef, and invokes the dssUpload task. Importing the dss.xml script defines the properties ${dss.server}, ${dss.username}, ${dss.password}, ${dss.appname}, ${dss.manifest.versionCode}, and ${dss.mapping.file} for you.

<import file="dss.xml" />
<target name="uploadToDss" description="Build, obfuscate, and upload mapping file to DSS" depends="release">
        <dssUpload server="${dss.server}" username="${dss.username}" password="${dss.password}" appname="${dss.appname}" version="${dss.manifest.versionCode}" file="${dss.mapping.file}" />
</target>
build.xml

Execute this task to build your Android release, obfuscate the build with ProGuard and then upload the mapping file to the DSS server automatically. A successful run looks like this:

release:
uploadToDss:
[dssUpload] Beginning file upload...................................upload complete.
[dssUpload] ==================================================================================================
[dssUpload] DSS Operation Status: OK	Bytes Uploaded: 239017
[dssUpload] Upload (ANDROID) symbol file for application 'ProguardTestApplication' version '5'
==================================================================================================
BUILD SUCCESSFUL
Total time: 17 seconds

The version number is read directly from the AndroidManifest.xml versionCode attribute. Running build against the same version updates the existing mapping file on the server. Incrementing the versionCode attribute uploads a new a mapping file linked to the new versionCode.

Advanced ant - defining your own taskdef and settings

If you don't want to import the dss.xml file and automatically, set the required dss properties, you can manually define the taskdef and then call dssUpload. First, define the taskdef in your build file:

<taskdef name="dssUpload" classname="com.dynatrace.diagnostics.dss.client.DssUploaderTask">
    <classpath>
        <pathelement location="dss-client.jar" />
    </classpath>
</taskdef>
build.xml

And then call the task, populating the parameters manually:

<dssUpload server="http://server:port" username="user" password="password" appname="MyAppName" version="1" file="bin/proguard/mapping.txt" /> 
build.xml

Other modes

Since the DSS runs as REST web service, it can be accessed in a variety of ways in addition to the DSS Client, wget, cURL, and web browsers provide a means to upload, view, and manage your mapping files.

Access using cURL examples

Get information about the DSS server, which is returned in the response headers:

curl --user <user>:<pass> -I https://server.com:8021/rest/dss/info

List all iOS symbol files for app MyApp version 5 (response in JSON):

curl --user <user>:<pass> https://server.com:8021/rest/dss/symbolfiles/ios/app/MyApp/versions/5