arkts-skills/arkts-development/references/hstack.md

Stack Trace Analysis Tool (hstack)

hstack is a tool for resolving obfuscated crash stack traces from Release builds back to their original source code locations. It supports Windows, Mac, and Linux.

Command Format

hstack [options]

Command Parameters

Parameter	Description
-i, --input	Specify the crash file archive directory
-c, --crash	Specify a single crash stack trace
-o, --output	Specify the output directory for parsed results (output file when using -c)
-s, --sourcemapDir	Specify the sourcemap file archive directory
--so, --soDir	Specify the shared object (.so) file archive directory
-n, --nameObfuscation	Specify the nameCache file archive directory
-v, --version	Show version
-h, --help	Show help

Parameter Constraints

• Crash file directory (-i) and crash stack trace (-c) must provide exactly one
• Sourcemap (-s) and shared object (--so) directories must provide at least one
• To restore obfuscated method names, both sourcemap and nameCache files must be provided
• Path parameters do not support special characters: `~!@#$^&*=|{};,\s\[\]<>?

Environment Setup

1. Add the Command Line Tools bin directory to the PATH environment variable
2. Add Node.js to the environment variables
3. To parse C++ exceptions, add the SDK's native\llvm\bin directory to the ADDR2LINE_PATH environment variable

Usage Examples

Parse Crash File Directory

# Full parse command
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir

# Parse using sourcemap only (ArkTS)
hstack -i crashDir -o outputDir -s sourcemapDir

# Parse using .so files only (C++)
hstack -i crashDir -o outputDir --so soDir

# Include method name restoration
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir

Parse a Single Stack Trace

# Output to console
hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir

# Output to file
hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir -o result.txt

Output

• Parsed results are written to the directory specified by -o, with filenames prefixed by _ followed by the original crash filename
• When -o is not specified:
  • With -i input: output to the crashDir directory
  • With -c input: output directly to console

File Sources

Sourcemap Files

Sourcemap files from build artifacts, containing:

• Path information mapping
• Line/column number mapping (mappings field)
• package-info information

NameCache Files

NameCache files from build artifacts, containing:

• IdentifierCache: Identifier obfuscation mapping
• MemberMethodCache: Member method obfuscation mapping, format: "sourceMethodName:startLine:endLine": "obfuscatedMethodName"

Shared Object (.so) Files

When building Release applications, .so files do not include symbol tables by default. To generate .so files with symbol tables, configure in the module's build-profile.json5:

{
  "buildOption": {
    "externalNativeOptions": {
      "arguments": "-DCMAKE_BUILD_TYPE=RelWithDebInfo"
    }
  }
}

Stack Trace Resolution Principles

Crash Stack Format

at har (entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js:58:58)
at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)

Path format: referrerPackageName|referredPackageName|version|sourceRelativePath

Resolution Steps

1. Find the sourcemap based on path information

   • From the path entry|har|1.0.0|src/main/ets/..., look up the corresponding field in the entry module's sourcemap

2. Restore path and line/column numbers using sourcemap

   • Parse using the sources and mappings fields
   • If package-info is included, perform a secondary parse for more accurate source locations

3. Restore method names using nameCache

   • Find all entries matching the obfuscated method name
   • Match the correct source method name based on the restored line number range

Resolution Example

Original stack trace:

at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)

After resolution:

at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3)

CI/CD Integration

# Automated parsing script example
hstack \
  -i ./crash-logs \
  -o ./parsed-logs \
  -s ./build/sourcemap \
  --so ./build/libs \
  -n ./build/nameCache

FAQ

1. Method names not restored: Ensure both -s and -n parameters are provided
2. C++ stack traces not parsed: Check the ADDR2LINE_PATH environment variable configuration
3. No symbol table in .so files: Configure the RelWithDebInfo build option