Upload RUM symbol table files by using CMS2 CLI - Application Real-Time Monitoring Service

In this tutorial, you use CMS2 CLI to upload symbol table files for Real User Monitoring (RUM). After the upload, RUM uses the symbol table files to restore compressed, obfuscated, or compiled error stacks to developer-readable source files, method names, function names, and line numbers.

Prerequisites

Before you use CMS2 CLI to upload symbol table files, make sure that the following requirements are met:

A RUM application is created and you have obtained the application workspace and service ID. For more information, see Connect a web and HTML app, Integrate a mini program, and Monitor Android apps.
To install the Alibaba Cloud CLI, see Install, update, and uninstall Alibaba Cloud CLI. You can run the aliyun cms2 --help command to verify that the CMS2 CLI is available.
You must have a CLI access credential with Cloud Monitor (CMS) permissions, which is configured by running the aliyun configure command. The following is an example of an access policy:
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cms:*",
      "Resource": "*"
    }
  ]
}
```

Command syntax

Run the following command to upload RUM symbol table files:

aliyun cms2 rum upload \
  --workspace <workspace-name> \
  --service-id <rum-service-id> \
  --version <release-version> \
  --file-kind <file-kind> \
  --dir <artifact-dir>

This command scans local symbol table files, requests a short-lived upload policy from CMS, and uploads the files to the specified storage location.

Parameters

Parameter	Required	Description
`--workspace`	Yes	The CMS workspace name.
`--service-id`	Yes	The RUM service ID.
`--version`	Yes	The release version or build version. The value must be the same as the version reported by the SDK.
`--file-kind`	Yes	The type of the symbol table file.
`--dir`	No	The directory to scan. You must specify at least one of `--dir` and `--file`.
`--file`	No	A single file to upload. You can specify this parameter multiple times.
`--dry-run`	No	Only scans and validates files without requesting an upload policy or uploading files. This parameter does not modify local files.
`--inject-debug-id`	No	If a sourcemap file does not have a Debug ID, injects a RUM debug ID runtime snippet into the companion JS file. This parameter does not modify the sourcemap file.
`--debug-id`	No	Explicitly specifies a Debug ID or Build ID. This value takes priority for all file types except `dsym`. The `dsym` upload policy does not pass a Debug ID.
`--max-files`	No	The maximum number of files to upload in a single command. Default value: `1000`.
`--recursive`	No	Specifies whether to recursively scan the directory specified by `--dir`. Default value: `true`.
`-o json`	No	Outputs the execution result in JSON format.

File types

The --file-kind parameter supports the following values:

Value	Description
`sourcemap`	Sourcemap files. Applicable to stack restoration for Web, HTML, mini program, and React Native JS errors.
`proguard`	Android ProGuard or R8 mapping files.
`dsym`	iOS dSYM files or directories.
`native-symbol`	Native symbol files, such as Android native symbol files.
`pdb`	Windows PDB files.

Validate the upload configuration

Before you integrate CMS2 CLI into your release pipeline or use it for the first time, use --dry-run to check parameters and files:

aliyun cms2 rum upload \
  --dry-run \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind sourcemap \
  --dir dist \
  --inject-debug-id

--dry-run does not request an upload policy or upload files. Even if --inject-debug-id is specified, it does not write back to JS files. Use this parameter to check:

Whether required parameters are complete.
Whether matching files exist in the directory.
Whether the file type is correct.
Whether sourcemap files have a Debug ID, or whether a companion JS file can be located to generate a runtime association identifier.
Whether native symbol or PDB file formats are valid.

Upload symbol table files

The following examples assume that the commands are run from the application project root directory. The --file and --dir parameters support relative paths and absolute paths. Relative paths are resolved from the current working directory. In CI/CD pipelines, switch to the project root directory first or use absolute paths for build artifacts to avoid file matching failures caused by working directory changes.

Upload sourcemap files

To upload Web, HTML, or mini program sourcemap files, run the following command:

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind sourcemap \
  --dir dist \
  --inject-debug-id

If a sourcemap file does not have a Debug ID, CLI returns the following message:

has no debugId; pass --inject-debug-id or --debug-id

In this case, use --inject-debug-id to inject a RUM debug ID runtime snippet into the companion JS file. CLI does not write a Debug ID to the sourcemap file. Before the upload, make sure that the injected JS file and the sourcemap file are used in the same release.

Upload Android mapping files

If your Android application has ProGuard or R8 obfuscation enabled, you can upload the mapping.txt file. The following example assumes that the command is run from the Android or Gradle project root directory:

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind proguard \
  --file app/build/outputs/mapping/release/mapping.txt

Make sure that the uploaded mapping.txt file is from the same build as the released APK or AAB and corresponds to the correct build variant.

Upload iOS dSYM files

You can upload a .dSYM directory:

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind dsym \
  --file path/to/Demo.app.dSYM

You can also upload a compressed dSYM file:

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind dsym \
  --file path/to/Demo.app.dSYM.zip

Make sure that the dSYM file matches the released iOS application version. When you pass a .dSYM directory, CLI temporarily compresses it into a .dSYM.zip file before uploading. The dsym upload policy request does not pass a Debug ID, so the --debug-id parameter does not take effect for dsym uploads.

Upload native symbol files

If your application contains native code, you can upload native symbol files:

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind native-symbol \
  --file path/to/libdemo.so

Upload a valid ELF file that contains symbol information. CLI automatically extracts the ELF Build ID. If the file is corrupted, is not a valid ELF file, or does not have a Build ID, CLI returns a format validation error. If the Build ID is missing, you can use --debug-id to explicitly specify one.

Upload PDB files

For Windows or PC applications, you can upload PDB files:

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind pdb \
  --file path/to/app.pdb

Make sure that the PDB file is from the same build as the released binary file. CLI extracts the Debug ID from PDB CodeView information. If a corresponding PE file, such as a .exe, .dll, .node, .pyd, or .sys file, exists in the same directory or scan directory, CLI also uses the age information from the PE file to correct the Debug ID. If automatic extraction fails, you can use --debug-id to explicitly specify one.

Use CMS2 CLI in CI/CD pipelines

Upload symbol table files after the production build completes and before the release. Store configurations such as --workspace, --service-id, and --version as pipeline variables.

The following example shows how to set environment variables and run the upload command in a pipeline:

export ARMS_RUM_SERVICE_ID="<rum-service-id>"
export RELEASE_VERSION="1.0.0"

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind sourcemap \
  --dir dist \
  --inject-debug-id

Common errors

Error message	Cause	Solution
`required flag(s) "file-kind" not set`	The file type is not specified.	Add the `--file-kind` parameter.
`one of --dir or --file is required`	No upload file or directory is specified.	Add the `--dir` or `--file` parameter.
`no upload files matched the given --file-kind`	No files matching the specified type are found.	Check whether the directory, file extension, and `--file-kind` value are correct.
`has no debugId; pass --inject-debug-id or --debug-id`	The sourcemap file does not have a Debug ID.	Add the `--inject-debug-id` or `--debug-id` parameter.
`--file-kind="xxx" is not a valid value`	The file type value is invalid.	Use a supported `--file-kind` value.
`bad magic number`	The native symbol file format is invalid.	Upload a valid native symbol file.
`read PDB header ... unexpected EOF`	The PDB file is invalid or corrupted.	Upload a complete and valid PDB file.

What's next

After the upload, you can view the stack parsing result on the error details or crash details page in the RUM console. If the stack is not parsed, check whether the upload version, file type, Debug ID, UUID, Build ID, and symbol table file match the released version.