1# rawheap-translator
2
3## When to Use
4
5To facilitate fault locating, applications automatically generate heap dump files in the case of ArkTS OOM errors. The VM scans and saves all object information on the current heap and generates .rawheap files in binary format. You can use the rawheap_translator tool (available in the **toolchains** directory of the SDK) to parse the files and convert them into .heapsnapshot files, which can be opened on [DevEco Studio](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-snapshot-basic-operations-V5#section6760173514388).
6
7## Operation Guide
8
9### How to Obtain
10
11The rawheap_translator tool is compatible with OHOS, Windows, Linux, and macOS. You can obtain it from either of the following directories:
12
13- From the **/bin/rawheap_translator** path on OHOS devices.
14
15- From the **toolchains** directory of the SDK in other platforms.
16
17### Environment Configuration
18
19- On Windows:
20
21  Choose **This PC** > **Properties** > **Advanced system settings** > **Advanced** > **Environment Variables** > **Path** > **Edit**, and input the path of **rawheap_translator.exe**. After that, restart the PC, and run the **hilogtool** command in the cmd window.
22
23- On macOS:
24
25  1. Start the terminal tool and run the following command:
26
27  echo $SHELL
28
29  a. If the command output is **/bin/bash**, open the **.bash_profile** file.
30
31  vi ~/.bash_profile
32
33  b. If the command output is **/bin/zsh**, open the **.zshrc** file.
34
35  vi ~/.zshrc
36
37  2. Press **i** to enter the **Insert** mode.
38
39  3. Add the path of **rawheap_translator.exe**:
40
41  export PATH=$PATH:/path/to/your/rawheap_translator
42
43  4. Press **Esc** to exit the edit mode, and then enter **:wq** and press **Enter** to save the settings and exit.
44
45  5. Run the following command for the environment variable to take effect.
46
47  a. If the **.bash_profile** file is opened in step a, run the following command:
48
49  source ~/.bash_profile
50
51  b. If the **.zshrc** file is opened in step a, run the following command:
52
53  source ~/.zshrc
54
55  6. After the environment variable configuration is finished, restart the PC.
56
57
58## How to Use
59
60### Parsing Command
61```bash
62rawheap_translator <rawheap_file> [heapsnapshot_file]
63```
64### Parameters
65
66| Parameter| Description| Example|
67| -------- | ----------------- | ---------------------------------- |
68| \<rawheap_file\> | (Mandatory) Path of the .rawheap file generated upon an OOM error:<br>**/data/log/reliability/resource_leak/memory_leak**| Parse the .rawheap file in the specified directory **D:\temp\rawheap**:<br>**rawheap_translator D:\temp\rawheap\xxx.rawheap**<br>Parse the .rawheap file in the current directory:<br>**rawheap_translator xxx.rawheap**|
69| [heapsnapshot_file] | (Optional) Specifies the name and path of the generated file. The file name extension must be **heapsnapshot**.<br>If this parameter is not specified, the current path is used by default. An example of the generated file name is **hprof_2024-11-19-21-13-20.heapsnapshot**.| Parse the .rawheap file in the current directory and generate the .heapsnapshot in the specified path **D:\temp**:<br>**rawheap_translator xxx.rawheap D:\temp\xxx.heapsnapshot**<br>Parse the .rawheap file in the current directory and generate the .heapsnapshot in the current directory:<br>**rawheap_translator xxx.rawheap xxx.heapsnapshot**|
70
71## Examples of Using Parsing Commands
72
73### On OHOS
74
75Run the **hdc shell** command to start the parsing tool in **/bin/rawheap_translator**. You are advised to specify the path of the **.heapsnapshot** file to **/data/local/tmp**, as you may not have the write permission on other paths.
76```bash
77> 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
78[INFO] Main: start to translate rawheap!
79[INFO] Meta::ParseVersion: current metadata version is 1.0.0
80[INFO] Meta::ParseTypeEnums: parse type enums, size=213
81[INFO] Meta::ParseTypeList: parse type list, obj size = 214
82[INFO] Meta::ParseTypeLayout: parse type layout, size=1
83[INFO] Meta::ParseTypeLayout: parse type desc, size=4
84[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
85[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
86[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
87[INFO] Rawheap version is
88[INFO] RawHeapTranslate::Translate: start to read objects
89[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
90[INFO] RawHeapTranslate::Translate: read objects finish!
91[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
92[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
93[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
94[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
95[INFO] Main: start to serialize!
96[INFO] HeapSnapshotJSONSerializer::Serialize begin
97[INFO] HeapSnapshotJSONSerializer::Serialize exit
98[INFO] Main: translate success! file save to /data/local/tmp/myapplication-7979-7979.heapsnapshot
99```
100
101### On Windows
102Open the cmd window, go to the .rawheap file path, and run the parsing command to generate the .heapsnapshot file in the current path.
103```bash
104> rawheap_translator.exe memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot
105[INFO] Main: start to translate rawheap!
106[INFO] Meta::ParseVersion: current metadata version is 1.0.0
107[INFO] Meta::ParseTypeEnums: parse type enums, size=213
108[INFO] Meta::ParseTypeList: parse type list, obj size = 214
109[INFO] Meta::ParseTypeLayout: parse type layout, size=1
110[INFO] Meta::ParseTypeLayout: parse type desc, size=4
111[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
112[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
113[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
114[INFO] Rawheap version is
115[INFO] RawHeapTranslate::Translate: start to read objects
116[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
117[INFO] RawHeapTranslate::Translate: read objects finish!
118[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
119[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
120[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
121[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
122[INFO] Main: start to serialize!
123[INFO] HeapSnapshotJSONSerializer::Serialize begin
124[INFO] HeapSnapshotJSONSerializer::Serialize exit
125[INFO] Main: translate success! file save to myapplication-7979-7979.heapsnapshot
126```
127
128### On Linux
129Go to the path of the .rawheap file, and run the parsing command to generate the .heapsnapshot file in the current path.
130```bash
131> ./rawheap_translator memory_leak/memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot
132[INFO] Main: start to translate rawheap!
133[INFO] Meta::ParseVersion: current metadata version is 1.0.0
134[INFO] Meta::ParseTypeEnums: parse type enums, size=213
135[INFO] Meta::ParseTypeList: parse type list, obj size = 214
136[INFO] Meta::ParseTypeLayout: parse type layout, size=1
137[INFO] Meta::ParseTypeLayout: parse type desc, size=4
138[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
139[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
140[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
141[INFO] Rawheap version is
142[INFO] RawHeapTranslate::Translate: start to read objects
143[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
144[INFO] RawHeapTranslate::Translate: read objects finish!
145[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
146[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
147[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
148[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
149[INFO] Main: start to serialize!
150[INFO] HeapSnapshotJSONSerializer::Serialize begin
151[INFO] HeapSnapshotJSONSerializer::Serialize exit
152[INFO] Main: translate success! file save to myapplication-7979-7979.heapsnapshot
153```
154
155### On macOS
156Open the device, go to the .rawheap file path, and run the parsing command to generate the .heapsnapshot file in the current path.
157```bash
158> rawheap_translator memory_leak/memleak-js-com.example.myapplication-7979-7979-20241215191332.rawheap myapplication-7979-7979.heapsnapshot
159[INFO] Main: start to translate rawheap!
160[INFO] Meta::ParseVersion: current metadata version is 1.0.0
161[INFO] Meta::ParseTypeEnums: parse type enums, size=213
162[INFO] Meta::ParseTypeList: parse type list, obj size = 214
163[INFO] Meta::ParseTypeLayout: parse type layout, size=1
164[INFO] Meta::ParseTypeLayout: parse type desc, size=4
165[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
166[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
167[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
168[INFO] Rawheap version is
169[INFO] RawHeapTranslate::Translate: start to read objects
170[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
171[INFO] RawHeapTranslate::Translate: read objects finish!
172[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
173[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
174[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
175[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
176[INFO] Main: start to serialize!
177[INFO] HeapSnapshotJSONSerializer::Serialize begin
178[INFO] HeapSnapshotJSONSerializer::Serialize exit
179[INFO] Main: translate success! file save to myapplication-7979-7979.heapsnapshot
180```
181
182## File Specifications
183
184As shown in the following table, in the OOM scenario, when the ArkTS heap memory usage is high and the number of live objects is large, the time required for generating the .rawheap file is long, and the file size is also large. You can subscribe to the [resource leak events](../dfx/hiappevent-watcher-resourceleak-events.md) and customize the event processing logic.
185
186To determine the performance and traffic overhead caused by reporting the .rawheap file to the server, you can refer to the following table to obtain the size of the compressed .rawheap file. Generally, the compression ratio is 10:1 and varies depending on the compression tool in use.
187
188| ArkTS Heap Memory Size (MB)| Number of Live Objects| File Generation Duration (s)| .rawheap File Size (MB)| Compressed File Size (MB)|
189| :---------: | :--------------: | :-----------: | :----------: | :----------: |
190| 11.00 | 99812 |  0.08 | 7.00 | 0.77 |
191| 25.30 | 250059 |  0.17 | 19.00 | 1.90 |
192| 50.40 | 496134 |  0.29 | 38.00 | 3.55 |
193| 72.00 | 759037 |  0.49 | 54.00 | 4.77 |
194| 104.00 | 47232 |  0.14 | 102.00 | 8.25 |
195| 130.00 | 1308804 |  0.92 | 100.00 | 10.40 |
196| 152.00 | 1493272 |  1.12 | 117.00 | 11.50 |
197| 187.00 | 1838800 |  1.50 | 144.00 | 13.00 |
198| 354.00 | 50704 |  0.31 | 352.00 | 27.25 |
199| 643.00 | 7772538 |  2.63 | 444.00 | 51.00 |
200| 750.00 | 6163456 |  3.64 | 605.00 | 59.55 |
201
202
203## FAQs
204### What should I do if the tool version is too early?
205Symptom: The message "The rawheap file's version 2.0.0 is not matched the current rawheap translator, please use the newest version of the translator!" is displayed during parsing.
206```bash
207[INFO] Main: start to translate rawheap!
208[INFO] Meta::ParseVersion: current metadata version is 1.0.0
209[INFO] Meta::ParseTypeEnums: parse type enums, size=213
210[INFO] Meta::ParseTypeList: parse type list, obj size = 214
211[INFO] Meta::ParseTypeLayout: parse type layout, size=1
212[INFO] Meta::ParseTypeLayout: parse type desc, size=4
213[ERRO] The rawheap file's version 1.1.0 is not matched the current rawheap translator, please use the newest version of the translator!
214```
215Solution: Upgrade the tool.
216
217### What should I do if I have no permission on the file?
218Symptom: The message "FileStream: open file failed!" is displayed during parsing.
219```bash
220[INFO] Main: start to translate rawheap!
221[INFO] Meta::ParseVersion: current metadata version is 1.0.0
222[INFO] Meta::ParseTypeEnums: parse type enums, size=213
223[INFO] Meta::ParseTypeList: parse type list, obj size = 214
224[INFO] Meta::ParseTypeLayout: parse type layout, size=1
225[INFO] Meta::ParseTypeLayout: parse type desc, size=4
226[INFO] Meta::SetObjTypeBitFieldOffset: offset=72
227[INFO] Meta::SetNativatePointerBindingSizeOffset: offset=32
228[INFO] RawHeapTranslate::ReadSectionInfo: sectionSize=6
229[INFO] Rawheap version is
230[INFO] RawHeapTranslate::Translate: start to read objects
231[INFO] RawHeapTranslate::ReadObjTable: read object, cnt=96432
232[INFO] RawHeapTranslate::Translate: read objects finish!
233[INFO] RawHeapTranslate::ReadStringTable: read string table, cnt=11208
234[INFO] RawHeapTranslate::ReadRootTable: find root obj 6244
235[INFO] RawHeapTranslate::FillNodesAndBuildEdges: start to build edges!
236[INFO] RawHeapTranslate::FillNodesAndBuildEdges: build edges finish!
237[INFO] Main: start to serialize!
238[ERRO] FielStream: open file failed
239```
240Solution: Specify a path with the write permission for generating the file. For example, specify the path to **/data/local/tmp**.
241