1# hiperf 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @leiguangyu--> 6<!--Designer: @Maplestroy--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10hiperf是一款集成多种性能分析功能的命令行工具，可用于分析系统性能瓶颈、定位软件热点及优化代码效率，支持采集和统计程序运行时的性能数据。 11 12 13开发者可优先使用[Deveco Studio](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-insight-session-time)或[SmartPerf](https://gitee.com/openharmony/developtools_smartperf_host/blob/master/smartperf_host/ide/src/doc/md/quickstart_hiperf.md)等图形前端工具采集函数的调用栈，获取调用栈上各层函数的执行时间，通过泳道图等方式查看调用链信息进而进行性能分析。若需要指定采集的事件、采样周期、采集时长、CPU核数等选项，可以单独使用 hiperf 命令行工具。采样数据 perf.data 文件可以使用SmartPerf工具打开并以可视化的火焰图进行展示。 14 15 16本文档详细说明了hiperf命令行工具的使用方法，帮助开发者借助该工具进行详细的性能分析。 17 18 19## 环境要求 20 21- 根据hdc命令行工具指导，完成[环境准备](hdc.md#环境准备)。 22 23- 确保设备已连接，然后执行hdc shell。 24 25 26## 命令行说明 27 28使用hiperf --help可以列出hiperf所有的命令，包括dump、list、record、report、stat等。 29 30```shell 31$ hiperf --help 32``` 33 34 35| 命令 | 命令说明 | 36| -------- | -------- | 37| --hilog | 设置该选项后，程序运行过程中产生的日志会被记录到hilog中。 | 38| --logpath | 设置日志文件的保存路径，现支持用户将输出文件路径设定为"/data/local/tmp/"目录，并允许用户自定义文件名称。 | 39| --logtag | 开启指定功能的日志。 | 40| --debug | 记录debug级别的日志。 | 41| --verbose | 记录verbose级别的日志。 | 42| --much | 记录much级别的日志。 | 43| --nodebug | 关闭所有日志的记录。 | 44| --mixlog | 日志输出到命令行界面。 | 45| -h/--help | 帮助命令。 | 46| [dump](#dump命令) | 将性能数据文件（如perf.data）转换为内容可读的格式。 | 47| [list](#list命令) | 展示当前系统支持的性能事件类型。 | 48| [record](#record命令) | 收集性能数据。 | 49| [report](#report命令) | 将性能数据进行可视化转换。 | 50| [stat](#stat命令) | 统计性能数据。 | 51 52 53**使用样例**： 54 55 56```shell 57$ hiperf --help 58Usage: hiperf [options] command [args for command] 59options: 60 --debug show debug log, usage format: --debug [command] [args] 61 --help show help 62 --hilog use hilog not file to record log 63 --logpath log file name full path, usage format: --logpath [filepath] [command] [args] 64 --logtag enable log level for HILOG_TAG, usage format: --logtag <tag>[:level][,<tag>[:level]] [command] [args] 65 tag: Dump, Report, Record, Stat... level: D, V, M... 66 example: hiperf --verbose --logtag Record:D [command] [args] 67 --mixlog mix the log in output, usage format: --mixlog [command] [args] 68 --much show extremely much debug log, usage format: --much [command] [args] 69 --nodebug disable debug log, usage format: --nodebug [command] [args] 70 --verbose show debug log, usage format: --verbose [command] [args] 71 -h show help 72command: 73 dump: Dump content of a perf data file, like perf.data 74 help: Show more help information for hiperf 75 list: List the supported event types. 76 record: Collect performance sample information 77 report: report sampling information from perf.data format file 78 stat: Collect performance counter information 79 80See 'hiperf help [command]' for more information on a specific command. 81``` 82 83 84## 常用命令 85 86 87### 性能数据采样记录 88 89 901. 对进程ID为1234的进程采样10秒，设置回栈方式为fp（栈指针），采样频率1000次/秒，事件类型为hw-cpu-cycles和hw-instructions，采样文件保存至/data/local/tmp/perf.data。 91 92 93```shell 94$ hiperf record -p 1234 -s fp -f 1000 -d 10 -e hw-cpu-cycles,hw-instructions -o /data/local/tmp/perf.data 95Profiling duration is 10.000 seconds. 96Start Profiling... 97Timeout exit (total 10335 ms) 98Process and Saving data... 99Hiperf is not running as root mode. Do not need load kernel syms 100[ hiperf record: Captured 3.014 MB perf data. ] 101[ Sample records: 1293, Non sample records: 855 ] 102[ Sample lost: 0, Non sample lost: 0 ] 103``` 104 105 106采集的数据将保存为二进制格式的perf.data文件，包含性能分析所需的采样数据、进程信息、符号表及函数调用等内容。利用火焰图脚本可将采样数据转换为可视化火焰图，以此分析系统性能瓶颈、定位软件热点并优化代码效率。 107 108 1092. 对应用com.example.insight_test_stage进行采样，采样时长为10s，回栈方式设置为dwarf（调试信息表），采样周期为1000，事件类型为hw-cpu-cycles和hw-instructions，使用默认保存路径。 110 111 112```shell 113$ hiperf record --app com.example.insight_test_stage -d 10 -s dwarf --period 1000 -e hw-cpu-cycles,hw-instructions 114Profiling duration is 10.000 seconds. 115Start Profiling... 116Timeout exit (total 10000 ms) 117Process and Saving data... 118Hiperf is not running as root mode. Do not need load kernel syms 119[ hiperf record: Captured 0.296 MB perf data. ] 120[ Sample records: 0, Non sample records: 2640 ] 121[ Sample lost: 0, Non sample lost: 0 ] 122``` 123 124 125采集的数据会被保存至默认路径/data/local/tmp/perf.data中。 126 127 128### 性能数据统计 129 130 1311. 对进程ID为1745，1910的进程进行计数，计数时长为10s。 132 133 134``` 135$ hiperf stat -d 10 -p 1745,1910 136Profiling duration is 10.000 seconds. 137Start Profiling... 138Timeout exit (total 10000 ms) 139 count name | comment | coverage 140 148,450 hw-branch-instructions | 26.404 M/sec | (100%) 141 49,833 hw-branch-misses | 33.568878 miss rate | (100%) 142 8,986,523 hw-cpu-cycles | 1.598409 GHz | (100%) 143 1,283,596 hw-instructions | 7.001053 cycles per instruction | (100%) 144 63 sw-context-switches | 11.206 K/sec | (100%) 145 0 sw-page-faults | 0.000 /sec | (100%) 146 5,622,169 sw-task-clock | 0.000562 cpus used | (100%) 147``` 148 149 1502. 对进程ID为1745和1910的进程进行计数，计数时长为10秒，事件类型为hw-cpu-cycles、hw-instructions、sw-task-clock，指定打印信息的时间间隔为3000ms。 151 152 153``` 154$ hiperf stat -d 10 -p 1745,1910 -e hw-cpu-cycles,hw-instructions,sw-task-clock -i 3000 155Profiling duration is 10.000 seconds. 156Start Profiling... 157Report at 3000 ms (6999 ms left): 158 count name | comment | coverage 159 2,534,675 hw-cpu-cycles | 1.717114 GHz | (100%) 160 324,279 hw-instructions | 7.816340 cycles per instruction | (100%) 161 1,476,125 sw-task-clock | 0.000492 cpus used | (100%) 162Report at 6000 ms (3999 ms left): 163 count name | comment | coverage 164 5,112,570 hw-cpu-cycles | 1.724259 GHz | (100%) 165 648,303 hw-instructions | 7.886081 cycles per instruction | (100%) 166 2,965,083 sw-task-clock | 0.000494 cpus used | (100%) 167Report at 9000 ms (999 ms left): 168 count name | comment | coverage 169 7,870,422 hw-cpu-cycles | 1.724897 GHz | (100%) 170 994,407 hw-instructions | 7.914689 cycles per instruction | (100%) 171 4,562,835 sw-task-clock | 0.000507 cpus used | (100%) 172Timeout exit (total 10000 ms) 173``` 174 175 1762.3 对进程ID为1910的进程进行计数，计数时长为3s，事件类型为hw-cpu-cycles，hw-instructions，并打印详细的信息。 177 178 179``` 180$ hiperf stat -d 3 -p 1910 -e hw-cpu-cycles,hw-instructions --verbose 181Profiling duration is 3.000 seconds. 182Start Profiling... 183Timeout exit (total 3000 ms) 184hw-cpu-cycles id:1342(c-1:p1910) timeEnabled:133583 timeRunning:133583 value:255740 185hw-cpu-cycles id:1343(c-1:p1988) timeEnabled:0 timeRunning:0 value:0 186hw-cpu-cycles id:1344(c-1:p1989) timeEnabled:0 timeRunning:0 value:0 187hw-cpu-cycles id:1345(c-1:p1990) timeEnabled:187833 timeRunning:187833 value:331425 188... 189hw-instructions id:1375(c-1:p1910) timeEnabled:133583 timeRunning:133583 value:36485 190hw-instructions id:1376(c-1:p1988) timeEnabled:0 timeRunning:0 value:0 191hw-instructions id:1377(c-1:p1989) timeEnabled:0 timeRunning:0 value:0 192hw-instructions id:1378(c-1:p1990) timeEnabled:187833 timeRunning:187833 value:47816 193... 194 count name | comment | coverage 195 669,850 hw-cpu-cycles | | (100%) 196 94,903 hw-instructions | 7.058259 cycles per instruction | (100%) 197``` 198 199 200## debug应用 201 202 203> **注意：** 204> 205> hiperf record/stat -p [pid] 命令采集的进程应为“使用调试证书签名的应用”。 206> 207> 确认命令指定的应用是否为可调试应用，可执行hdc shell "bm dump -n bundlename | grep appProvisionType"查询，预期返回信息为"appProvisionType": "debug"。 208> 209> 以包名com.example.myapplication为例，可执行如下命令查询： 210> 211> ```shell 212> hdc shell "bm dump -n com.example.myapplication | grep appProvisionType" 213> ``` 214> 215> 如包名对应的应用是可调试应用，预期返回信息如下： 216> 217> ```shell 218> "appProvisionType": "debug", 219> ``` 220> 221> 构建可调试应用需要使用调试证书进行签名，申请调试证书及签名可参考：[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-debugcert-0000001914263178)。 222 223 224## list命令 225 226展示当前系统支持的性能事件类型，事件类型可用于record和stat命令-e选项的参数。 227 228**参数**： 229 230| 参数名 | 说明 | 231| -------- | -------- | 232| -h/--help | 帮助命令。 | 233| hw | 硬件事件。<br/>当前支持事件：<br/>- hw-cpu-cycles<br/>- hw-instructions<br/>- hw-cache-references<br/>- hw-cache-misses<br/>- hw-branch-instructions<br/>- hw-branch-misses<br/>- hw-bus-cycles<br/>- hw-stalled-cycles-frontend<br/>- hw-stalled-cycles-backend | 234| sw | 软件事件。 | 235| tp | tracepoint事件。 | 236| cache | 硬件缓存事件。 | 237| raw | 原始性能监测单元（PMU）事件。 | 238 239**命令行示例**： 240 241``` 242Usage: hiperf list [event type name] 243``` 244 245查询支持的硬件事件类型。 246 247 248``` 249$ hiperf list hw 250event not support hw-ref-cpu-cycles 251 252Supported events for hardware: 253 hw-cpu-cycles 254 hw-instructions 255 hw-cache-references 256 hw-cache-misses 257 hw-branch-instructions 258 hw-branch-misses 259 hw-bus-cycles 260 hw-stalled-cycles-frontend 261 hw-stalled-cycles-backend 262``` 263 264 265## record命令 266 267采集指定进程或指定应用的性能数据，包括CPU周期、指令数、函数调用等信息，并且将采样数据保存到指定的文件中（默认为/data/local/tmp/perf.data）。 268 269**record命令参数说明** 270 271<!--RP1--> 272| 参数 | 参数说明 | 273| -------- | -------- | 274| -h/--help | 帮助命令。 | 275| -c | 设置采集的CPU ID，只采集对应的CPU数据。 | 276| --cpu-limit | 设置采集时CPU最大占比，取值范围：1 - 100，默认25。 | 277| -d | 采集时长，单位为s。该参数不能和--control一起使用。 | 278| -f | 采集频率，默认4000次/s。该参数不能和--period一起使用。 | 279| --period | 设置采集事件周期，多少事件采集一次。该参数不能和-f一起使用。 | 280| -e | 采集事件，支持对多种事件进行采集，多个事件之间以逗号隔开。可通过list命令获取当前支持的事件类型。 | 281| -g | 采集事件群组，以逗号隔开。 | 282| --no-inherit | 不采集子进程数据。 | 283| -p | 采集进程ID，支持对多个进程进行采样，多个进程号之间以逗号隔开。该参数不能和-a一起使用。 | 284| -t | 采集线程ID，支持对多个线程进行采样，多个线程号之间以逗号隔开。该参数不能和-a一起使用。 | 285| --exclude-tid | 不采集线程ID，通过线程ID排除特定线程的采样。多个线程号之间以逗号隔开。该参数不能和-a一起使用。 | 286| --exclude-thread | 不采集线程名，通过线程名排除特定线程的采样。多个线程名之间以逗号隔开。该参数不能和-a一起使用。 | 287| --offcpu | 跟踪线程何时脱离CPU调度。 | 288| -j | 分支堆栈采样，过滤器支持any、any_call、any_ret、ind_call、ind_jmp、cond、call。 | 289| -s/--callstack | 设置回栈模式，可设置为fp(栈指针)、dwarf(调试信息表)两种模式中的一种，默认是fp模式。 | 290| --kernel-callchain | 采集内核态堆栈，该参数必须和-s参数一起使用。 | 291| --callchain-useronly | 仅收集用户态堆栈。 | 292| --delay-unwind | 回栈模式被设置为dwarf时，设置此选项后调用栈会在录制后展开。 | 293| --disable-unwind | 回栈模式被设置为dwarf时，设置此选项后调用栈将不会在录制后展开。 | 294| --disable-callstack-expand | 回栈模式被设置为dwarf时，设置此选项后会用缓存的线程栈来对调用栈进行合并。 | 295| --enable-debuginfo-symbolic | -s fp/dwarf被设置时，elf在.gnu_debugdata段的符号会被解析，默认不解析。 | 296| --clockid | 设置采集时钟类型，支 monotonic和monotonic_raw，部分事件支持boottime、realtime和 clock_tai时钟类型。 | 297| --symbol-dir | 符号表文件路径，用于采集过程中进行符号化操作。 | 298| -m | mmap页数量，取值范围：2 - 1024，默认1024。 | 299| --app | 采集的应用程序名，以逗号隔开。应用程序必须是启动状态，应用程序未启动时会等待20s，20s内应用程序未启动，命令会自动结束。该参数不能和-a一起使用。 | 300| --chkms | 设置查询的间隔时间，单位为ms。取值范围：1 - 200，默认10。 | 301| --data-limit | 输出数据达到指定大小停止采集，默认无限制。 | 302| -o | 设置输出文件路径，现支持用户将输出文件路径设定为"/data/local/tmp/"目录，并允许用户自定义文件名称。 | 303| -z | 以.gz的压缩文件形式输出。 | 304| --restart | 收集应用启动的性能指标信息，如果进程在30秒内未启动，采集操作将结束。 | 305| --verbose | 输出更详细的报告。 | 306| --control [command] | 采集操作启停控制参数。命令包括prepare/start/pause/resume/output/stop。该参数不能和-d一起使用。 | 307| --dedup_stack | 删除记录中的重复堆栈。 | 308| --cmdline-size | 设置/sys/kernel/tracing/saved_cmdlines_size节点的值，单位byte，取值范围：512 - 4096。 | 309| --report | 采集后回栈报告。 | 310| --backtrack | 采集之前一段时间的数据，该参数必须和--control prepare一起使用。 | 311| --backtrack-sec | 采集之前数据的时长，单位为秒。取值范围：5 - 30，默认10。该参数必须和--backtrack一起使用。 | 312| --dumpoptions | 展示采集参数的详细信息。 | 313| -a | 采集整机的性能数据。 | 314| --exclude-hiperf | 不采集hiperf进程自身的性能数据，该可选参数必须和-a一起使用。 | 315| --exclude-process | 不采集的进程名，该参数必须和-a一起使用。 | 316<!--RP1End--> 317 318**命令行示例**： 319 320``` 321Usage: hiperf record [options] [command [command-args]] 322``` 323 324对指定的pid为267的进程采样10秒，并使用dwarf回栈。 325 326``` 327$ hiperf record -p 267 -d 10 -s dwarf 328``` 329 330 331## stat命令 332 333监听用户指定的目标程序，周期性打印性能计数器的值。 334 335**stat命令参数说明** 336 337<!--RP2--> 338| 参数 | 参数说明 | 339| -------- | -------- | 340| -h/--help | 帮助命令。 | 341| -c | 设置采集的CPU ID，只采集对应的CPU数据。 | 342| -d | 采集时长，单位为s。该参数不能和--control一起使用。 | 343| -i | 设置打印stat信息的间隔时长，单位ms。 | 344| -e | 采集事件，支持采集多种事件，多个事件之间以逗号隔开。 | 345| -g | 采集事件群组，以逗号隔开。可通过list命令获取当前支持的事件类型。 | 346| --no-inherit | 不采集子进程数据。 | 347| -p | 采集进程ID，支持对多个进程进行采样，多个进程号之间以逗号隔开。该参数不能和-a一起使用。 | 348| -t | 采集线程ID，支持对多个线程进行采样，多个线程号之间以逗号隔开。该参数不能和-a一起使用。 | 349| --app | 采集的应用程序名，以逗号隔开。应用程序必须是启动状态，应用程序未启动时会等待20s，20s内应用程序未启动，命令会自动结束。该参数不能和-a一起使用。 | 350| --chkms | 设置查询的间隔时间，单位为毫秒，取值范围：1 - 200，默认10。 | 351| --per-core | 每个CPU核的打印计数。 | 352| --pre-thread | 每个线程的打印计数。 | 353| --restart | 收集应用启动的性能指标信息，如果进程在30秒内未启动，记录将退出。该参数必须和--app一起使用。 | 354| --verbose | 输出详细的信息。 | 355| --dumpoptions | 展示当前列表里所有选项的详细信息。 | 356| --control [command] | 采集操作启停控制参数。命令包括prepare/start/stop。该参数不能和-d一起使用。<br/>**说明**：从API version 20开始，支持该参数。 | 357| -o | 设置输出文件路径，现支持用户将输出文件路径设定为"/data/local/tmp/"目录，并允许用户自定义文件名称。该参数必须和--control prepare一起使用，不能和--control一起使用。<br/>**说明**：从API version 20开始，支持该参数。 | 358| -a | 统计整机的性能数据。 | 359 360**命令行示例**： 361 362``` 363hiperf stat [options] [command [command-args]] 364``` 365 366使用stat命令监听进程号为2349的进程在CPU 0上运行3秒的性能数据。 367 368``` 369$ hiperf stat -p 1745 -d 3 -c 0 370``` 371 372 373## dump命令 374 375此命令用于将不同格式的性能数据文件（如perf.data）转换为内容易读的明文，便于开发和测试人员核对其中原始采样数据的正确性。 376 377**dump命令参数说明** 378 379| 参数 | 参数说明 | 380| -------- | -------- | 381| -h/--help | 帮助命令。 | 382| --head | 仅输出数据头和属性。 | 383| -d | 仅输出数据段。 | 384| -f | 仅输出附加功能。 | 385| --sympath | 符号表文件路径。 | 386| -i | 采样文件的路径。 | 387| -o | 设置输出文件路径，现支持用户将输出文件路径设定为"/data/local/tmp/"目录，并允许用户自定义文件名称。若未设置该参数，数据将会输出到命令行界面。 | 388| --elf | 将elf格式的文件转换成内容可读的明文。 | 389| --proto | 将proto格式的文件转换成内容可读的明文。 | 390| --export | 将用户栈数据分割成多个文件。 | 391 392**命令行示例**： 393 394``` 395Usage: hiperf dump [option] \<filename\> 396``` 397 398使用dump命令将/data/local/tmp/perf.data文件读取出来，并输出到/data/local/tmp/perf.dump文件中。 399 400``` 401$ hiperf dump -i /data/local/tmp/perf.data -o /data/local/tmp/perf.dump 402``` 403 404 405## report命令 406 407此命令主要用于将采样数据（perf.data）转换为用户指定的格式（例如Json或者ProtoBuf)，并可以将属于相同进程、线程、函数的样本分组到同一样本条目中，根据样本条目的事件计数对样本条目进行排序，并以报告的形式进行展示。 408 409**report命令参数说明** 410 411| 参数 | 参数说明 | 412| -------- | -------- | 413| -h/--help | 帮助命令。 | 414| --symbol-dir | 符号表文件路径。 | 415| --limit-percent | 筛选性能占比不低于指定百分比（取值范围 1 - 100）的性能数据，仅在报告中保留并展示符合该阈值条件的数据条目。 | 416| -s | 显示回栈模式。 | 417| --call-stack-limit-percent | 展示指定比例的堆栈内容，取值范围：1 - 100。 | 418| -i | 资源文件路径，默认perf.data。 | 419| -o | 设置输出文件路径，现支持用户将输出文件路径设定为"/data/local/tmp/"目录，并允许用户自定义文件名称。若未设置该参数，数据将会输出到命令行界面。 | 420| --proto | 输出protobuf格式数据。 | 421| --json | 输出json格式数据。 | 422| --diff | 显示源文件与转换后文件的差别。不能与--proto、--json、-s参数一起使用。 | 423| --branch | 根据函数地址显示分支。 | 424| --<keys> <keyname1>[,keyname2][,...] | 可选关键字：comms、pids、tids、dsos、funcs、from_dsos、from_funcs，例如： --comms hiperf。 | 425| --sort [key1],[key2],[...] | 按关键字排序。 | 426| --hide_count | 报告中不显示数值。 | 427| --dumpoptions | 展示当前列表里所有选项的详细信息。 | 428 429**命令行示例**： 430 431``` 432Usage: hiperf report [option] \<filename\> 433``` 434 435从采样文件（perf.data）中提取对性能影响较大（占比≥1%）的关键数据，并以报告的形式进行展示。 436``` 437$ hiperf report -i /data/local/tmp/perf.data --limit-percent 1 438``` 439