• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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> **NOTE**
71>
72> The value of **[heapsnapshot_file]** must be specified to a path that has the read and write permissions. If this parameter is not specified, ensure that the directory where the command is executed has the read and write permissions.<br>
73> For example,
74> when running the **D:\>...\rawheap_translator.exe...\example.rawheap** command on Windows, ensure that the **D:\** path has the read and write permissions.
75
76## Examples of Using Parsing Commands
77
78### On OHOS
79
80Run 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.
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### On Windows
107Open the cmd window, go to the .rawheap file path, and run the parsing command to generate the .heapsnapshot file in the current path.
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### On Linux
134Go to the path of the .rawheap file, and run the parsing command to generate the .heapsnapshot file in the current path.
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### On macOS
161Open the device, go to the .rawheap file path, and run the parsing command to generate the .heapsnapshot file in the current path.
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## File Specifications
188
189As 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.
190
191To 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.
192
193| ArkTS Heap Memory Size (MB)| Number of Live Objects| File Generation Duration (s)| .rawheap File Size (MB)| Compressed File Size (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## FAQs
209### What should I do if the tool version is too early?
210Symptom: 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.
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```
220Solution: Upgrade the tool.
221
222### What should I do if I have no permission on the file?
223Symptom: The message "FileStream: open file failed!" is displayed during parsing.
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```
245Solution: Specify a path with the write permission for generating the file. For example, specify the path to **/data/local/tmp**.
246