1# rawheap-translator工具
2
3## 使用场景
4
5为方便开发者定位问题，当前应用在ArkTS内存OOM时会自动进行Heapdump，虚拟机会扫描并保存当前堆上的所有对象信息，生成rawheap文件。该文件以二进制形式保存，开发者可从SDK中toolchains路径下获取rawheap_translator工具进行解析，转换成heapsnapshot文件，可通过[DevEco Studio](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-snapshot-basic-operations-V5#section6760173514388)打开查看。
6
7## 使用指导
8
9### 工具获取
10
11当前工具适配了OHOS、Windows、Linux、MacOS平台，获取方法如下：
12
13- 设备内获取：/bin/rawheap_translator，可在oh设备使用；
14
15- SDK中获取：不同平台工具在SDK路径下toolchains目录获取，可在对应平台下使用。
16
17### 环境配置
18
19- Windows环境变量设置方法
20
21  在此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量 > Path > 编辑 中，将rawheap_translator.exe所在路径添加到 Path，环境变量配置完成后，请重启电脑，即可在cmd窗口执行rawheap_translator命令。
22
23- MacOS环境变量设置方法
24
25  1）打开终端工具，执行以下命令，根据输出结果分别执行不同命令。
26
27  echo $SHELL
28
29  a. 如果输出结果为/bin/bash，则执行以下命令，打开.bash_profile文件。
30
31  vi ~/.bash_profile
32
33  b. 如果输出结果为/bin/zsh，则执行以下命令，打开.zshrc文件。
34
35  vi ~/.zshrc
36
37  2）单击字母“i”，进入Insert模式。
38
39  3）输入以下内容，添加PATH信息。
40
41  export PATH=$PATH:/path/to/your/rawheap_translator
42
43  4）编辑完成后，单击Esc键，退出编辑模式，然后输入“:wq”，单击Enter键保存。
44
45  5）执行以下命令，使配置的环境变量生效。
46
47  a. 如果步骤a时打开的是.bash_profile文件，请执行如下命令：
48
49  source ~/.bash_profile
50
51  b. 如果步骤a时打开的是.zshrc文件，请执行如下命令：
52
53  source ~/.zshrc
54
55  6）环境变量配置完成后，重启电脑。
56
57
58## 使用方法
59
60### 解析命令
61```bash
62rawheap_translator <rawheap_file> [heapsnapshot_file]
63```
64### 参数列表
65
66| 选项 | 描述 | 举例 |
67| -------- | ----------------- | ---------------------------------- |
68| \<rawheap_file\> | 必选参数，OOM时生成的rawheap文件路径：<br>/data/log/reliability/resource_leak/memory_leak | 解析指定目录(如：D:\temp\rawheap)下的rawheap文件：<br>rawheap_translator D:\temp\rawheap\xxx.rawheap<br>解析当前目录下的rawheap文件：<br>rawheap_translator xxx.rawheap |
69| [heapsnapshot_file] | 可选参数，指定生成的文件名称和路径，后缀名必须是heapsnapshot；<br>不指定则默认为当前路径，生成的文件名如：hprof_2024-11-19-21-13-20.heapsnapshot | 解析当前目录下的rawheap文件，并在指定路径(如：D:\temp)下生成的heapsnapshot:<br>rawheap_translator xxx.rawheap D:\temp\xxx.heapsnapshot<br>解析当前目录下的rawheap文件，并在当前路径下生成的heapsnapshot:<br>rawheap_translator xxx.rawheap xxx.heapsnapshot |
70> **注意：**
71>
72> [heapsnapshot_file] 需要指向具有读写权限的路径，如果未指定参数，需要保证当前执行cmd命令时所在目录具有读写权限。<br>
73> 以windows为例:
74> D:\> ...\rawheap_translator.exe ...\example.rawheap 命令中，需要保证“D:\”路径具有读写权限。
75
76## 解析命令示例
77
78### OHOS设备中解析示例
79
80通过hdc shell命令拉起解析工具，设备内工具路径：/bin/rawheap_translator，推荐指定生成heapsnapshot文件路径在/data/local/tmp下，其他路径可能面临没有写权限问题。
81```bash
82> hdc shell /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
83[INFO] Main: start to translate rawheap!
84[INFO] Meta::ParseVersion: current metadata version is 1.0.0
85[INFO] Meta::ParseTypeEnums: parse type enums, size=213
86[INFO] Meta::ParseTypeList: parse type list, obj size = 214
87[INFO] Meta::ParseTypeLayout: parse type layout, size=1
88[INFO] Meta::ParseTypeLayout: parse type desc, size=4
89[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
90[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
91[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
92[INFO] Rawheap version is
93[INFO] RawHeapTranslate::Translate: start to read objects
94[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
95[INFO] RawHeapTranslate::Translate: read objects finish!
96[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
97[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
98[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
99[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
100[INFO] Main: start to serialize!
101[INFO] HeapSnapshotJSONSerializer::Serialize begin
102[INFO] HeapSnapshotJSONSerializer::Serialize exit
103[INFO] Main: translate success! file save to /data/local/tmp/myapplication-7979-7979.heapsnapshot
104```
105
106### Windows系统中解析示例
107打开cmd并进入rawheap文件路径，调用解析工具命令，指定在当前路径下生成heapsnapshot文件。
108```bash
109> rawheap_translator.exe memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot
110[INFO] Main: start to translate rawheap!
111[INFO] Meta::ParseVersion: current metadata version is 1.0.0
112[INFO] Meta::ParseTypeEnums: parse type enums, size=213
113[INFO] Meta::ParseTypeList: parse type list, obj size = 214
114[INFO] Meta::ParseTypeLayout: parse type layout, size=1
115[INFO] Meta::ParseTypeLayout: parse type desc, size=4
116[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
117[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
118[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
119[INFO] Rawheap version is
120[INFO] RawHeapTranslate::Translate: start to read objects
121[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
122[INFO] RawHeapTranslate::Translate: read objects finish!
123[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
124[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
125[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
126[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
127[INFO] Main: start to serialize!
128[INFO] HeapSnapshotJSONSerializer::Serialize begin
129[INFO] HeapSnapshotJSONSerializer::Serialize exit
130[INFO] Main: translate success! file save to myapplication-7979-7979.heapsnapshot
131```
132
133### Linux系统中解析示例
134进入rawheap文件路径，调用解析工具命令，指定在当前路径下生成heapsnapshot文件。
135```bash
136> ./rawheap_translator memory_leak/memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot
137[INFO] Main: start to translate rawheap!
138[INFO] Meta::ParseVersion: current metadata version is 1.0.0
139[INFO] Meta::ParseTypeEnums: parse type enums, size=213
140[INFO] Meta::ParseTypeList: parse type list, obj size = 214
141[INFO] Meta::ParseTypeLayout: parse type layout, size=1
142[INFO] Meta::ParseTypeLayout: parse type desc, size=4
143[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
144[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
145[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
146[INFO] Rawheap version is
147[INFO] RawHeapTranslate::Translate: start to read objects
148[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
149[INFO] RawHeapTranslate::Translate: read objects finish!
150[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
151[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
152[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
153[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
154[INFO] Main: start to serialize!
155[INFO] HeapSnapshotJSONSerializer::Serialize begin
156[INFO] HeapSnapshotJSONSerializer::Serialize exit
157[INFO] Main: translate success! file save to myapplication-7979-7979.heapsnapshot
158```
159
160### MacOS系统中解析示例
161打开终端并进入rawheap文件路径，调用解析工具命令，指定在当前路径下生成heapsnapshot文件。
162```bash
163> rawheap_translator memory_leak/memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot
164[INFO] Main: start to translate rawheap!
165[INFO] Meta::ParseVersion: current metadata version is 1.0.0
166[INFO] Meta::ParseTypeEnums: parse type enums, size=213
167[INFO] Meta::ParseTypeList: parse type list, obj size = 214
168[INFO] Meta::ParseTypeLayout: parse type layout, size=1
169[INFO] Meta::ParseTypeLayout: parse type desc, size=4
170[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
171[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
172[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
173[INFO] Rawheap version is
174[INFO] RawHeapTranslate::Translate: start to read objects
175[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
176[INFO] RawHeapTranslate::Translate: read objects finish!
177[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
178[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
179[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
180[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
181[INFO] Main: start to serialize!
182[INFO] HeapSnapshotJSONSerializer::Serialize begin
183[INFO] HeapSnapshotJSONSerializer::Serialize exit
184[INFO] Main: translate success! file save to myapplication-7979-7979.heapsnapshot
185```
186
187## 文件参考规格
188
189rawheap文件大小、生成耗时，与当前ArkTS堆内存大小、存活对象数量强正相关（如下表所示），因此OOM场景下当ArkTS堆内存占用较大、存活对象数量较多时，生成的rawheap文件耗时会较长，文件也会较大。开发者可订阅[资源泄漏事件](../dfx/hiappevent-watcher-resourceleak-events.md)，自定义事件处理逻辑。
190
191为了方便开发者判断上报rawheap文件到服务器所带来的性能和流量开销，下表还给出了当前rawheap文件被压缩后的文件大小，一般压缩比是10:1，不同压缩工具略有差异，仅供开发者参考。
192
193| ArkTS堆内存（MB） | 存活对象数量（个） | 生成耗时（s） | rawheap文件（MB） | 压缩后文件（MB） |
194| :---------: | :--------------: | :-----------: | :----------: | :----------: |
195| 11.00 | 99812 |  0.08 | 7.00 | 0.77 |
196| 25.30 | 250059 |  0.17 | 19.00 | 1.90 |
197| 50.40 | 496134 |  0.29 | 38.00 | 3.55 |
198| 72.00 | 759037 |  0.49 | 54.00 | 4.77 |
199| 104.00 | 47232 |  0.14 | 102.00 | 8.25 |
200| 130.00 | 1308804 |  0.92 | 100.00 | 10.40 |
201| 152.00 | 1493272 |  1.12 | 117.00 | 11.50 |
202| 187.00 | 1838800 |  1.50 | 144.00 | 13.00 |
203| 354.00 | 50704 |  0.31 | 352.00 | 27.25 |
204| 643.00 | 7772538 |  2.63 | 444.00 | 51.00 |
205| 750.00 | 6163456 |  3.64 | 605.00 | 59.55 |
206
207
208## 常见问题
209### 工具版本过低
210工具解析时，提示：The rawheap file's version 2.0.0 is not matched the current rawheap translator, please use the newest version of the translator!
211```bash
212[INFO] Main: start to translate rawheap!
213[INFO] Meta::ParseVersion: current metadata version is 1.0.0
214[INFO] Meta::ParseTypeEnums: parse type enums, size=213
215[INFO] Meta::ParseTypeList: parse type list, obj size = 214
216[INFO] Meta::ParseTypeLayout: parse type layout, size=1
217[INFO] Meta::ParseTypeLayout: parse type desc, size=4
218[ERRO] The rawheap file's version 1.1.0 is not matched the current rawheap translator, please use the newest version of the translator!
219```
220原因：当前工具版本低于rawheap文件版本，升级工具可解决。
221
222### 文件没有权限
223工具解析时，提示：FileStream: open file failed!
224```bash
225[INFO] Main: start to translate rawheap!
226[INFO] Meta::ParseVersion: current metadata version is 1.0.0
227[INFO] Meta::ParseTypeEnums: parse type enums, size=213
228[INFO] Meta::ParseTypeList: parse type list, obj size = 214
229[INFO] Meta::ParseTypeLayout: parse type layout, size=1
230[INFO] Meta::ParseTypeLayout: parse type desc, size=4
231[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
232[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
233[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
234[INFO] Rawheap version is
235[INFO] RawHeapTranslate::Translate: start to read objects
236[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
237[INFO] RawHeapTranslate::Translate: read objects finish!
238[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
239[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
240[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
241[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
242[INFO] Main: start to serialize!
243[ERRO] FielStream: open file failed
244```
245原因：生成文件路径下没有写文件权限，指定到有写权限路径下可解决。参考路径：/data/local/tmp。
246