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 setup](hdc.md#environment-setup) is complete. 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 debug 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 | Lists the tracepoint events.| 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| --offcpu | Traces the time when a thread is out of CPU scheduling.| 100| -j | Samples branch stacks. The following filters are supported: **any**, **any_call**, **any_ret**, **ind_call**, **ind_jmp**, **cond** and **call**.| 101| -s/--callstack | Sets the stack mode.| 102| --kernel-callchain | Collects kernel stack information. This parameter must be used together with **-s fp/dwarf**.| 103| --callchain-useronly | Collects only user stacks.| 104| --delay-unwind | Unwinds the stack after recording. If **-s dwarf** is set, the stack is unwound during recording.| 105| --disable-unwind | Disables the unwinding of the stack during recording by default when **-s dwarf** is set.| 106| --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.| 107| --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.| 108| --clockid | Sets the type of the clock to collect, which can be **monotonic** or **monotonic_raw**.| 109| --symbol-dir | Specifies the directory of the online symbol table file.| 110| -m | Sets the number of mmap pages. Value range: 2 to 1024. The default value is **1024**.| 111| --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.| 112| --chkms | Sets the check interval. Value range: 1 to 200. The default value is **10**.| 113| --data-limit | Sets the limit of the output data size. When this limit is reached, the collection stops. By default, there is no limit.| 114| -o | Specifies the output file path.| 115| -z | Outputs the data in a compressed file.| 116| --restart | Collects performance indicator information about application startup. If a process is not started within 30 seconds, the record exits.| 117| --verbose | Outputs a more detailed report.| 118| --control [command]| Collects the **control** parameter of a command. The following commands are supported: **prepare**/**start**/**pause**/**resume**/**stop**.| 119| --dedup_stack | Deletes duplicate stacks from a record. This parameter cannot be used together with **-a**.| 120| --cmdline-size | Sets the value of the **/sys/kernel/tracing/saved_cmdlines_size** node. Value range: 512 to 4096.| 121| --report | Obtains the stack report after collection. This parameter cannot be used together with **-a**.| 122| --dumpoptions | Dumps the command options.| 123 124``` 125Usage: hiperf record [options] [command [command-args]] 126``` 127 128Sample the process 267 for 10 seconds and use **dwarf** to collect and unwind stack memory of the process. 129 130``` 131hiperf record -p 267 -d 10 -s dwarf 132``` 133 134 135 136 137 138## stat 139 140Monitors the specified application and periodically prints the values of performance counters. 141 142**Parameters of the stat command** 143 144| Parameter| Description| 145| -------- | -------- | 146| -h/--help | Displays the help information.| 147| -a | Collects the full information of the system for evaluating all processes and threads.| 148| -c | Specifies the ID of the CPU to collect its data.| 149| -d | Sets the collection duration.| 150| -i | Sets the interval for printing stat information. Unit: ms.| 151| -e | Specifies the events to collect, which are separated by commas (,).| 152| -g | Specifies the event groups to collect, which are separated by commas (,).| 153| --no-inherit | Collects no subprocess data.| 154| -p | Specifies the IDs of the processes to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 155| -t | Specifies the IDs of the threads to collect, which are separated by commas (,). This parameter cannot be used together with **-a**.| 156| --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.| 157| --chkms | Sets the check interval. Value range: 1 to 200. The default value is **10**.| 158| --per-core | Obtains the print count of each CPU core.| 159| --pre-thread | Obtains the print count of each thread.| 160| --restart | Collects performance indicator information about application startup. If a process is not started within 30 seconds, the record exits.| 161| --verbose | Outputs a more detailed report.| 162| --dumpoptions | Dumps the command options.| 163 164``` 165Usage: hiperf stat [options] [command [command-args]] 166``` 167 168Monitor the performance counter of process 2349 on CPU0 for 3 seconds. 169 170``` 171hiperf stat -p 2349 -d 3 -c 0 172``` 173 174## dump 175 176Reads the data in **perf.data** without processing the file. You can check whether the original sampling data is correct. 177 178**Parameters of the dump command** 179 180| Parameter| Description| 181| -------- | -------- | 182| -h/--help | Displays the help information.| 183| --head | Outputs only the data header and attributes.| 184| -d | Outputs only data segments.| 185| -f | Outputs only additional functions.| 186| --syspath | Specifies the path of the symbol table file.| 187| -i | Specifies the resource file path.| 188| -o | Specifies the output file path. If this parameter is not set, the file is displayed on the screen.| 189| --elf | Outputs the ELF file.| 190| --proto | Outputs data in ProtoBuf format.| 191| --export | Exports user stack data to a split file and generates ut data.| 192 193``` 194Usage: hiperf dump [option] \<filename\> 195``` 196 197Run the **dump** command to read the **/data/local/tmp/perf.data** file and export it to the **/data/local/tmp/perf.dump** file. 198 199``` 200hiperf dump -i /data/local/tmp/perf.data -o /data/local/tmp/perf.dump 201``` 202 203 204 205 206 207## report 208 209Displays the sampled data (read from perf.data) in required format (such as JSON or ProtoBuf). 210 211**Parameters of the report command** 212 213| Parameter| Description| 214| -------- | -------- | 215| -h/--help | Displays the help information.| 216| --symbol-dir | Specifies the path of the symbol table file.| 217| --limit-percent | Sets the percentage of the content to display.| 218| -s | Displays the stack mode.| 219| --call-stack-limit-percent | Sets the percentage of the stack to display.| 220| -i | Specifies the resource file path. The default value is **perf.data**.| 221| -o | Specifies the output file path. If this parameter is not set, the file is displayed on the screen.| 222| --proto | Outputs data in ProtoBuf format.| 223| --json | Outputs data in JSON format.| 224| --diff | Displays the differences between the **-i** and **--diff **files.| 225| --branch | Displays the branch in the address instead of the IP address.| 226| --\<keys\> \<keyname1\>[,keyname2][,...] | Specifies the keywords, which can be **comms**, **pids**, **tids**, **dsos**, **funcs**, **from_dsos** or **from_funcs**, for example, **--comms hiperf**.| 227| --sort [key1],[key2],[...] | Sorts the data by keyword.| 228| --hide_count | Hides values in the report.| 229| --dumpoptions | Dumps the command options.| 230 231``` 232Usage: hiperf report [option] \<filename\> 233``` 234 235Display a common report, with the sampling limit of 1%. 236 237``` 238hiperf report --limit-percent 1 239``` 240 241 242 243## script 244 245You 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). 246 2471. Sample data. 248 249 Run **command_script.py** to sample data. This script packages the **report** command. 250 251 ``` 252 usage: command_script.py [-h] 253 (-app PACKAGE_NAME | -lp LOCAL_PROGRAM | -cmd CMD | -p [PID [PID ...]] | -t [TID [TID ...]] | -sw) 254 [-a ABILITY] [-r RECORD_OPTIONS] [-lib LOCAL_LIB_DIR] 255 [-o OUTPUT_PERF_DATA] [--not_hdc_root] 256 ``` 257 258 Sample the **com.ohos.launch** package. 259 260 ``` 261 python command_script.py -app com.ohos.launch 262 ``` 263 264 Sample the **hdcd** process. 265 266 ``` 267 python command_script.py -lp hdcd 268 ``` 269 2702. Collect symbol tables. 271 272 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**. 273 274 ``` 275 usage: recv_binary_cache.py [-h] [-i PERF_DATA] [-l LOCAL_LIB_DIR [LOCAL_LIB_DIR ...]] 276 ``` 277 278 The following example specifies two symbol table paths. 279 280 ``` 281 python recv_binary_cache.py -l Z:\OHOS_MASTER\out\ohos-arm-release\lib.unstripped Z:\OHOS_MASTER\out\ohos-arm-release\exe.unstripped 282 ``` 283 284 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. 285 2863. Generate a flame graph. 287 288 Run **make_report.py** to display the sampled data in an HTML page. 289 290 ``` 291 usage: make_report.py [-h] [-i PERF_DATA] [-r REPORT_HTML] 292 ``` 293 294 Generate an HTML file. The default file name is **hiperf_report.html**. 295 296 ``` 297 python make_report.py -i perf.data 298 ``` 299
