81b3c82d16
- Translate arkguard-obfuscation.md (ArkGuard code obfuscation guide) - Translate hstack.md (stack trace analysis tool) - Translate codelinter.md (code linting tool) - Translate hvigor-commandline.md (Hvigor build tool) - Fix capitalization: ArkTs -> ArkTS in README title
154 lines
4.7 KiB
Markdown
154 lines
4.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
# 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
|