1# hiperf 2 3 4hiperf is a performance sampling and analysis tool provided for developers. It extends the user-mode capabilities based on the kernel perf mechanism and can conduct performance sampling of the specified application or the entire system. 5 6 7You can run the **hiperf -h** command to display the commands supported by hiperf. 8 9 10The following describes the common commands (**list**, **stat**, **record**, and **report**) supported by hiperf. 11 12 13## list 14 15 16### Parameters 17 18The **list** command lists all the perf events supported by the device. The event names are used for the **-e** and **-g** parameters of the **stat** and **record** commands. 19 20 21``` 22hiperf list [event type] 23``` 24 25| Parameter| Description| 26| -------- | -------- | 27| hw | Lists the hardware events supported by the performance monitoring unit (PMU).| 28| sw | Lists the software events supported. | 29| tp | Lists the tracepotint events supported. | 30| cache | Lists the cache events supported by the PMU. | 31| raw | Lists the raw PMU events supported.| 32 33 34### Example 35 36List the hardware events supported by the PMU. The command also lists the events that are not supported by the PMU. 37 38 39``` 40hiperf list hw 41event not support hw-stalled-cycles-backend 42event not support hw-stalled-cycles-frontend 43event not support hw-ref-cpu-cycles 44 45Supported events for hardware: 46 hw-cpu-cycles 47 hw-instructions 48 hw-cache-references 49 hw-cache-misses 50 hw-branch-instructions 51 hw-branch-misses 52 hw-bus-cycles 53``` 54 55 56## stat 57 58 59### Parameters 60 61 The **stat** command monitors the specified application and periodically prints the values of performance counters. 62 63``` 64hiperf stat [options] 65Collect performance counter information. 66``` 67 68 69| Parameter| Description| 70| -------- | -------- | 71| -a | Collects the values of all threads and default performance counters of the system.| 72| -c | Specifies the IDs of the CPUs to monitor. Use commas (,) to separate multiple CPU IDs, for example **0,1,2**. | 73| -d <_sec_> | Specifies the monitoring period, in seconds. | 74| -i <_ms_> | Specifies the interval for printing the monitored events, in milliseconds. | 75| -e | Specifies the events to monitor. You can run the **list** command to list all the events supported. **event:u** indicates an event in the user space, and **event:k** indicates an event in the kernel space. | 76| -g | Specifies a group of events to monitor. The events in the same group are monitored by the same PMU.| 77| --no-inherit | Leaves the sub-threads of the target thread or process not monitored.| 78| -p | Specifies the process IDs (PIDs) to monitor.| 79| -t | Specifies the thread IDs (TIDs) to monitor.| 80| --verbose | Displays detailed report, including raw time data.| 81 82 83### Example 84 85Monitor the entire system for 3 seconds. 86 87 88``` 89hiperf stat -d 3 -a 90this is root mode, perfEventParanoid assume as -1 91Start Profiling... 92Timeout exit (total 3009 ms) 93 count name | comment | coverage 94 132523 hw-branch-instructions | 15.750 M/sec | (100%) 95 62554 hw-branch-misses | 47.202372% miss rate | (100%) 96 6994768 hw-cpu-cycles | 0.832068 GHz | (100%) 97 1237627 hw-instructions | 5.651758 cycles per instruction | (100%) 98 248 sw-context-switches | 29.959 K/sec | (100%) 99 0 sw-page-faults | 0.000 /sec | (100%) 100 9402580 sw-task-clock | 0.002758 cpus used | (100%) 101``` 102 103 104### Field Description 105 106| Field| Description| 107| -------- | -------- | 108| count | Indicates the times that an event occurred.| 109| name | Indicates the event name. You can run the **list** command to list all the supported events. **hw** stands for hardware, and **sw** for software. | 110| comment | Provides values calculated from those in the **Count** column for easy understanding. For example, the CPU frequency (**hw-cpu-cycles**) is converted to **0.832068** GHz from **6994768**. | 111| coverage | Indicates the percentage of PMU resources occupied by the event. The number of events to be monitored by a PMU varies depending on the number of PMUs.| 112 113 114## record 115 116 117### Parameters 118 119The **record** command samples the specified application and saves the sampling data to a file (**perf.data** by default). 120 121 122``` 123hiperf record [options] 124Collect performance sampling information. 125``` 126 127| Parameter| Description| 128| -------- | -------- | 129| -a | Samples all processes and threads in the system.| 130| --exclude-hiperf | Leaves the hiperf process not sampled.| 131| -c | Specifies the IDs of the CPUs to sample.| 132| --cpu-limit <_percent_> | Specifies the maximum percentage of CPU resources occupied by the sampling. | 133| -d <sec> | Specifies the sampling duration, in seconds.| 134| -f <freq> | Specifies how often a sampling event is triggered. The default value is 4000 times/second.<br>Note: A higher value indicates heavier CPU load but more sampling data.| 135| --period <_num_> | Specifies the number of occurrence times of an event that triggers a sampling. That is, a sampling is performed once when the event occurs the specified number of times. | 136| -e | Specifies the events to monitor. You can run the **list** command to list all the events supported. **event:u** indicates an event in the user space, and **event:k** indicates an event in the kernel space.| 137| -g | Specifies a group of events to monitor. The events in the same group are monitored by the same PMU.| 138| --no-inherit | Leaves the sub-threads of the target thread or process not monitored.| 139| -p | Specifies the processes to monitor.| 140| -t | Specifies the threads to monitor.| 141| --offcpu | Monitors the CPU scheduling event, which is equivalent to the **--period 1 -e sched:sched_switch** event.| 142| -j <_branch_filter1_>[,_branch_filter2_]... | Monitors the branch prediction events. Branch prediction tries to predict the next instruction to be executed if there are multiple if else conditions. | 143| -s / --call-stack <_fp \\| dwarf[,size]_> | Sets the user stack unwinding mode, which can be **fp** or **dwarf**. If **dwarf** is used, you can specify the size of the user stack to be sampled. The default value is **65528**. | 144| --delay-unwind | Delays the stack unwinding till the sampling is complete.| 145| --disable-unwind | Disables stack unwinding. The user register and stack data is stored in **perf.data** for offline stack unwinding.| 146| --disable-callstack-expend | Disables the unwound call stack information from being combined or extended.| 147| --clockid <_clock type_> | Sets the clock source for the sampling data. The options are **monotonic**, **boottime**, and **realtime**. | 148| --symbol-dir <_dir_> | Specifies the directory of the symbol table. The specified symbol table will be preferentially used in stack unwinding. | 149| -m <_mmap pages_> | Specifies the cache size, in pages. The default value is **1024**. The parameter value must be a power of 2. The value range is [2 - 1024].<br>Note: <br>A higher value indicates a lower event loss rate but higher memory usage. | 150| --app <_package name_> | Specifies the bundle name of the target application to be sampled. The default timeout interval is 10 seconds. If the specified application does not exist, the hiperf process exits after 10 seconds. | 151| --data-limit <_SIZE[K\|M\|G]_> | Specifies the maximum size of the sampling result, in KB, MB, or GB. By default, there is no limit on the size.| 152| -o <_output file name_> | Specifies the name of the sampling result file. It is **/data/local/tmp/perf.data** by default. | 153| -z | Saves the output file in .gzip format.| 154| --verbose | Displays detailed log information during sampling.| 155 156 157### Example 158 159- Sample all processes in the system for 3 seconds and display detailed log information during the sampling process. 160 161 ``` 162 hiperf record -d 3 -a --verbose 163 ``` 164 165- Enable stack unwinding in fp mode. 166 167 ``` 168 hiperf record -s fp -d 3 -a 169 ``` 170 171- Enable stack unwinding in dwarf mode. 172 173 ``` 174 hiperf record -s dwarf -d 3 -a 175 ``` 176 177- Sample offcpu events. 178 179 ``` 180 hiperf record --offcpu -s dwarf -d 3 -a 181 ``` 182 183- Delay stack unwinding. 184 185 ``` 186 hiperf record -d 3 -s dwarf --delay-unwind -a 187 ``` 188 189- Disable stack unwinding. In this case, the stack data is saved to the **perf.data** file. 190 191 ``` 192 hiperf record -d 3 -s dwarf --disable-unwind -a 193 ``` 194 195- Monitor the **com.ohos.launch** application. The hiperf process exits after 10 seconds if the process corresponding to the specified bundle name does not exist. 196 197 ``` 198 hiperf record -d 3 -s dwarf --app com.ohos.launch 199 ``` 200 201- Compress the sampling results. 202 203 ``` 204 hiperf record -z -s dwarf -d 3 -a 205 ``` 206 207 208## report 209 210 211### Parameters 212 213The **report** command displays the sampling data that is captured by using **record**. 214 215 216``` 217hiperf report [option] 218Report sampling information from perf.data. 219``` 220 221| Parameter| Description| 222| -------- | -------- | 223| --symbol-dir <_dir_> | Specifies the directory of the symbol table. | 224| --limit-percent <_number_> | Specifies the minimum percentage of the result to display. The result that is lower than the minimum percentage is not displayed. | 225| -s / --call-stack | Displays detailed call stack information.| 226| --call-stack-limit-percent <_number_> | Specifies the minimum percentage of the call stack to display. The call stack that is lower than the minimum percentage is not displayed. | 227| --proto | Converts the **perf.data** file into the proto format. The default file name is **perf.proto**. | 228| --json | Converts the **perf.data** file into the JSON format. The default file name is **perf.json**. | 229| --branch | Displays the report based on the branch prediction result address instead of the IP address of the call stack.| 230| --<_keys_> <_keyname1_>[,_keyname2_][,...] | Filters and displays reports based on the given keywords. **keys** supports **comms**, **pids**, and **tids**. For example, **--comms hiperf,hilog** displays only the records whose process or thread name is **hiperf** or **hilog**.| 231| --sort <_key1_>[,_key2_][,...] | Sorts and displays information based on specified keywords, such as **pid**, **tid**, and **comm**. Multiple keywords can be specified. | 232| -i <_filename_> | Specifies the sampling data (**perf.data** by default). | 233| -o <_filename_> | Specifies the name of the report to output. | 234 235 236### Example 237 238- Output the report of the sampling data (perf.data by default). 239 240 ``` 241 hiperf report 242 ``` 243 244 Output (example): 245 246 247 ``` 248 Heating count comm pid tid dso func 249 5.68% 15073949 hiperf_example_ 1085 1091 /system/lib/ld-musl-arm.so.1 malloc 250 2.57% 6834119 hiperf_example_ 1085 1091 [kernel.kallsyms] vector_swi 251 2.27% 6013910 hiperf_example_ 1085 1087 /system/lib/ld-musl-arm.so.1 malloc 252 2.19% 5805738 hiperf_example_ 1085 1091 /system/lib/ld-musl-arm.so.1 vfprintf 253 2.09% 5543362 hiperf_example_ 1085 1091 [kernel.kallsyms] ktime_get_ts64 254 report done 255 ``` 256 257- Output the call stack report of the sampling data. 258 259 ``` 260 hiperf report -s 261 ``` 262 263 264 265- Set the symbol table directory. 266 267 ``` 268 hiperf report -s --symbol-dir /data/local/tmp 269 ``` 270 271 272 273- Display only the information containing **libutils.z.so**. 274 275 ``` 276 hiperf report --dsos libuitls.z.so 277 ``` 278 279 280 281- Sort the result by **dso**. 282 283 ``` 284 hiperf report --sort dso 285 ``` 286