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:

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 Java SE Runtime Environment under 64bit. JRE and JDK version 1.6 and above.

1.2 Symbol Table Extraction Requirements

To extract symbol tables, the symbol table tool and Debug(unstripped) SO file are required (for SO files that contain debug info, please refer to "3. Debug SO File", the third section below).

1.3 Uploading Symbol Table

The CrashSight Android symbol table tool version 2.5.0 and above has an uploading feature added, and supports Mapping file uploading. When using the uploading feature, the following info must be specified: App ID, App Key, App version, App package name, address for reporting

2 How to Extract Symbol Tables

The symbol table tool supports three platforms: Windows, Linux, and Mac. It provides these JAR files: crashSightSymbolAndroid.jar, crashSightSymboliOS.jar

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>]

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:

• Domestic: https://api.crashsight.qq.com/openapi/file/upload/symbol
• Singapore: https://crashsight.wetest.net/openapi/file/upload/symbol

2.2 Usage example

Here is a usage example. Change it according to your project’s needs.

2.2.1 Symbol Table Generation and Uploading for Debug SO

Example:

Operating system: Windows
Directory of Debug SO: E:\Projects\Demo\obj
App ID: 9000012345
App Key: abcdefghijk
App Package Name: com.batman.demo
App Version: 2.3.1

Use the symbol table tool’s JAR file to generate the symbol table file and upload automatically. The command is as follows:

    java -jar crashSightSymbolAndroid.jar -i E:\Projects\Demo\obj -u -id 900012345 -key abcdefghijk -package com.batman.demo -version 2.3.1 -url https://crashsight.wetest.net/openapi/file/upload/symbol

Note: In the example above, the overseas reporting url address is used. To upload to a domestic environment, please replace it with: https://api.crashsight.qq.com/openapi/file/upload/symbol

2.2.2 Upload Mapping Files

Example:

Operating system: Windows
Android project directory: E:\Projects\Demo
App ID: 9000012345
App Key: abcdefghijk
App Package Name:：com.batman.demo
App Version: 2.3.1

Use the symbol table tool to upload Mapping files. The command is as follows:

java -jar crashSightSymbolAndroid.jar -mapping E:\Projects\Demo\Mapping\mapping.txt -u -id 900012345 -key abcdefghijk -package com.batman.demo -version 2.3.1 -channel tencent -url https://crashsight.wetest.net/openapi/file/upload/symbol

Note: In the example above, the overseas reporting url address is used. To upload to a domestic environment, please replace it with: https://api.crashsight.qq.com/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

2. What is a symbol table’s UUID?
   UUID is a built-in property of so/dsym. For one single file, its value remains the same.

3. 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.

4. 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.

5. 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.