1# rawheap-translator工具 2<!--Kit: ArkTS--> 3<!--Subsystem: ArkCompiler--> 4<!--Owner: @wanghuan2025--> 5<!--Designer: @wanghuan2025--> 6<!--Tester: @kir175; @zsw_zhushiwei--> 7<!--Adviser: @foryourself--> 8 9## 使用场景 10 11为方便开发者定位问题，应用在ArkTS内存OOM（Out of Memory）时会自动进行HeapDump。此操作会将虚拟机当前堆上的所有对象信息保存在后缀为.rawheap的二进制文件中。开发者可使用rawheap_translator工具解析.rawheap文件，生成.heapsnapshot文件。该文件可通过DevEco Studio的[Heap Snapshot离线导入](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-snapshot-basic-operations#section6760173514388)或Chrome浏览器的开发者工具中的内存工具导入并查看。 12 13## 使用指导 14 15### 工具获取 16 17此工具支持OHOS、Windows、Linux和MacOS平台，获取方法如下： 18 19- 设备内获取：/bin/rawheap_translator，仅适用于OHOS设备。 20- SDK中获取：sdk/default/openharmony/toolchains/rawheap_translator，适用于各平台。 21 22### 环境配置 23 24对于OHOS平台，由于其已在系统路径下内置了rawheap_translator工具，因此可以在终端中直接使用此工具。 25 26对于非OHOS平台，建议将从SDK中获取的rawheap_translator工具放置在稳定的路径下，并将该路径配置为系统环境变量。这样可以在终端中直接使用工具，无需每次指定路径。 27 28在不同系统中，环境变量的配置方法存在差异。以下提供一些配置示例，供开发者参考。 29 30- Windows环境变量设置方法（以Windows 10某版本为例）。 31 32 1. 右键点击“此电脑”选择“属性”选项。 33 2. 在弹出的窗口中，找到并点击“高级系统设置”标签。 34 3. 在弹出的窗口中，找到并点击“高级”页签下的“环境变量”按钮。 35 4. 在弹出的窗口中，找到并双击“系统变量”框中的“Path”变量。 36 5. 在弹出的窗口中，找到并点击“新建”按钮。 37 6. 将本地存放rawheap_translator工具的文件路径填至新建的文本框中。 38 7. 点击“确定”按钮关闭所有弹出的窗口。 39 8. 重启终端。 40 41- MacOS环境变量设置方法（以MacOS 15某版本为例）。 42 43 1. 打开终端工具，执行以下命令。 44 45 ```bash 46 echo $SHELL 47 ``` 48 49 2. 根据步骤1的返回结果做如下对应处理。 50 51 a. 如果返回结果为`/bin/bash`，则执行以下命令： 52 53 ```bash 54 echo 'export PATH=$PATH:/path/to/your/rawheap_translator' >> ~/.bash_profile 55 source ~/.bash_profile 56 ``` 57 58 b. 如果返回结果为`/bin/zsh`，则执行以下命令： 59 60 ```bash 61 echo 'export PATH=$PATH:/path/to/your/rawheap_translator' >> ~/.zshrc 62 source ~/.zshrc 63 ``` 64 65## 使用方法 66 67### 解析命令 68```bash 69rawheap_translator [rawheap_file] [heapsnapshot_file] 70``` 71### 参数列表 72 73| 选项 | 必选 | 描述 | 74| -------- | --- | ----------------- | 75| [rawheap_file] | 是 | 需要解析的应用OOM时生成的.rawheap文件路径。 | 76| [heapsnapshot_file] | 否 | 解析生成的heapsnapshot文件路径，路径必须具有读写权限。<br>参数缺省时，默认为当前执行命令的路径。<br>参数给定时，文件的后缀名必须是heapsnapshot。 77 78## 解析命令示例 79 80### 解析示例 81 82 83OHOS设备中解析示例 84OHOS设备内工具路径：/bin/rawheap_translator，推荐指定生成heapsnapshot文件路径为/data/local/tmp，其他路径可能面临没有写权限问题。 85```bash 86> /bin/rawheap_translator /data/log/reliability/resource_leak/memory_leak/memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap /data/local/tmp/myapplication-7979-7979.heapsnapshot 87``` 88Windows系统中解析示例 89打开cmd并进入rawheap文件路径，调用解析工具命令，指定在当前路径下生成heapsnapshot文件。 90```bash 91> rawheap_translator.exe memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot 92``` 93Linux系统中解析示例 94进入rawheap文件路径，调用解析工具命令，指定在当前路径下生成heapsnapshot文件。 95```bash 96> ./rawheap_translator memory_leak/memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot 97``` 98MacOS系统中解析示例 99打开终端并进入rawheap文件路径，调用解析工具命令，指定在当前路径下生成heapsnapshot文件。 100```bash 101> rawheap_translator memory_leak/memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot 102``` 103参考输出 104```bash 105[INFO ] ParseVersion current metadata version is 1.0.0 106[INFO ] ParseTypeEnums total JSType count 214 107[INFO ] ParseTypeList total metadata count 220 108[INFO ] SetBitField set BitField offset 8 109[INFO ] SetBitField set BindingSize offset 32 110[INFO ] SetBitField set Length offset 8 111[INFO ] SetBitField set Data offset 16 112[INFO ] ReadVersion current rawheap version is 1.0.0 113[INFO ] RawHeap start to translate rawheap 114[INFO ] ReadRootTable root node count 6244 115[INFO ] ReadStringTable string table count 11208 116[INFO ] ReadObjTable section objects count 96432 117[INFO ] Translate success 118[INFO ] Serialize start to serialize 119[INFO ] Translate file save to /data/local/tmp/myapplication-7979-7979.heapsnapshot 120``` 121 122## 文件参考规格 123 124rawheap文件的大小和生成耗时与当前ArkTS堆内存大小及存活对象数量呈强正相关。当ArkTS堆内存占用较大、存活对象数量较多时，生成的rawheap文件会更大，耗时也会更长。开发者可以订阅[资源泄漏事件](../dfx/hiappevent-watcher-resourceleak-events.md)，自定义事件处理逻辑。 125 126从API version 20开始，虚拟机支持两种规格的HeapDump。 127| 规格 | 特点 | 128| :--- | :--- | 129| TRIM_LEVEL_1 | dump速度快，生成的rawheap文件大。<br>API version 20之前版本，虚拟机默认为TRIM_LEVEL_1规格。 | 130| TRIM_LEVEL_2 | dump速度稍慢，生成的rawheap文件大小相比TRIM_LEVEL_1缩小40%左右。 | 131 132为了方便开发者了解上报rawheap文件到服务器所带来的性能和流量开销，下表给出了在不同的堆大小下，不同规格的HeapDump生成的rawheap文件大小、生成耗时、解析耗时的示例，仅供开发者参考。 133 134|规格|堆大小（MB）|rawheap文件（MB）|生成耗时（s）|解析耗时（s）| 135|:---|:---|:---|:---|:---| 136| TRIM_LEVEL_1 | 690 | 629 | 2.64 | 14 | 137| TRIM_LEVEL_2 | 690 | 376 | 3.47 | 14 | 138| TRIM_LEVEL_1 | 653 | 618 | 2.63 | 13 | 139| TRIM_LEVEL_2 | 653 | 347 | 3.36 | 13 | 140| TRIM_LEVEL_1 | 576 | 563 | 3.63 | 15 | 141| TRIM_LEVEL_2 | 576 | 294 | 4.53 | 15 | 142 143 144## 常见问题 145### 工具版本不匹配 146**问题现象**<br> 147工具解析时会提示：原始堆文件的版本 2.0.0 与当前的原始堆文件翻译器不匹配，请使用最新版本的翻译器。 148```bash 149[INFO ] ParseVersion current metadata version is 1.0.0 150[INFO ] ParseTypeEnums total JSType count 214 151[INFO ] ParseTypeList total metadata count 220 152[INFO ] SetBitField set BitField offset 8 153[INFO ] SetBitField set BindingSize offset 32 154[INFO ] SetBitField set Length offset 8 155[INFO ] SetBitField set Data offset 16 156[INFO ] ReadVersion current rawheap version is 2.0.0 157[ERROR] ParseRawheap The rawheap file's version 2.0.0 is not matched the current rawheap translator, please use the newest version of the translator! 158``` 159**原因**<br> 160当前工具版本低于rawheap文件版本。<br> 161**解决措施**<br> 162升级工具版本至2.0.0可解决此问题。 163 164### 文件无法打开 165**问题现象**<br> 166工具解析时，提示：open file failed 167```bash 168[INFO ] ParseVersion current metadata version is 1.0.0 169[INFO ] ParseTypeEnums total JSType count 214 170[INFO ] ParseTypeList total metadata count 220 171[INFO ] SetBitField set BitField offset 8 172[INFO ] SetBitField set BindingSize offset 32 173[INFO ] SetBitField set Length offset 8 174[INFO ] SetBitField set Data offset 16 175[INFO ] ReadVersion current rawheap version is 1.0.0 176[INFO ] RawHeap start to translate rawheap 177[INFO ] ReadRootTable root node count 6244 178[INFO ] ReadStringTable string table count 11208 179[INFO ] ReadObjTable section objects count 96432 180[INFO ] Translate success 181[ERROR] Initialize open file failed 182``` 183**原因**<br> 184定的生成文件路径没有写入权限。<br> 185**解决措施**<br> 186更改到有写权限的路径可以解决。