Symbol Table Tool Usage Introduction

---

1 Introduction

What is a symbol table? A symbol table is a mapping table that contains memory addresses, function names, file names, and line numbers. Symbol table elements are as follows:

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

What is a symbol table for?

To locate the code where a crash happened in the user's app quickly and accurately, CrashSight uses symbol tables to analyze and retrace the crash stack. For example:

stack before retrace	stack after retrace
#00 pc 0021cdf4 /lib/libgame.so	#00 pc 0021cdf4 _ZNK14CAnimationNode13getCurEquipldEv(CAnimationNode.h:51)
#01 pc 002abe36 /lib/libgame.so	#01 pc 002abe36 _ZNSt6vectorl15NDKCallbackNodeSalS0_EE5beginEv(NDKHelper.cpp:312)
#02 pc 003aebee /lib/libgame.so	#02 pc 003aebee _ZNK6b2Vec26LengthEv(b2Math.h:121)

The symbol table tool is a tool CrashSight offers developers to extract symbol table files (.symbol). If the project doesn't contain Native code, but has used ProGuard to obfuscate code, just upload the Mapping file generated by ProGuard. The symbol table also supports uploading Mapping files. The way to do it is explained below.

1.1 Environment Requirements

The symbol table tool requires 64 bits Java SE Runtime Environment under 64bit. JRE and JDK version 1.6 and above. The Windows symbol table must be uploaded on a Windows platform.

1.2 Symbol Table Extraction Requirements

To extract symbol tables, the symbol table tool and libraries with symbol table are required (see Symbol table file format for each platform, and how to generate it in unity and unreal engines for more details).

1.3 Uploading Symbol Table

The CrashSight symbol table tool supports symbol table uploading. When using the uploading feature, the following info must be specified: App ID, App version, URL for reporting.

1.4 How to Obtain App ID

2 How to use Symbol Table Tool

The symbol table tool supports three platforms: Windows, Linux, and Mac. The corresponding symbol table tool can be downloaded from the "Tutorial" in the left sidebar of the project:

Download Symbol Table Tool open in new window (Download is unavailable due to an ongoing internal review. To download it, please contact crashsight@tencent.com)

2.1 Tool Usage and Options

    jar -jar <JAR file> [-option <parameter>]

It is recommended to copy the auto-generated commands directly in the "Tutorial" to avoid missing parameters.

Option	Note
-i	Assign a file path. It can be a directory (For Windows symbol tables, you can only specify directories)
-p	Platform type: aos/ios/win/hm/linux/ps5, corresponding to Android, iOS, Windows, Harmony,Linux and PS5 platform respectively.
-o	Assign a path for outputting symbol table zip files. It must be a zip file (Windows symbol tables are output to a temporary directory, and cannot be assigned a directory)
-d	Debugging mode switch (off by default)
-s	Assign a configuration file (the setting.txt file under the Jar directory is read by default)
-u	Upload switch
-url	Upload URL
-id	App ID
-key	App Key
-package	App package name
-version	App version
-channel	App channel (optional)
-mapping	Mapping file (optional)
-symbol	Generate symbol file (optional)
-uploadcos	Symbol table file directly uploaded to Tencent Cloud COS (optional)
-m	Generation mode. Fill in "win" or "ori" ("win" by default. Only supports windows symbol tables.)

Note that the symbol table tool of this version doesn't generate .sym files by default. To get .sym files, specify the "-symbol" parameter before running the symbol table tool.

URL for reporting:

• Local(China): https://api.crashsight.qq.com/openapi/file/upload/symbol
• International: https://crashsight.wetest.net/openapi/file/upload/symbol

3 FAQs

1. What is the input file of symbol table tool? For Android, input .so files with debugging info. For iOS, input dsym files. For Windows, input PDB files, and corresponding EXE or DLL files.

2. What is a symbol table's UUID?

   • UUID is a built-in attribute of the symbol table, serving as a unique identifier for the symbol table. For the same file, this value will not change.
   • You can check the end of each line in the stack trace, where there will be a hexadecimal string (usually 32 characters long). This represents the UUID of the module in that stack trace line.
   • By matching the UUID, you can link the crash report to the symbol table file, enabling the conversion of memory addresses to source code locations and performing stack trace resolution.

3. How to view the UUID of the symbol table?

   • You can use the command line tool to view the UUID of the symbol table. The commands for each platform are as follows:
     • Android, Linux, Harmony platform

       readelf -n {SYMBOL_FILE_PATH} | grep "Build ID"
       {SYMBOL_FILE_PATH} is the path of the so file
     • iOS, MacOS platform

       dwarfdump --uuid {SYMBOL_FILE_PATH}
       {SYMBOL_FILE_PATH} is the path to the dsym file
     • Windows platform

       dumpbin /headers {SYMBOL_FILE_PATH} | findstr "RSDS"
       {SYMBOL_FILE_PATH} is the path of the exe or dll file
     • If the uuid viewed through the command line tool exceeds 32 bits, the CrashSight symbol table tool will take the last 32 bits. If it is less than 32 bits, it will be filled with 0;
   • You can use the CrashSight symbol table tool to check the UUID of the symbol table. The command parameters are as follows:

       java -jar crashSightSymbolTool.jar -i SYMBOL_FILE_PATH -p {platform} -uuid
     Here, the {platform} parameter should be the same as the one you filled in when uploading the symbol table.

4. Does uploading a symbol table overwrite the previous table? The previous table will be overwritten if the two tables share the same UUID, but retained if the UUIDs are different.

5. After using the symbol table uploading tool, how can I know whether the upload is successful? Usually, the upload is successful as long as the symbol table tool is executed. You can also check on the page whether the symbol table of the corresponding version has been uploaded.

6. How would I know it when the uploading tool needs an update? And how to update it? If the update is optional, it will be included in this document. If the update is a must, users will be notified via the communication channel provided upon Integration.

4 Getting iOS system symbol table

Since iOS crashes occur within the system library, in order to symbolicate this part of the crash, you need to use the symbol table of the system library. iOS system symbol table can be obtained as follows:

1. Prepare a device corresponding to the system version / model. Here as much as possible to use crash the same model, because iOS the same version of the system, different models, may be different symbol table.

2. Prepare a Mac with Xcode installed. It is best to have a MAC with the latest Xcode installed, otherwise the latest iOS may not be supported. For a specific support list, check the MAC machine directory /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport for the version number of the system for which you need to upload a symbol table.

3. Connect to the MAC with USB, open Xcode's Device Manager, and wait for the synchronization to complete, which usually takes 10 to 30 minutes or more.

4. The "~/Library/Developer/Xcode/iOS DeviceSupport" directory is the folder with the corresponding version number.

5. Zip the corresponding version of the system folder and send it to the CrashSight administrator.

5 Symbol table file format for each platform, and the generating method in unity and unreal engine

1.Android - debug version of the .so file. Unity: in build settings, [Create symbols.zip] select Debugging. Unreal: in project settings - advanced compilation, check [Fixed save a copy of libUnreal.so with symbols]. 2. iOS - dSYM file. Unity: configure GENERATE_DEBUG_SYMBOLS(True) and DEBUG_INFORMATION_FORMAT(dwarf-with-dsym) in the exported xcode project. Unreal: Check Generate dSYM file for code debugging and profiling and Generate dSYM bundle for third party crash tools in Project Settings-Platforms-iOS-Build. 3. Windows - PDB files, and corresponding EXE or DLL files. Unity: check [Copy PDB files] in the build settings. Unreal: File-Package project-Package settings, Check [Include debug files].
4. macOS - dSYM file.
Unity dSYM files can be found in the XXX_BackUpThisFolder_ButDontShipItWithYourGame directory of the build product.
Unreal checks [For Distribution] and [Include Debug Files in Shipping Builds] in Project Settings-Project-Packaging-Project, and the xcarchive file generated by packaging will include dSYM.

6 Common questions for Windows symbol table tools

1. The symbol table files on the Windows platform are PDB files, along with their corresponding EXE or DLL files. When CrashSight Symbol Table Tool processes and generates symbol tables, it matches the corresponding EXE/DLL files based on the PDB's name and UUID for processing and generation.

   • If the name of the EXE/DLL is modified, the symbol table tool will match the corresponding EXE/DLL according to the PDB's name and UUID.
   • If the name of the PDB is modified, it will lead to failure in parsing. Therefore, it is necessary to ensure that the name of the PDB file remains unmodified.

2. Supplementary explanation of CrashSight Symbol Table Tool parameters

• The -i parameter specifies the path of the symbol table file.
  • On the Windows platform, it is required to specify the directory where the PDB file is located, and directly specifying the file is not allowed.
  • The directory and its subdirectories can contain multiple PDB files, and the symbol table tool will search for all PDBs in this directory for processing and uploading.

3. CrashSight has the following three mechanisms for stack backtracking:

   • Context: It uses the register state in the crash thread context to locate stack frames, and the result is accurate.
   • CFI: It uses Call Frame Information to deduce stack frames, and the result is accurate.
   • Scan: It uses the Stack Scan method to scan stack memory, treating any value pointing to the code segment as a return address, and the result is inaccurate.

   Therefore, when the page prompts "Current stack trace was unwound based on stack scanning mechanism, in this case, the stack trace may be inaccurate. Please upload symbol files to obtain accurate stack traces.", the following troubleshooting steps can be taken:

   • Check whether the symbol table has been uploaded. Failure to upload the symbol table will result in inaccurate stack backtracking.
   • If the symbol table has been uploaded and the stack of a certain module contains a restored stack, the reason may be that the matching EXE/DLL was not found when generating the symbol table for that module, in which case the function call relationship may be inaccurate.
   • If the stack of a certain line in the module cannot be restored individually, the overall call relationship is usually correct, which may be caused by stack corruption or other reasons.