符号表工具使用说明
1 介绍
什么是符号表？ 符号表是内存地址与函数名、文件名、行号的映射表。符号表元素如下所示：
<起始地址> <结束地址> <函数> [<文件名:行号>]
为什么要配置符号表？
为了能快速并准确地定位用户APP发生Crash的代码位置，CrashSight使用符号表对APP发生Crash的程序堆栈进行解析和还原。 举一个例子：
| 还原前堆栈 | 还原后堆栈 |
|---|---|
| #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) |
而符号表工具，正是CrashSight提供给开发者提取符号表文件(.symbol)的工具。 如果项目工程中没有Native代码，但使用了代码混淆proguard，那么只需要上传Proguard生成的Mapping文件。该符号表也支持Mapping文件的上传，具体方法请参看下文。
1.1 环境要求
符号表工具的运行需要64位Java运行环境（Java SE Runtime Envrionment），JRE或者JDK版本需要>=1.6。Windows符号表必须在Windows平台上进行上传。
1.2 符号表提取要求
提取符号表需要符号表工具和带符号表的库文件（详见各平台符号表文件格式，及在unity、unreal引擎中的生成方法）。
1.3上传功能
CrashSight符号表工具支持上传功能。 使用上传功能时，需要指定以下信息： App ID App版本 上报地址
1.4 如何获取App ID
2 如何使用符号表工具
符号表工具支持Windows、Linux、Mac三个平台，提供了JAR包crashSightSymbolTool.jar
在项目左侧导航栏的“接入指南”中，可以下载符号表工具：
使用方法及参数如下：
jar -jar <JAR包> [-选项 <参数>]
建议直接在“接入指南”中复制自动生成的命令，以免遗漏参数。
| 选项 | 说明 |
|---|---|
| -i | 指定文件路径，可指定目录（Windows符号表只可以指定目录） |
| -p | 指定符号表平台类型：aos/ios/win/hm/linux/ps5/xbox，分别对应Android，iOS，Windows，Harmony，Linux，PS5 和 Xbox平台 |
| -o | 指定输出的符号表zip文件的路径，必须是zip文件（Windows符号表在系统临时文件目录，不支持指定） |
| -d | 调试模式开关（默认关闭） |
| -s | 指定配置文件（默认读取Jar目录下的setting.txt文件） |
| -u | 上传开关 |
| -url | 上传URL |
| -id | App ID |
| -key | App Key |
| -package | App包名 |
| -version | App版本 |
| -channel | App渠道（可选） |
| -mapping | Mapping文件（可选） |
| -uploadcos | 符号表文件直传腾讯云COS |
| -m | 生成模式，win（需要windows环境） 或者 generic（跨平台兼容） |
上报URL：默认新加坡
- 国内：https://api.crashsight.qq.com/openapi/file/upload/symbol
- 新加坡：https://crashsight.wetest.net/openapi/file/upload/symbol
3 常见问题
-
符号表工具的具体输入文件是什么？
安卓需要输入的文件是带调试信息的.so文件，iOS的输入是dsym文件，Windows的输入是pdb文件以及对应的exe/dll文件
-
符号表的 UUID 是什么?
- UUID是符号表的内置属性，是符号表的唯一标识，对于同一份文件，该值不会改变；
- 可以查看堆栈中每一行的末尾，存在一个十六进制字符串（通常为32个字符），这就是此行堆栈的模块的uuid；
- 通过UUID匹配对应的崩溃报告与符号表文件，从而将内存地址转换为源码位置，进行堆栈还原
-
如何查看符号表的 UUID ?
- 可以使用命令行工具查看符号表的 UUID，各平台命令如下：
- Android, Linux, Harmony平台
{SYMBOL_FILE_PATH}为so文件的路径
readelf -n {SYMBOL_FILE_PATH} | grep "Build ID" - iOS, MacOS平台
{SYMBOL_FILE_PATH}为dsym文件的路径
dwarfdump --uuid {SYMBOL_FILE_PATH} - Windows平台
{SYMBOL_FILE_PATH}为exe或dll文件的路径
dumpbin /headers {SYMBOL_FILE_PATH} | findstr "RSDS" - 通过命令行工具查看的uuid，如果其超过32位，CrashSight符号表工具会取后32位，如果不足，会补0；
- Android, Linux, Harmony平台
- 可以使用CrashSight符号表工具查看符号表的uuid，命令参数如下：
其中{platform}参数与您上传符号表时填写的相同。
java -jar crashSightSymbolTool.jar -i SYMBOL_FILE_PATH -p {platform} -uuid
- 可以使用命令行工具查看符号表的 UUID，各平台命令如下：
-
符号表的上传更新是增量更新还是覆盖更新？
相同UUID会覆盖，不同UUID会保留.
-
使用符号表上传工具，上传完成之后怎么自动确认（校验）上传是成功了的。
一般来说符号表工具成功执行完成，就是成功了。也可以在页面检查对应版本的符号表是否上传。
-
上传工具需要更新的话，是如何进行通知以及更新的？ 非必要更新，是会放到本文档中。如果存在必须要更新才能使用的情况，会通过接入时的沟通渠道进行联系。
4 iOS系统符号表获取
由于iOS崩溃会出现在系统库内，为了还原这部分崩溃，需要使用系统库的符号表。iOS系统符号表的获取方式如下：
-
准备对应系统版本/机型的设备一台。这里尽可能的使用崩溃相同机型，因为iOS同一版本系统，不同机型，有可能是不同的符号表。
-
安装Xcode的MAC一台。最好是安装最新Xcode的MAC，否则可能不支持最新的iOS系统。具体支持列表，可以查看MAC机器目录 /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport 下，是否有需要上传符号表的系统版本号。
-
USB连接MAC，打开Xcode的设备管理，等待同步完成，通常需要10到30分钟以上。
-
查看MAC机器 "~/Library/Developer/Xcode/iOS DeviceSupport" 目录下是有对应的版本号的文件夹。
-
将对应版本的系统文件夹压缩并发送给CrashSight管理人员。
5 各平台符号表文件格式，及在unity、unreal引擎中的生成方法
-
Android, Harmony--debug版的.so文件。
- Unity中在build settings里【Create symbols.zip】选择Debugging。
- Unreal中 项目设置-高级编译 勾选上【固定保存带符号libUnreal.so的副本】。
-
iOS--dSYM文件。
- Unity需要在导出的xcode项目中配置GENERATE_DEBUG_SYMBOLS(True)和 DEBUG_INFORMATION_FORMAT(dwarf-with-dsym)。
- Unreal在Project Settings-Platforms-iOS-Build中勾选Generate dSYM file for code debugging and profiling和Generate dSYM bundle for third party crash tools。
-
Windows--PDB文件，以及对应的EXE或DLL文件。
- Unity在build settings里勾选上【Copy PDB files】。
- Unreal 文件-打 包项目-打包设置 勾选【包括调试文件】。
-
MacOS--dSYM文件。
- Unity可以在构建产物的XXX_BackUpThisFolder_ButDontShipItWithYourGame目录中找到dSYM文件。
- Unreal在Project Settings-Project-Packaging-Project中勾选For Distribution和Include Debug Files in Shipping Builds，打包生成的xcarchive文件中会包含dSYM。
6 符号表调试信息
-
符号表调试信息是编译器生成的元数据，CrashSight依赖它将堆栈中的内存地址还原成可读的函数名、源文件路径及行号，从而精准定位崩溃代码位置。
-
如何检查是否有调试信息？
- Android平台的符号表调试信息主要指.so文件中的.debug_info段，可以通过以下方法进行检查
- 使用 'readelf -e {SYMBOL_FILE_PATH}' 命令查看.so中是否包含.debug_info段;
- 使用7-Zip解压软件打开.so文件，查看是否包含.debug_info段，如下图所示。
- iOS和MacOS平台请查看是否有dSYM文件，或者dSYM文件是否明显过小，如小于1MB；
- Windows平台请查看是否有PDB文件。
- Android平台的符号表调试信息主要指.so文件中的.debug_info段，可以通过以下方法进行检查
7 Windows 符号表工具常见问题
-
Windows平台的符号表文件是PDB文件，以及对应的EXE或DLL文件。CrashSight符号表 工具在处理制作符号表时，会根据pdb的名字、pdb的uuid，匹配对应的exe/dll进行处理制作。
- 如果修改了exe/dll的名字，符号表工具会根据pdb的名字、uuid，去匹配对应的exe/dll
- 如果修改了pdb的名字，会导致无法解析，因此需要确保未修改pdb文件的名字
-
CrashSight符号表工具参数补充说明
- -i 参数指定符号表文件路径
- 在windows平台需要指定pdb文件所在的目录，不能直接指定文件
- 该目录及其子目录里可以包含多个pdb文件，符号表工具会查找该目录下所有的pdb进行处理上传
- -i 参数指定符号表文件路径
-
CrashSight对于堆栈回溯的机制有以下三种
- context 指使用崩溃线程上下文中的寄存器状态来定位栈帧，结果是准确的；
- cfi 指使用Call Frame Information来推到栈帧，结果是准确的；
- scan 指使用Stack Scan扫描栈内存的方式，把任何指向代码段的值当作返回地址，结果是不准确的；
-
当页面提示“当前堆栈回溯基于栈扫描机制，回溯的堆栈可能与真实的堆栈有出入，请上传符号表以便得到精确的回溯堆栈。”时，可进行如下的问题排查：
- 请检查是否上传符号表，未上传符号表会导致堆栈回溯不精确；
- 如果已上传符号表，同时某个模块的堆栈中包含已还原的堆栈，那么原因可能是该模块在制作符号表时没有找到匹配的exe/dll，此时函数的调用关系可能不准确；
- 如果单独出现模块中某一行的堆栈无法还原，此时整体的调用关系通常没有问题，可能是栈破坏等原因导致的。