Analyzing iOS app crashes with dSYM files (public preview)

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.

Uploading dSYM files

You can upload compressed dSYM files up to 100 MB.

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

Ensure that the following prerequisites are met before uploading a dSYM file:

  • An API token is created with configuration permissions 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 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.

      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.

  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="$UNIQUE_ID_OF_CURRENT_VERSION_OF_APP, for example myapp-1.0"' \
         -F 'fileType="dSYM"' \
         -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="$UNIQUE_ID_OF_CURRENT_VERSION_OF_APP, for example myapp-1.0"' \
         -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="$UNIQUE_ID_OF_CURRENT_VERSION_OF_APP, for example myapp-1.0"' \
           -F 'fileType="dSYM"'

Removing a dSYM file from Instana

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'