1# hiperf 2 3hiperf为开发人员提供用于调试的命令行工具，用于抓取特定程序或者系统的性能数据，类似内核的perf工具，该工具支持在 Windows/Linux/Mac 等操作系统上运行。 4 5## 环境要求 6 7- 根据hdc命令行工具指导，完成[环境准备](hdc.md#环境准备)。 8 9- 正常连接设备。 10 11## hiperf命令行说明 12 13| 参数 | 参数说明 | 14| -------- | -------- | 15| -h/--help | 帮助命令。 | 16| --debug | 输出debug级别日志。 | 17| --hilog | 日志写入hilog。 | 18| --logpath | 日志路径。 | 19| --logtag | 日志等级。 | 20| --mixlog | 混合日志输出。| 21| --much | 输出尽可能多的日志。 | 22| --nodebug | 无日志输出。 | 23| --verbose | 输出verbose级别日志。 | 24 25## 帮助命令 26 27可用 --help 查看帮助。 28 29``` 30hiperf --help 31``` 32 33 34 35使用如下命令查看子功能的帮助信息。 36 37``` 38hiperf [command] --help 39``` 40 41## list命令 42 43可列出设备上支持的所有事件名称，事件名称用于 stat 和 record 的 -e 和 -g 参数。 44 45**list命令参数说明** 46 47| 参数 | 参数说明 | 48| -------- | -------- | 49| -h/--help | 帮助命令。 | 50| hw | 硬件事件。 | 51| sw | 软件事件。 | 52| tp | tracepoint事件。 | 53| cache | 硬件缓存事件。 | 54| raw | 原始pmu事件。 | 55 56``` 57Usage: hiperf list [event type name] 58``` 59 60使用help命令查询支持的事件类型。 61 62``` 63hiperf list --help 64``` 65 66 67 68下面列出了设备支持的HW事件，并且会提示哪些事件此设备不支持。 69 70``` 71hiperf list hw 72``` 73 74 75 76## record命令 77 78采样指定目标程序，并且将采样数据保存到指定的文件中(默认为/data/local/tmp/perf.data)。 79 80**record命令参数说明** 81 82| 参数 | 参数说明 | 83| -------- | -------- | 84| -h/--help | 帮助命令。 | 85| -a | 采集整机信息，用于评估所有进程、线程。 | 86| --exclude-hiperf | 不采集hiperf本身数据。 | 87| -c | 设置采集的cpuid,只采集这些cpu数据。 | 88| --cpu-limit | 设置采集时cpu最大占比，取值范围：1 - 100，默认25。 | 89| -d | 采集时长。 | 90| -f | 采集频率，默认4000次每秒，不能和--period一起使用。 | 91| --period | 设置采集事件周期，多少事件采集一次，不能和-f一起使用。 | 92| -e | 采集事件，以逗号隔开。 | 93| -g | 采集事件群组，以逗号隔开。 | 94| --no-inherit | 不采集子进程数据。 | 95| -p | 采集进程ID，以逗号隔开，不能和-a一起使用。 | 96| -t | 采集线程ID，以逗号隔开，不能和-a一起使用。 | 97| --exclude-tid | 不采集线程ID，以逗号隔开，不能和-a一起使用。 | 98| --exclude-thread | 不采集线程名，以逗号隔开，不能和-a一起使用。 | 99| --exclude-process | 不采集进程名，以逗号隔开，必须和-a一起使用。 | 100| --offcpu | 跟踪线程何时脱离cpu调度。 | 101| -j | 分支堆栈采样，过滤器支持any、any_call、any_ret、ind_call、ind_jmp、cond、call。 | 102| -s/--callstack | 设置回栈模式。 | 103| --kernel-callchain | 采集内核态堆栈，必须和-s fp/dwarf一起使用。 | 104| --callchain-useronly | 只收集用户态堆栈。 | 105| --delay-unwind | -s dwarf被设置时栈会在录制时展开，设置此选项栈会在录制后展开。 | 106| --disable-unwind | -s dwarf被设置时，默认情况下，录制时堆栈将不会展开。 | 107| --disable-callstack-expand | -s dwarf被设置时，破除64K栈限制，默认情况下合并callstack构建更完整的调用堆栈，可能有时候会不准确。 | 108| --enable-debuginfo-symbolic | -s fp/dwarf被设置时，elf在.gnu_debugdata段的符号会被解析，默认不解析。 | 109| --clockid | 设置采集时钟类型，支持monotonic 和 monotonic_raw。 | 110| --symbol-dir | 在线符号化符号表文件路径。 | 111| -m | mmap页数量，取值范围：2 - 1024，默认1024。 | 112| --app | 采集的应用程序名，以逗号隔开，应用程序必须是debuggable模式，应用程序未启动时会等待20s。 | 113| --chkms | 设置查询的间隔时间，取值范围：1 - 200，默认10。 | 114| --data-limit | 输出数据达到指定大小停止采集，默认无限制。 | 115| -o | 设置输出文件路径。 | 116| -z | 以压缩文件形式输出。 | 117| --restart | 收集应用启动的性能指标信息，如果进程在30秒内未启动，记录将退出。 | 118| --verbose | 输出更详细的报告。 | 119| --control [command]| 采集命令控制参数。命令包括prepare/start/pause/resume/output/stop。 | 120| --dedup_stack | 删除记录中的重复堆栈，不能和-a一起使用。 | 121| --cmdline-size | 设置/sys/kernel/tracing/saved_cmdlines_size节点的值，取值范围：512 - 4096。 | 122| --report | 采集后回栈报告，不能和-a一起使用。 | 123| --backtrack | 采集之前一段时间的数据，必须和--control prepare一起使用。 | 124| --backtrack-sec | 采集之前数据的时长，取值范围5-30，默认10s，必须和--backtrack一起使用。 | 125| --dumpoptions | dump命令选项。 | 126 127``` 128Usage: hiperf record [options] [command [command-args]] 129``` 130 131对指定的PID为267的进程采样10秒，并且使用dwarf回栈。 132 133``` 134hiperf record -p 267 -d 10 -s dwarf 135``` 136 137 138 139 140 141## stat命令 142 143监听指定目标程序，周期性打印性能计数器的值。 144 145**stat命令参数说明** 146 147| 参数 | 参数说明 | 148| -------- | -------- | 149| -h/--help | 帮助命令。 | 150| -a | 采集整机信息，用于评估所有进程、线程。 | 151| -c | 设置采集的cpuid,限制采集哪些cpu数据。 | 152| -d | 采集时长。 | 153| -i | 设置每隔多少ms打印stat信息。 | 154| -e | 采集事件，以逗号隔开。 | 155| -g | 采集事件群组，以逗号隔开。 | 156| --no-inherit | 不采集子进程数据。 | 157| -p | 采集进程ID，以逗号隔开，不能和-a一起使用。 | 158| -t | 采集线程ID，以逗号隔开，不能和-a一起使用。 | 159| --app | 采集的应用程序名，以逗号隔开，应用程序必须是debuggable模式，应用程序未启动时会等待10秒。 | 160| --chkms | 设置查询的间隔时间，取值范围：1 - 200，默认10。 | 161| --per-core | 每个cpu核的打印计数。 | 162| --pre-thread | 每个线程的打印计数。 | 163| --restart | 收集应用启动的性能指标信息，如果进程在30秒内未启动，记录将退出。 | 164| --verbose | 输出更详细的报告。 | 165| --dumpoptions | dump命令选项。 | 166 167``` 168Usage: hiperf stat [options] [command [command-args]] 169``` 170 171下面展示了一个 stats 监听2349进程在CPU0上3秒的性能计数器命令。 172 173``` 174hiperf stat -p 2349 -d 3 -c 0 175``` 176 177## dump命令 178 179此命令主要以不加以处理的方式直接读取perf.data的数据，开发和测试人员可核对其中原始采样数据的正确性。 180 181**dump命令参数说明** 182 183| 参数 | 参数说明 | 184| -------- | -------- | 185| -h/--help | 帮助命令。 | 186| --head | 只输出数据头和属性。 | 187| -d | 只输出数据段。 | 188| -f | 只输出附加功能。 | 189| --syspath | 符号表文件路径。 | 190| -i | 资源文件路径。 | 191| -o | 输出文件路径，未设置则输出到屏幕。 | 192| --elf | 输出elf文件。 | 193| --proto | 输出protobuf格式数据。 | 194| --export | 将用户堆栈数据导出到某个分割文件，使用此命令生成ut数据。 | 195 196``` 197Usage: hiperf dump [option] \<filename\> 198``` 199 200使用dump命令将/data/local/tmp/perf.data文件读取出来，输出到/data/local/tmp/perf.dump文件中。 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 212此命令主要用于展示相关采样数据（从perf.data中读取）并且转换为用户需要的格式（比如Json或者ProtoBuf）。 213 214**report命令参数说明** 215 216| 参数 | 参数说明 | 217| -------- | -------- | 218| -h/--help | 帮助命令。 | 219| --symbol-dir | 符号表文件路径。 | 220| --limit-percent | 只显示前面多少百分比的内容。 | 221| -s | 显示回栈模式。 | 222| --call-stack-limit-percent | 只显示前面多少百分比的堆栈内容。 | 223| -i | 资源文件路径，默认perf.data。 | 224| -o | 输出文件路径，未设置则输出到屏幕。 | 225| --proto | 输出protobuf格式数据。 | 226| --json | 输出json格式数据。 | 227| --diff | 显示-i --diff两个文件的不同。 | 228| --branch | 从地址而不是ip地址显示分支。 | 229| --\<keys\> \<keyname1\>[,keyname2][,...] | 可选关键字：comms、pids、tids、dsos、funcs、from_dsos、from_funcs，例如： --comms hiperf。 | 230| --sort [key1],[key2],[...] | 按关键字排序。 | 231| --hide_count | 报告中不显示数值。 | 232| --dumpoptions | dump命令选项。 | 233 234``` 235Usage: hiperf report [option] \<filename\> 236``` 237 238范例输出普通报告的命令，限制为占比不超过1%。 239 240``` 241hiperf report --limit-percent 1 242``` 243 244 245 246## 脚本 247 248一般用户用脚本执行采样操作，可生成可视化的火焰图。工具可在[developtools_hiperf仓库](https://gitee.com/openharmony/developtools_hiperf/tree/master/script)中获取。 249 2501. 采样。 251 252 由 command_script.py 完成，它是 report 命令的包装脚本。 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 对指定包名采样，包名是 com.ohos.launch。 262 263 ``` 264 python command_script.py -app com.ohos.launch 265 ``` 266 267 对特定进程采样，进程名称是 hdcd。 268 269 ``` 270 python command_script.py -lp hdcd 271 ``` 272 2732. 收集符号表。 274 275 由 recv_binary_cache.py 完成，它主要根据 perf.data 里面记录的相关文件和库以及它们的 buildid， 在用户指定的路径中去寻找对应的 ELF 作为符号表文件用于回栈或者打印函数名等。 276 277 ``` 278 usage: recv_binary_cache.py [-h] [-i PERF_DATA] [-l LOCAL_LIB_DIR [LOCAL_LIB_DIR ...]] 279 ``` 280 281 指定了2个符号表路径的位置。 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 对应的符号表文件会复制到 binary_cache 文件夹，优先检查用户给出的符号表位置，如果没有则复制设备中的文件。 288 2893. 生成火焰图。 290 291 由 make_report.py 完成，将采样后的数据导出为HTML展示页面。 292 293 ``` 294 usage: make_report.py [-h] [-i PERF_DATA] [-r REPORT_HTML] 295 ``` 296 297 产生HTML文件，默认的文件名是 hiperf_report.html。 298 299 ``` 300 python make_report.py -i perf.data 301 ``` 302
