iOS symbol file management

What is a symbol table?

A symbol file is a mapping table that links memory addresses to function names, file names, and line numbers. A symbol file element has the following format:

<start address> <end address> <function> [<file name:line number>]

When an iOS app crashes, the crash stack in the log contains obfuscated binary information. You must use a symbol file to symbolicate this binary stack information. Symbolication converts the stack into readable function names and line numbers. This helps you locate the code that caused the problem.

Import an iOS symbol file

Before you can symbolicate a crash log, you must upload a symbol file. On the iOS platform, the dSYM file is the object file that stores the symbol table. The file name is usually xxx.app.dSYM. Back up the dSYM file every time you build or publish your app.

Follow these steps to upload an iOS symbol file:

1. In the directory that contains the dSYM file, run the Linux command tar -czvf symbol.tgz ./xxx.app.dSYM to compress the dSYM file into a .tgz package.

2. Log on to the mPaaS console, select the target application, and from the left navigation pane, choose Mobile Analysis > App Performance Analytics > iOS Symbol Table Management.

3. Click Import App Symbol Table. In the Import Symbol Table dialog box, provide the necessary details and upload the symbol table file.

   • Version: The version number of the app.

   • Module Name: The name of the iOS app's binary file. This name is stored in the symbol file and is used to match the symbol file with the correct app binary.

     Enter the moduleName of the app's main module. For example, if the generated package is Produce.app, the moduleName is Produce.

   • UUID: A universally unique identifier (UUID) is a unique ID generated by the machine. A new UUID is generated each time you compile an iOS app. For a crash stack to be parsed correctly, the UUID of the imported symbol file must match the UUID in the crash log. This ensures both originated from the same compilation.

     Enter the UUID of the app's main module. If multiple UUIDs exist, such as for the armv7 and arm64 architectures, you can enter any one of them. The UUID string must not contain hyphens and must be in lowercase. For example: b7583434dc5e377bb4d8e7b69bf4c1fb.

   • Upload Symbol File: Two upload methods are supported.

     • URL Upload: Enter the URL of the compressed .tgz symbol file. If the file is not found at the specified URL, an error message is returned.

     • Local Upload: Upload the symbol file from your local machine.

4. To import the symbol table, click Import.

5. On the iOS Symbol File Management page, check the import status of the symbol file. If the status is Done, the import was successful. If the status is Failed, the import failed. If the import fails, follow the instructions in the error message to re-import the symbol file.

All imported symbol files are displayed on the management page. You can query for symbol files by app version.

Test symbolication

After importing a symbol file, you can test it to verify that it is valid.

Follow these steps to test symbolication:

1. In the list of iOS symbol files, find the file that you want to test. In the Actions column, click Test Symbolication.

2. In the Raw Log Text field, paste the content of the crash log that you want to symbolicate. Then, click Symbolicate Log. The symbolicated log text is displayed in the Symbolication Result field. If symbolication fails, a reason is provided, such as "UUID mismatch".