Symbol Table Management

Android Symbolization

Java Symbol Table Tool Usage and Upload

Tingyun SDK provides two methods to upload mapping files:

• Upload through the dashboard
• Automatic upload through the tingyun.properties file

Upload Mapping Files Through the Dashboard

1. Log in to the Tingyun dashboard, select the Exception Analysis module, click the Crash card, and click Symbol Table Management in the upper right corner of the "Crash List"

   

2. Find the corresponding version and upload the local Mapping file

Symbol table uploads are sorted by default according to the data reception time of the application version, support searching by application version, and one version supports uploading multiple files.

Automatic Upload Through tingyun.properties File

To automatically upload Mapping files through the tingyun.properties file, the SDK needs to be version 2.15.7 or above​(Temporarily does not support AGP8+; AGP7 and below versions rely on the packageRelease task, and currently do not support productFlavors).

Note: If the "tingyun.properties" file does not exist in your project, you need to create this file in both the project app directory and the root directory.

1. Configure in the tingyun.properties file:

uploadAddress=Tingyun dashboard main domain name concatenation with "/o11y-api/ro/rum-app/symbol/appkey/"(e.g.: http://10.128.9.92/o11y-api/ro/rum-app/symbol/appkey/ ) 
appKey=MobileKey
mapping_file_auto_upload=true

2. Enable the obfuscator.

The mapping_file_auto_upload control switch only takes effect when the obfuscator is enabled. After enabling the control switch, the Tingyun SDK will automatically upload the mapping file in the local directory to the Tingyun server. If the obfuscator is not enabled, this configuration item will not take effect.

Native Symbol Table Tool Usage and Upload

In order to quickly and accurately locate the code position where a Native Crash occurs in the application, Tingyun uses symbol table files to parse and restore the application crash stack.

Original Stack:

Restored Stack:

Symbol Table Extraction Requirements

The symbol table tool nbs.newlens.so.parser.jar is a tool provided by Mobile for developers to extract symbol table files. Extracting symbol tables requires the symbol table tool and Debug SO files (SO files with debugging information). By default, the SDK will automatically generate symbol table files in the tingyun folder in the project root directory when compiling the release version. You can also use the symbol table tool to manually generate symbol table files.

Tool Options

Option	Description
-i	Specify the SO folder path

Generate Symbol Table Files

The command to generate symbol table files using the JAR package of the symbol table tool is as follows: java -jar nbs.newlens.so.parser.jar -i E:\JNIDemo\jniLibs //specify directory

The generated symbol table file NewlensSymbol.zip is located in the symbol table tool directory.

Note: Tingyun only supports zip format for uploading symbol table files. Please specify the path of the generated SO folder for the -i parameter. This path is generally defaulted to app\build\intermediates\cmake\debug\obj, or can be configured to output to other directories through the CMakeLists.txt file.

Upload Symbol Table

Native symbol table files currently only support dashboard upload.

1. Log in to the Tingyun dashboard, select the Exception Analysis module, click the Crash card, and click Symbol Table Management in the upper right corner of the "Crash List".

   

2. Select the Native symbol tab, click Select File to upload NewlensSymbol.zip.

   

iOS Symbolization

Find Symbol Table

1. Find the .xcarchive file of the project, then right-click "Show in Finder" to enter the file directory.

   

2. Right-click the ".xcarchive" file and select "Show Package Contents".

   

3. Select the corresponding ".app.dSYM" file, such as: "HelloWorld.app.dSYM", right-click "Show Package Contents".

   Note: The marked part in the figure below is the symbol table file. When uploading, please upload this file instead of the xxx.app.dSYM directory.

   

Upload Symbol Table Files Through Scripts

Upload symbol table files through Xcode + sh script, the operation steps are as follows.

1. Paste the contents of tingyun.sh from the unzipped SDK package to the position below shell in the figure above.

2. Configure the corresponding APP_KEY and UPLOAD_URL in the figure above.

3. Add in Input Files:

   • If calling the following interface, you need to change the VALUE of VERSION in the script to be consistent with the versionName set by the interface.

     (void)setVersionName:(NSString *)versionName;

   • If calling the following interface and useBuildVersion is YES, you need to change the VALUE of VERSION in the script to be consistent with the CFBundleVersion version number (xcode->General->Identity->Build).

      +(void)startWithAppID:(NSString*)appId location:(BOOL)locationAllowed rateOfLaunch:(double) rate channelId:(NSString *)channelId useBuildVersion:(BOOL)useBuildVersion;

Upload Symbol Table Files Through the Dashboard

1. Log in to the Tingyun dashboard, select the Exception Analysis module, click the Crash card, and click Symbol Table Management in the upper right corner of the "Crash List" below.

2. In the pop-up window, click the Add button to the right of the corresponding application version number, then click the Select File button at the bottom to manually upload the symbol table. As shown in the figure below:

   

Upload Symbol Table Through Command Line

• Open the terminal, enter the directory of the HelloWorld symbol table, i.e., HelloWorld.app.dSYM/Contents/Resources/DWARF, and enter the following command:

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

• Command Line Argument Configuration:

HelloWorld : Symbol table name

CFBundleShortVersionString : Major version number (xcode->General->Identity->Version)

CFBundleVersion : Build version number (xcode->General->Identity->Build)

UPLOAD_URL : Main domain name of the Tingyun login report (e.g., https://wukong2.tingyun.com)

APP_KEY : Mobile authorization key

• Upload Symbol Table: After configuration, you can upload the symbol table to the Tingyun server via command line. A SUCCESS message indicates a successful upload.

{"status":"SUCCESS","message":"","data":[{"id":12,"mobileAppId":7023,"mobileAppVersionId":0,"uploadType":1,"shor tVersion":"295","checkMd":"720f0223900fad37ada3f8bf92dafe57","dsymbolFileName":"Doomfirst","dsymbolFilePath":"70 23/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"}]}

• The executed command and results are shown in the figure:

HarmonyOS NEXT Symbolization

TINGYUN CLI Symbol Table File Upload Tool

Tingyun CLI is a CLI tool used to upload HarmonyOS NEXT symbol table files, supporting Windows, Mac, and Linux operating systems.

Installation

Method 1: npm

Local installation

1. Enter the project directory

npm install @tingyun-common/cli

2. Verify that the installation is successful

npx tingyun-cli -v

If the tingyun-cli version is printed in the terminal, it proves that the installation is successful

Global installation

1. Installation

npm install -g @tingyun-common/cli --unsafe-perm

Make sure you have permission to access the global node_modules directory. If you encounter permission issues in Linux or Mac environments, it is recommended to use root installation

sudo npm install -g @tingyun-common/cli --unsafe-perm

2. Verify that the installation is successful

tingyun-cli -v

If the tingyun-cli version is printed in the terminal, it proves that the installation is successful

Configure the executable file download address (optional)

During the CLI installation process, the executable file will be downloaded from the server. The root path of the download address can be set by the --tingyuncli_cdnurl parameter. If not configured, the default address of the Tingyun file download server is used

Example:

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

Method 2: Manually download the executable file

You can view the released versions of Tingyun CLI on the Tingyun File Download Server and download the required executable file according to the operating system and architecture. Please select the latest version of Tingyun CLI to support uploading the HarmonyOS NEXT symbol table. After downloading, you can rename the executable file to tingyun-cli.exe or tingyun-cli for use. Note that the executable file is a CLI program and needs to be used in a terminal.

Use

HarmonyOS NEXT

1. Upload symbol table file

Command:

1. Specify the HarmonyOS NEXT project root directory scenario

tingyun-cli upload <project root directory> --beacon=<beacon> --app-token=<app token> --token=<token> --app-version=<app version> --build-id=<buildId> --platform=HarmonyOSNEXT

2. Specify the common directory scenario

tingyun-cli upload <common directory> --beacon=<beacon> --app-token=<app token> --token=<token> --app-version=<app version> --build-id=<buildId> --platform=HarmonyOSNEXT --module=<module name> --package=<package name>

Description:

1. The CLI automatically determines whether the specified directory is the root directory of a HarmonyOS NEXT project. If it is, it runs in project root directory mode, otherwise it runs in normal mode
2. In project root directory mode, the CLI will read the app.json5 file, try to read the application version from app.versionName, and try to read the tingyun_build_id environment variable from app.appEnvironments. If it cannot be read, it needs to be manually specified, and the files of each module under the current project will be automatically collected. In normal mode, you must manually specify the application version, buildId, module, and package.
3. appToken, token, and application version can be set through configuration files or passed directly through commands.
4. For more configuration parameters, refer to the command list below.

2. Set the application version of the project.

For accurate parsing, you need to ensure that the application version and buildId of the project itself are consistent with those passed by the CLI. The application version is set in app.versionName in app.json5. The buildId can be set in the following two ways. Method 1: Set in app.appEnvironments

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

Method 2: Set when SDK starts

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

Command list

init

Initialize the configuration file

tingyun-cli init

Flags:

• -y: Skip the questionnaire and generate the configuration file directly

upload

Upload files (currently only supports HarmonyOSNEXT)

tingyun-cli upload <dir> [flags]

Note: Currently only the HarmonyOS NEXT symbol table upload supports this command

Flags:

• --beacon <string>: Upload beacon address, the main domain name of the Tingyun Report (for example: https://wukong1.tingyun.com)

• --app-token <string>: Application token (appKey), obtained in Tingyun Report User experience->Mobile App->Application List->Application Settings->Basic Settings->App Key

• --token <string>: account token, obtain it in Tingyun ReportAccount Management->API->Access Token

• --app-version <string>: application version

• --build-id <string>: build ID

• --platform <string>: currently only supports HarmonyOSNEXT

• --sourcemap: upload only sourcemap files

• --namecache: upload only namecache files

• --symbol: upload only so file symbol table files

• --product <string>: specify the product name to be uploaded, the default is default

• --target <string>: specify the target name to be uploaded, the default is default

• --module: specify the module name of the module to be uploaded (module.name field in module.json5), multiple use , to separate

• --package <string>: Specify the package name of the module to be uploaded (name field in oh-package.json5), use , to separate multiple names

• --output <string>: package file generation directory, default is TingyunSymbol directory under the current directory

• --remove-output: delete package file after uploading, default is not deleted

• --no-upload: only package upload file, no report

• --upload-retries <int>: number of retries after sending failure. Default is 0, no retry after failure

Others

View version

tingyun-cli -v

Specify configuration file path

Flags:

• --config <string>: Specify configuration file location, global flags, effective for all command subcommands.

Example:

tingyun-cli upload <project root directory> --beacon=<beacon> --app-token=<app token> --token=<token> --app-version=<app version> --build-id=<buildId> --platform=HarmonyOSNEXT --config /my/config/dir/.tingyunclirc.toml

hvigor plugin

This plugin is used to automatically collect and report symbol table related files when compiling the HarmonyOS NEXT project.

Usage examples

Installation

1. Introduce hvigor plugin dependency

Add plugin dependency in the project root directory hvigor/hvigor-config.json5

{
  // ...
  "dependencies": {
    "@tingyun-common/hvigor-plugin-build": "<version number>"
  }
}

2. Register the plugin in the project-level 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: "<app token>"
    }),
    // ... other plugins
  ]
}

3. Sync project

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

Note:

• If tingyun-cli customizes the download address, you need to ensure that the environment variable of the relevant download address exists before executing

4. Build the project, observe the log output, and you can see that the files are packaged and reported

Uninstall

1. Unregister the plugin in the project-level hvigorfile.ts

2. Comment or remove the plugin dependency in the project root directory hvigor/hvigor-config.json5

3. Sync project

Plugin configuration items

type TingyunBuildPluginOptions = {
// The directory to be reported. If the user does not set it, the plugin will automatically pass the project root directory
include?: string[];
// Upload address, directly configure beacon or configure it in the configuration file specified by configFile
beacon?: string;
// auth token, directly configure beacon or configure it in the configuration file specified by configFile
token?: string;
// Application token, directly configure beacon or configure it in the configuration file specified by configFile
appToken?: string;
// Configuration file path, when beacon, token, appToken are not specified, it will try to read from the configuration file
configFile?: string;
// BuildMode of the plugin to be executed, the default is release
buildMode?: string;
// Application version
appVersion?: string;
// Build ID
buildId?: string;
// Specify the product name to be uploaded, which will be automatically obtained by default during the build
product?: string;
// Specify the target name to be uploaded
target?: string;
// Module name to be reported, all modules under the project are reported by default
modules?: string[];
// Package name to be reported (name in oh-package.json5), all packages under the project are reported by default
packages?: string[];
// Only sourceMap reporting switch is collected, default false
sourceMap?: boolean;
// Only nameCache reporting switch is collected, default false
nameCache?: boolean;
// Only symbol reporting switch is collected, default false
symbol?: boolean;
// Output directory
output?: string;
// Remove the packaged zip file after uploading, default false
removeOutput?: boolean;
// Only package and do not report, default false
noUpload?: boolean;
// Length of each batch of demangle parameters, default 4096
demangleBatchSize?: number;
// Number of retries, default 0
uploadRetries?: number;
};