Analyzing Android app crashes with source-mapping files (public preview)

You can view details of Android app crashes on Instana. The details include stack traces for all the active threads of your mobile app. These stack traces contain memory address and raw function name. You can use Instana to translate the stack trace into meaningful information.

If your Android app's code is obfuscated, understanding the stack trace is difficult. If you use ProGuard, DexGuard, or R8 compiler to optimize and obfuscate the code, Instana can deobfuscate the stack trace. Instana deobfuscates the stack trace by using the mapping.txt file of your project. The mapping file maps the original class, method, and fields to the obfuscated names that make the stack traces readable.

To translate the stack trace, upload the mapping.txt file to Instana. You can upload a mapping file by making web REST API calls. After the mapping file is uploaded, more details about the crash are displayed in the Instana UI. To view the details, click Crashed Threads on the Crashes tab. For more information, see Crashes.

Uploading mapping files
Removing a mapping file from Instana

Uploading mapping files

You can upload a compressed mapping file up to 100 MB.

To upload a compressed mapping file that exceeds 100 MB, contact the Instana support team.

Ensure that the following prerequisites are met before you upload a mapping file:

An API token is created with configuration permissions that are enabled for Mobile App monitoring. For more information, see API Tokens.
Source maps are stored for Self-Hosted Custom Edition (Kubernetes or Red Hat OpenShift Container Platform). For more information, see Configuring external storage.

To upload a mapping file to Instana, complete the following steps:

On the Instana UI, create a configuration to upload the mapping file:
1. Go to Websites & Mobile Apps > Mobile Apps.
2. Click a mobile app. The mobile app dashboard is displayed.
3. Click Configuration > Stack Trace Translation.
4. Click Add Configuration. The New Symbol File Upload Configuration dialog is displayed.
5. In the Description field, enter a description for the upload.
6. Click Create. The Edit Symbol File Upload Configuration dialog is displayed. Use the web REST APIs that are displayed in the dialog to upload the mapping file. See step 3.
7. Click Save. The configuration is saved.

Compress your mapping file into a .tgz file:

   tar czf <archive name>.tgz <mapping_file>

An example of the command is shown in the following snippet:

   tar czf your_app.mapping.tgz your_app.mapping.txt

If the compressed file size exceeds 10 MB, split the .tgz file into multiple blobs (each 9 MB):
```
   split -b 9m <archive name>.tgz <file>.tgz_blob_
```
An example of the command is shown in the following snippet:
```
   split -b 9m your_mapping_file.tgz your_mapping_file.tgz_blob_
```

Upload the file by using the Instana web REST API. Complete one of the following steps:

If the upload contains multiple blobs, run:

    curl -L -X PUT \
         'https://$UNIT-$TENANT.instana.io/api/mobile-app-monitoring/config/$MOBILE_APP_ID/sourcemap-upload/$UPLOAD_CONFIG_ID/form' \
         -H 'authorization: apiToken $API_TOKEN' \
         -F 'fileId="$IDENTIFIER_OF_APP_BUNDLE-$APP_VERSION, for example com.example.myapp-1.0.3"' \
         -F 'fileType="R8PG_MAP"' \
         -F 'blobIndex=1' \
         -F 'sourceMap=@"$LOCAL_SYMBOLFILE_LOCATION"'

The blob index starts from 1, not 0.

If the upload contains only one file, run:

    curl -L -X PUT \
         'https://$UNIT-$TENANT.instana.io/api/mobile-app-monitoring/config/$MOBILE_APP_ID/sourcemap-upload/$UPLOAD_CONFIG_ID/form' \
         -H 'authorization: apiToken $API_TOKEN' \
         -F 'fileId="$IDENTIFIER_OF_APP_BUNDLE-$APP_VERSION, for example com.example.myapp-1.0.3"' \
         -F 'fileType="R8PG_MAP"' \
         -F 'sourceMap=@"$LOCAL_SYMBOLFILE_LOCATION"'

If the size of the compressed file exceeds 10 MB, an error message request entity too large is displayed. See step 3.

Commit upload:

      curl -L -X PUT \
           'https://$UNIT-$TENANT.instana.io/api/mobile-app-monitoring/config/$MOBILE_APP_ID/sourcemap-upload/$UPLOAD_CONFIG_ID/commit' \
           -H 'authorization: apiToken $API_TOKEN' \
           -F 'fileId="$IDENTIFIER_OF_APP_BUNDLE-$APP_VERSION, for example com.example.myapp-1.0.3"' \
           -F 'fileType="R8PG_MAP"'

Removing a mapping file from Instana

To remove a mapping file from Instana, complete one of the following steps:

Go to Websites & Mobile Apps > Mobile Apps > Configuration > Stack Trace Translation, and then click the Delete icon against the configuration.

Make a web REST API call. A sample command is shown in the following example:

   curl -L -X PUT \
      'https://$UNIT-$TENANT.instana.io/api/mobile-app-monitoring/config/$MOBILE_APP_ID/sourcemap-upload/$UPLOAD_CONFIG_ID/clear' \
        -H 'authorization: apiToken $API_TOKEN'