符号表管理

Android符号化

Java符号表工具使用及上传

基调听云SDK 提供了两种方式上传mapping文件：

通过报表上传
通过tingyun.properties文件自动上传

通过报表上传Mapping文件

登录基调听云报表，选中异常分析模块，点击崩溃卡片，在「崩溃列表」右上角单击符号表管理
找到对应版本，并上传本地 Mapping文件即可

符号表上传默认按照应用版本的数据接收时间进行排序，支持根据应用版本进行检索，一个版本支持上传多个文件。

通过tingyun.properties文件自动上传

通过tingyun.properties文件自动上传Mapping文件，SDK需要 2.15.7 及以上版本（暂不支持AGP8+；AGP7及以下版本依赖于packageRelease task，暂不支持productFlavors）。

说明：若您的项目不存在「tingyun.properties」文件，需在项目app目录及根目录下新建该文件。

在tingyun.properties 文件中配置：

uploadAddress=*基调听云登录报表的主域名拼接/o11y-api/ro/rum-app/symbol/appkey/（例如：http://10.128.9.92/o11y-api/ro/rum-app/symbol/appkey/）*
appKey=*MobileKey*
mapping_file_auto_upload=true

开启混淆器。

mapping_file_auto_upload控制开关只有在启用混淆器的时候才会生效，开启控制开关后，基调听云SDK会将本地目录下的mapping文件自动上传到基调听云服务器。若未开启混淆器则该配置项不生效。

Native符号表工具使用及上传

为了能快速并准确地定位应用发生 Native Crash 的代码位置，基调听云使用符号表文件对应用崩溃堆栈进行解析和还原。

原堆栈：

还原后堆栈：

符号表提取要求

符号表工具 nbs.newlens.so.parser.jar，是Mobile提供给开发者提取符号表文件的工具。提取符号表需要符号表工具和Debug SO文件（具有调试信息的SO文件）。SDK 默认会在编译 release 版本时自动在项目根目录 tingyun 文件夹中生成符号表文件。您也可以使用符号表工具手动生成符号表文件。

工具选项

选项	说明
-i	指定so文件夹路径

生成符号表文件

使用符号表工具的JAR包生成符号表文件的命令如下：

java -jar nbs.newlens.so.parser.jar -i E:\JNIDemo\jniLibs //指定目录

生成的符号表文件 NewlensSymbol.zip 位于符号表工具目录下。

注意：基调听云上传符号表文件仅支持zip 格式，-i 参数请指定生成SO文件夹的路径。该路径一般默认为app\build\intermediates\cmake\debug\obj，也可以通过CMakeLists.txt文件配置输出到其他目录。

上传符号表

Native符号表文件目前只支持报表上传。

登录基调听云报表，选中异常分析模块，点击崩溃卡片，在「崩溃列表」右上角单击符号表管理。
选择Native symbol页签，单击选择文件上传NewlensSymbol.zip即可。

iOS符号化

查找符号表

找到工程的.xcarchive文件，然后右选择“Show in Finder”进入文件目录。
右击“.xcarchive”文件，选择“显示包内容”。
选择对应的“.app.dSYM”文件，如："HelloWorld.app.dSYM"，右击"显示包内容"。

注意：下图标注部分为符号表文件，上传时请上传该文件而不是xxx.app.dSYM这个目录。

通过脚本上传符号表文件

通过Xcode + sh脚本上传符号表文件，操作步骤如下。

将解压后SDK包中tingyun.sh的内容粘贴到上图中shell下方的位置。
配置好上图中对应的APP_KEY和UPLOAD_URL。
在Input Files中添加：
- 若调用以下接口，需在脚本中将VERSION的值改成与接口设置的versionName一致。
```
(void)setVersionName:(NSString *)versionName;
```
- 若调用以下接口且useBuildVersion为YES时，需在脚本中将VERSION的值改成与CFBundleVersion版本号一致（xcode->General->Identity->Build）。
```
 +(void)startWithAppID:(NSString*)appId location:(BOOL)locationAllowed rateOfLaunch:(double) rate channelId:(NSString *)channelId useBuildVersion:(BOOL)useBuildVersion;
```

通过报表上传符号表文件

登录基调听云报表，选中异常分析模块，点击崩溃卡片，在下方的「崩溃列表」右上角单击符号表管理。
在弹出窗口中在对应的应用版本号右侧单击添加按钮，再点击底部的选择文件按钮，手动上传符号表。如下图所示：

通过命令行上传符号表

打开终端，进入HelloWorld符号表的目录，即HelloWorld.app.dSYM/Contents/Resources/DWARF，输入如下命令：

curl -k -F file=@HelloWord -F buildVersion=${CFBundleVersion} -F shortVersion=${CFBundleShortVersionString} ${UPLOAD_URL}/o11y-api/ro/rum-app/symbol/appkey/${APP_KEY}

命令行参数配置：

HelloWorld : 符号表名称
CFBundleShortVersionString : 主版本号（xcode->General->Identity->Version)
CFBundleVersion : build版本号（xcode->General->Identity->Build)
UPLOAD_URL : 基调听云登录报表的主域名（例如：https://wukong2.tingyun.com）
APP_KEY: Mobile授权Key

上传符号表：配置完成后即可通过命令行上传符号表到基调听云服务器，出现 SUCCESS 说明上传成功。

{"status":"SUCCESS","message":"","data":[{"id":12,"mobileAppId":7023,"mobileAppVersionId":0,"uploadType":1,"shortVersion":"295","checkMd":"720f0223900fad37ada3f8bf92dafe57","dsymbolFileName":"Doomfirst","dsymbolFilePath":"7023/7023_295_1_55F9253D-9F5B-3C23-BD8F-D783BE3510D1.dsymb","imgName":"Doomfirst","mobileAppBuildId":"55F9253D-9F5B-3C23-BD8F-D783BE3510D1","status":1,"muser":9,"ctime":1762398443447,"mtime":1762398443453,"buildVersion":"7"}]}

执行命令及结果如图所示：

HarmonyOS NEXT符号化

TINGYUN CLI符号表文件上传工具

Tingyun CLI是用来上传HarmonyOS NEXT符号表文件的CLI工具，支持Windows, Mac, Linux操作系统。

安装

方式1: npm

本地安装

进入工程目录
```
npm install @tingyun-common/cli
```
验证安装成功
```
npx tingyun-cli -v
```

如果终端中打印tingyun-cli版本证明安装成功

全局安装

安装
```
npm install -g @tingyun-common/cli --unsafe-perm
```
需要确保有权限访问全局的node_modules目录, 如果在Linux, Mac环境遇到权限问题, 建议使用root安装
```
sudo npm install -g @tingyun-common/cli --unsafe-perm
```
验证安装成功
```
tingyun-cli -v
```
如果终端中打印tingyun-cli版本证明安装成功

配置可执行文件下载地址(可选)

CLI安装过程中会从服务器下载可执行文件, 可以通过--tingyuncli_cdnurl参数设置下载地址的根路径, 不配置时默认使用听云文件下载服务器地址

示例:

npm install @tingyun-common/cli --tingyuncli_cdnurl=http://example.com/path

方式2: 手动下载可执行文件

可以在听云文件下载服务器查看Tingyun CLI已经发布的版本，并根据操作系统和架构下载需要的可执行文件，请选择Tingyun CLI最新版本以支持上传HarmonyOS NEXT符号表。下载之后可以将可执行文件重命名为tingyun-cli.exe或tingyun-cli来使用。注意可执行文件是CLI程序，需要在终端中使用。

使用

HarmonyOS NEXT

1. 上传符号表文件

命令:

指定HarmonyOS NEXT工程根目录的场景

tingyun-cli upload <工程根目录> --beacon=<beacon> --app-token=<应用token> --token=<token> --app-version=<应用版本> --build-id=<buildId> --platform=HarmonyOSNEXT

指定普通目录的场景

tingyun-cli upload <普通目录> --beacon=<beacon> --app-token=<应用token> --token=<token> --app-version=<应用版本> --build-id=<buildId> --platform=HarmonyOSNEXT --module=<模块名> --package=<包名>

说明:

CLI自动判断指定的目录是否是一个HarmonyOS NEXT工程的根目录。如果是则以工程根目录模式运行，否则以普通模式运行
工程根目录模式下, CLI会读取app.json5文件, 尝试从app.versionName读取应用版本, 尝试从app.appEnvironments中读取tingyun_build_id环境变量，读取不到需要手动指定, 而且会自动收集当前工程下的各个模块的文件。普通模式下, 必须手动指定应用版本、buildId、module, package
appToken, token, 应用版本支持通过配置文件设置或直接通过命令传递
更多配置参数参考下方命令列表

2. 设置项目的应用版本

为了准确解析, 需要确保项目本身的应用版本，buildId与CLI传递的保持一致，其中应用版本在app.json5中app.versionName设置, buildId可以通过下面2种方式设置

方式1: 在app.appEnvironments中设置

{
  "app": {
    "appEnvironments": [
      {
        "name": "tingyun_build_id",
        "value": "<buildId>"
      }
    ]
  }
}

方式2: SDK启动时设置

tingyun.init({
  // ...
  buildId: '<buildId>',
});

命令列表

init

初始化配置文件

tingyun-cli init

Flags:

-y: 跳过问卷，直接生成配置文件

upload

上传文件(目前仅支持HarmonyOS NEXT)

tingyun-cli upload <dir> [flags]

注: 当前仅HarmonyOS NEXT符号表上传支持此命令

Flags:

--beacon <string>: 上传beacon地址，基调听云登录报表的主域名（例如：https://wukong2.tingyun.com）
--app-token <string>: 应用token(appKey)，在基调听云报表用户体验->APP->应用->应用设置->基础设置->App Key获取
--token <string>: 账号token，在基调听云报表账户管理->API->Access Token获取
--app-version <string>: 应用版本
--build-id <string>: 构建ID
--platform <string>: 当前仅支持HarmonyOSNEXT
--sourcemap: 仅上传sourcemap文件
--namecache: 仅上传namecache文件
--symbol: 仅上传so文件符号表文件
--product <string>: 指定需要上传的product名称, 默认为default
--target <string>: 指定需要上传的target名称, 默认为default
--module: 指定需要上传的模块的模块名(module.json5中module.name字段), 多个使用,分割
--package <string>: 指定需要上传的模块的包名(oh-package.json5中name字段), 多个使用,分割
--output <string>: 打包文件生成目录, 默认为当前目录下的TingyunSymbol目录
--remove-output: 上传后删除打包文件, 默认不删除
--no-upload: 只打包上传文件，不上报
--upload-retries <int>: 发送失败后重试次数。默认为0次，失败后不重试

其他

查看版本

tingyun-cli -v

指定配置文件路径

Flags:

--config <string>: 指定配置文件位置, 全局flags, 对所有命令子命令都生效。

示例:

tingyun-cli upload <工程根目录> --beacon=<beacon> --app-token=<应用token> --token=<token> --app-version=<应用版本> --build-id=<buildId> --platform=HarmonyOSNEXT --config /my/config/dir/.tingyunclirc.toml

hvigor插件

此插件用于在HarmonyOS NEXT项目编译时自动收集上报符号表相关文件。

使用示例

安装

引入hvigor插件依赖

在项目根目录hvigor/hvigor-config.json5中加入插件依赖

{
  // ...
  "dependencies": {
    "@tingyun-common/hvigor-plugin-build": "<版本号>"
  }
}

在工程级的hvigorfile.ts中注册插件

import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { tingyunBuildPlugin } from '@tingyun-common/hvigor-plugin-build'

export default {
  system: appTasks,
  plugins:[
    tingyunBuildPlugin({
      beacon: "<beacon>",
      token: "<token>",
      appToken: "<应用token>"
    }),
    // ... 其他插件
  ]
}

sync工程

hvigorw --sync -p product=default -p buildMode=release --analyze=normal --parallel --incremental --no-daemon

注：

如果tingyun-cli自定义了下载地址，需要确保相关下载地址的环境变量存在再执行

build项目，观察日志输出，可以看到文件打包并上报

卸载

在工程级的hvigorfile.ts中取消注册插件
在项目根目录hvigor/hvigor-config.json5中注释或移除插件依赖
sync工程

插件配置项

type TingyunBuildPluginOptions = {
  // 上报的目录，如果用户没有设置, 插件内部会自动传入项目根目录
  include?: string[];
  // 上传地址, 直接配置beacon或在configFile指定的配置文件中配置
  beacon?: string;
  // auth token, 直接配置beacon或在configFile指定的配置文件中配置
  token?: string;
  // 应用 token, 直接配置beacon或在configFile指定的配置文件中配置
  appToken?: string;
  // 配置文件路径, 当beacon, token, appToken未指定时会尝试从配置文件中读取
  configFile?: string;
  // 需要执行插件的buildMode, 默认为release
  buildMode?: string;
  // 应用版本
  appVersion?: string;
  // 构建ID
  buildId?: string;
  // 指定需要上传的product名称, 默认会在构建时自动获取
  product?: string;
  // 指定需要上传的target名称
  target?: string;
  // 需要上报的模块名, 默认上报工程下的全部模块
  modules?: string[];
  // 需要上报的包名(oh-package.json5中的name), 默认上报工程下的全部包
  packages?: string[];
  // 仅收集sourceMap上报开关, 默认false
  sourceMap?: boolean;
  // 仅收集nameCache上报开关, 默认false
  nameCache?: boolean;
  // 仅收集symbol上报开关, 默认false
  symbol?: boolean;
  // 输出目录
  output?: string;
  // 上传完成后移除打包的zip文件, 默认false
  removeOutput?: boolean;
  // 只打包不上报, 默认false
  noUpload?: boolean;
  // demangle每批参数长度, 默认4096
  demangleBatchSize?: number;
  // 重试次数, 默认0次
  uploadRetries?: number;
};

Android符号化​

Java符号表工具使用及上传​

通过报表上传Mapping文件​

通过tingyun.properties文件自动上传​

Native符号表工具使用及上传​

符号表提取要求​

生成符号表文件​

上传符号表​

iOS符号化​

查找符号表​

通过脚本上传符号表文件​

通过报表上传符号表文件​

通过命令行上传符号表​

HarmonyOS NEXT符号化​

TINGYUN CLI符号表文件上传工具​

安装​

方式1: npm​

本地安装​

全局安装​

配置可执行文件下载地址(可选)​

方式2: 手动下载可执行文件​

使用​

HarmonyOS NEXT​

1. 上传符号表文件​

2. 设置项目的应用版本​

命令列表​

init​

upload​

其他​

查看版本​

指定配置文件路径​

hvigor插件​

使用示例​

安装​

卸载​

插件配置项​

Android符号化

Java符号表工具使用及上传

通过报表上传Mapping文件

通过tingyun.properties文件自动上传

Native符号表工具使用及上传

符号表提取要求

生成符号表文件

上传符号表

iOS符号化

查找符号表

通过脚本上传符号表文件

通过报表上传符号表文件

通过命令行上传符号表

HarmonyOS NEXT符号化

TINGYUN CLI符号表文件上传工具

安装

方式1: npm

本地安装

全局安装

配置可执行文件下载地址(可选)

方式2: 手动下载可执行文件

使用

HarmonyOS NEXT

1. 上传符号表文件

2. 设置项目的应用版本

命令列表

init

upload

其他

查看版本

指定配置文件路径

hvigor插件

使用示例

安装

卸载

插件配置项