1# hiperf 2 3hiperf is a command-line tool provided to capture performance data of a specific program or the entire system, like the kernel's perf tool. It can run on Windows, Linux, and macOS. 4 5## Environment Setup 6 7- The environment for OpenHarmony Device Connector (hdc) has been set up. For details, see [Environment Setup](hdc.md#environment-setup). 8 9- The devices are properly connected. 10 11## hiperf 12 13| Parameter| Description| 14| -------- | -------- | 15| -h/--help | Displays the help information.| 16| --debug | Outputs debug logs.| 17| --hilog | Writes logs to the hilog.| 18| --logpath | Specifies the log path.| 19| --logtag | Specifies the log level.| 20| --mixlog | Outputs mixed logs.| 21| --much | Output as many logs as possible.| 22| --nodebug | Outputs no log.| 23| --verbose | Outputs verbose logs.| 24 25## help 26 27Run the **--help** command to view help information. 28 29``` 30hiperf --help 31``` 32 33 34 35Run the following command to view the help information about a command: 36 37``` 38hiperf [command] --help 39``` 40 41## list 42 43Lists all the supported events on the device. The event names are used for the **-e** and **-g** parameters of the **stat** and **record** commands. 44 45**Parameters of the list command** 46 47| Parameter| Description| 48| -------- | -------- | 49| -h/--help | Displays the help information.| 50| hw | Lists the hardware events.| 51| sw | Lists the software events.| 52| tp | Tracepoint event.| 53| cache | Lists the hardware cache events.| 54| raw | Lists the original PMU events.| 55 56``` 57Usage: hiperf list [event type name] 58``` 59 60Run the **help** command to query the supported event types. 61 62``` 63hiperf list --help 64``` 65 66 67 68Run the following command to list the hardware events supported and not supported by the device. 69 70``` 71hiperf list hw 72``` 73 74 75 76## record 77 78Specifies the target program for sampling and saves the sampled data to a file (**/data/local/tmp/perf.data** by default). 79 80**Parameters of the record command** 81 82| Parameter| Description| 83| -------- | -------- | 84| -h/--help | Displays the help information.| 85| -a | Collects the full information of the system for evaluating all processes and threads.| 86| --exclude-hiperf | Collects no hiperf data.| 87| -c | Specifies the ID of the CPU to collect its data.| 88| --cpu-limit | Sets the maximum CPU usage during collection. Value range: 1 to 100. The default value is 25.| 89| -d | Sets the collection duration.| 90| -f | Sets the collection frequency. The default value is 4000 times per second. This parameter cannot be used together with **--period**.| 91| --period | Sets the event collection period, that is, the number of events to be collected each time. This parameter cannot be used together with **-f**.| 92| -e | Specifies the events to collect, which are separated by commas (,).| 93| -g | Specifies the event groups to collect, which are separated by commas (,).| 94| --no-inherit | Collects no subprocess data.| 95| -p | Specifies the IDs of the processes to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 96| -t | Specifies the IDs of the threads to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 97| --exclude-tid | Specifies the IDs of the threads not to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 98| --exclude-thread | Specifies the names of the threads not to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 99| --exclude-process | Specifies the names of the processes not to collect, which are separated by commas (,). This parameter must be used together with **-a**.| 100| --offcpu | Traces the time when a thread is out of CPU scheduling.| 101| -j | Samples branch stacks. The following filters are supported: **any**, **any_call**, **any_ret**, **ind_call**, **ind_jmp**, **cond** and **call**.| 102| -s/--callstack | Sets the stack mode.| 103| --kernel-callchain | Collects kernel stack information. This parameter must be used together with **-s fp/dwarf**.| 104| --callchain-useronly | Collects only user stacks.| 105| --delay-unwind | Unwinds the stack after recording. If **-s dwarf** is set, the stack is unwound during recording.| 106| --disable-unwind | Disables the unwinding of the stack during recording by default when **-s dwarf** is set.| 107| --disable-callstack-expand | Disables the 64 KB stack limit when **-s dwarf** is set. By default, call stacks are combined to a more complete call stack, which may be inaccurate.| 108| --enable-debuginfo-symbolic | Parses the symbols in the **.gnu_debugdata** section of elf when **-s fp/dwarf** is set. By default, the symbols are not parsed.| 109| --clockid | Sets the type of the clock to collect, which can be **monotonic** or **monotonic_raw**.| 110| --symbol-dir | Specifies the directory of the online symbol table file.| 111| -m | Sets the number of mmap pages. Value range: 2 to 1024. The default value is **1024**.| 112| --app | Specifies the names of the applications to collect, which are separated by commas (,). The applications must be in debuggable mode. If an application is not started, the system waits for 20s.| 113| --chkms | Sets the check interval. Value range: 1 to 200. The default value is **10**.| 114| --data-limit | Sets the limit of the output data size. When this limit is reached, the collection stops. By default, there is no limit.| 115| -o | Specifies the output file path.| 116| -z | Outputs the data in a compressed file.| 117| --restart | Collects performance indicator information about application startup. If a process is not started within 30 seconds, the record exits.| 118| --verbose | Outputs a more detailed report.| 119| --control [command]| Controls the collection command. The following commands are supported: **prepare**/**start**/**pause**/**resume**/**output**/**stop**.| 120| --dedup_stack | Deletes duplicate stacks from a record. This parameter cannot be used together with **-a**.| 121| --cmdline-size | Sets the value of the **/sys/kernel/tracing/saved_cmdlines_size** node. Value range: 512 to 4096.| 122| --report | Obtains the stack report after collection. This parameter cannot be used together with **-a**.| 123| --backtrack | Collects data in a previous period. This parameter must be used together with **--control prepare**.| 124| --backtrack-sec | Collects the duration of previous data. The value ranges from 5 to 30. The default value is 10s. This parameter must be used together with **--backtrack**.| 125| --dumpoptions | Dumps the command options.| 126 127``` 128Usage: hiperf record [options] [command [command-args]] 129``` 130 131Sample the process 267 for 10 seconds and use **dwarf** to collect and unwind stack memory of the process. 132 133``` 134hiperf record -p 267 -d 10 -s dwarf 135``` 136 137 138 139 140 141## stat 142 143Monitors the specified application and periodically prints the values of performance counters. 144 145**Parameters of the stat command** 146 147| Parameter| Description| 148| -------- | -------- | 149| -h/--help | Displays the help information.| 150| -a | Collects the full information of the system for evaluating all processes and threads.| 151| -c | Specifies the ID of the CPU to collect its data.| 152| -d | Sets the collection duration.| 153| -i | Sets the interval for printing stat information. Unit: ms.| 154| -e | Specifies the events to collect, which are separated by commas (,).| 155| -g | Specifies the event groups to collect, which are separated by commas (,).| 156| --no-inherit | Collects no subprocess data.| 157| -p | Specifies the IDs of the processes to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 158| -t | Specifies the IDs of the threads to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 159| --app | Specifies the names of the applications to collect, which are separated by commas (,). The applications must be in debuggable mode. If an application is not started, the system waits for 10s.| 160| --chkms | Sets the check interval. Value range: 1 to 200. The default value is **10**.| 161| --per-core | Obtains the print count of each CPU core.| 162| --pre-thread | Obtains the print count of each thread.| 163| --restart | Collects performance indicator information about application startup. If a process is not started within 30 seconds, the record exits.| 164| --verbose | Outputs a more detailed report.| 165| --dumpoptions | Dumps the command options.| 166 167``` 168Usage: hiperf stat [options] [command [command-args]] 169``` 170 171Monitor the performance counter of process 2349 on CPU0 for 3 seconds. 172 173``` 174hiperf stat -p 2349 -d 3 -c 0 175``` 176 177## dump 178 179Reads the data in **perf.data** without processing the file. You can check whether the original sampling data is correct. 180 181**Parameters of the dump command** 182 183| Parameter| Description| 184| -------- | -------- | 185| -h/--help | Displays the help information.| 186| --head | Outputs only the data header and attributes.| 187| -d | Outputs only data segments.| 188| -f | Outputs only additional functions.| 189| --syspath | Specifies the path of the symbol table file.| 190| -i | Specifies the resource file path.| 191| -o | Specifies the output file path. If this parameter is not set, the file is displayed on the screen.| 192| --elf | Outputs the ELF file.| 193| --proto | Outputs data in ProtoBuf format.| 194| --export | Exports user stack data to a split file and generates ut data.| 195 196``` 197Usage: hiperf dump [option] \<filename\> 198``` 199 200Run the **dump** command to read the **/data/local/tmp/perf.data** file and export it to the **/data/local/tmp/perf.dump** file. 201 202``` 203hiperf dump -i /data/local/tmp/perf.data -o /data/local/tmp/perf.dump 204``` 205 206 207 208 209 210## report 211 212Displays the sampled data (read from perf.data) in required format (such as JSON or ProtoBuf). 213 214**Parameters of the report command** 215 216| Parameter| Description| 217| -------- | -------- | 218| -h/--help | Displays the help information.| 219| --symbol-dir | Specifies the path of the symbol table file.| 220| --limit-percent | Sets the percentage of the content to display.| 221| -s | Displays the stack mode.| 222| --call-stack-limit-percent | Sets the percentage of the stack to display.| 223| -i | Specifies the resource file path. The default value is **perf.data**.| 224| -o | Specifies the output file path. If this parameter is not set, the file is displayed on the screen.| 225| --proto | Outputs data in ProtoBuf format.| 226| --json | Outputs data in JSON format.| 227| --diff | Displays the differences between the **-i** and **--diff **files.| 228| --branch | Displays the branch in the address instead of the IP address.| 229| --\<keys\> \<keyname1\>[,keyname2][,...] | Specifies the keywords, which can be **comms**, **pids**, **tids**, **dsos**, **funcs**, **from_dsos** or **from_funcs**, for example, **--comms hiperf**.| 230| --sort [key1],[key2],[...] | Sorts the data by keyword.| 231| --hide_count | Hides values in the report.| 232| --dumpoptions | Dumps the command options.| 233 234``` 235Usage: hiperf report [option] \<filename\> 236``` 237 238Display a common report, with the sampling limit of 1%. 239 240``` 241hiperf report --limit-percent 1 242``` 243 244 245 246## script 247 248You can use a script to sample data and generate flame graphs. You can obtain the script from [developtools_hiperf](https://gitee.com/openharmony/developtools_hiperf/tree/master/script). 249 2501. Sample data. 251 252 Run **command_script.py** to sample data. This script packages the **report** command. 253 254 ``` 255 usage: command_script.py [-h] 256 (-app PACKAGE_NAME | -lp LOCAL_PROGRAM | -cmd CMD | -p [PID [PID ...]] | -t [TID [TID ...]] | -sw) 257 [-a ABILITY] [-r RECORD_OPTIONS] [-lib LOCAL_LIB_DIR] 258 [-o OUTPUT_PERF_DATA] [--not_hdc_root] 259 ``` 260 261 Sample the **com.ohos.launch** package. 262 263 ``` 264 python command_script.py -app com.ohos.launch 265 ``` 266 267 Sample the **hdcd** process. 268 269 ``` 270 python command_script.py -lp hdcd 271 ``` 272 2732. Collect symbol tables. 274 275 Run **recv_binary_cache.py** to collect symbol tables. This script searches for the ELF in the specified paths based on the files and libraries recorded in **perf.data** and their **buildids**. 276 277 ``` 278 usage: recv_binary_cache.py [-h] [-i PERF_DATA] [-l LOCAL_LIB_DIR [LOCAL_LIB_DIR ...]] 279 ``` 280 281 The following example specifies two symbol table paths. 282 283 ``` 284 python recv_binary_cache.py -l Z:\OHOS_MASTER\out\ohos-arm-release\lib.unstripped Z:\OHOS_MASTER\out\ohos-arm-release\exe.unstripped 285 ``` 286 287 The ELF files of the specified symbol table paths are copied to the **binary_cache** folder. If the paths do not exist, the file in the device will be copied. 288 2893. Generate a flame graph. 290 291 Run **make_report.py** to display the sampled data in an HTML page. 292 293 ``` 294 usage: make_report.py [-h] [-i PERF_DATA] [-r REPORT_HTML] 295 ``` 296 297 Generate an HTML file. The default file name is **hiperf_report.html**. 298 299 ``` 300 python make_report.py -i perf.data 301 ``` 302
