Analyzing iOS app crashes with dSYM files

Edit online

You can view details of iOS 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.

To translate the data, Instana requires a debug symbol (dSYM) file from the iOS app. The dSYM file is used for symbolication. Symbolication is the process of transforming an active memory address into a human-readable format.

To translate the stack trace, upload the dSYM files to Instana. You can upload dSYM files by making Web REST API calls. After the dSYM files are uploaded, more details about the crash are displayed on 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 dSYM files

Edit online

Ensure that the following prerequisites are met before you upload a dSYM 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.
  • Help ensure that the dSYM file you are uploading corresponds to the current app version. For example, each time you update your app, you must upload the updated dSYM file.

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

  1. On the Instana UI, create a configuration to upload the dSYM 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. Symbol file upload configurations view
      Screenshot showing the symbol 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 dSYM 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.

  2. Compress your dSYM files into a .tgz file:

       tar czf <archive name>.tgz <files or locations>

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

       tar czf your_app.dSYM.tgz your_app.dSYM_folder

  3. 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_dSYM_file.tgz your_dSYM_file.tgz_blob_

  4. 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="$BUNDLE_IDENTIFIER_OF_APP, for example com.instana.ios.testapp1"' \
         -F 'fileType="dSYM"' \
         -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="$BUNDLE_IDENTIFIER_OF_APP, for example com.instana.ios.testapp1"' \
         -F 'fileType="dSYM"' \
         -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.

  5. 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="$BUNDLE_IDENTIFIER_OF_APP, for example com.instana.ios.testapp1"' \
           -F 'fileType="dSYM"'

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.

Removing a dSYM file from Instana

Edit online

To remove a dSYM 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'