Analyzing Android app crashes with source-mapping files

Edit online

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.

Note: Instana does not support retroactive crash translation. Instana translates only the crashes that occur after the source maps are properly uploaded and committed.

Uploading mapping files

Edit online

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.
  
  Figure 1. Mapping file upload configurations view
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.
Note: You can upload up to 1,024 source map configurations per mobile app. The maximum storage for source map configurations per mobile app is 2,048 MB. To increase this limit, contact Instana support.
Compress your mapping file (mapping.txt) 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"'

Note: The blobIndex starts from 1, not 0. For each successive blob, increase the blobIndex by 1.

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"'

Upload all blobs before you run the commit command. You can see the number of uploaded blobs for each source map in the Instana UI. For a source map that does not use blobbing, the blob count is shown as 1.

Note: For large source maps, the commit can take some time to complete. When the commit is successful, the source map commit status shows Success.

Screenshot showing the blobs uploaded and commit status in mapping file upload configurations view — Figure 2. Mapping file upload configurations view with blobs uploaded and commit status

Removing a mapping file from Instana

Edit online

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'