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| --offcpu | 跟踪线程何时脱离cpu调度。 | 100| -j | 分支堆栈采样，过滤器支持any、any_call、any_ret、ind_call、ind_jmp、cond、call。 | 101| -s/--callstack | 设置回栈模式。 | 102| --kernel-callchain | 采集内核态堆栈，必须和-s fp/dwarf一起使用。 | 103| --callchain-useronly | 只收集用户态堆栈。 | 104| --delay-unwind | -s dwarf被设置时栈会在录制时展开，设置此选项栈会在录制后展开。 | 105| --disable-unwind | -s dwarf被设置时，默认情况下，录制时堆栈将不会展开。 | 106| --disable-callstack-expand | -s dwarf被设置时，破除64K栈限制，默认情况下合并callstack构建更完整的调用堆栈，可能有时候会不准确。 | 107| --enable-debuginfo-symbolic | -s fp/dwarf被设置时，elf在.gnu_debugdata段的符号会被解析，默认不解析。 | 108| --clockid | 设置采集时钟类型，支持monotonic 和 monotonic_raw。 | 109| --symbol-dir | 在线符号化符号表文件路径。 | 110| -m | mmap页数量，取值范围：2 - 1024，默认1024。 | 111| --app | 采集的应用程序名，以逗号隔开，应用程序必须是debuggable模式，应用程序未启动时会等待20s。 | 112| --chkms | 设置查询的间隔时间，取值范围：1 - 200，默认10。 | 113| --data-limit | 输出数据达到指定大小停止采集，默认无限制。 | 114| -o | 设置输出文件路径。 | 115| -z | 以压缩文件形式输出。 | 116| --restart | 收集应用启动的性能指标信息，如果进程在30秒内未启动，记录将退出。 | 117| --verbose | 输出更详细的报告。 | 118| --control [command]| 采集命令控制参数。命令包括prepare/start/pause/resume/stop。 | 119| --dedup_stack | 删除记录中的重复堆栈，不能和-a一起使用。 | 120| --cmdline-size | 设置/sys/kernel/tracing/saved_cmdlines_size节点的值，取值范围：512 - 4096。 | 121| --report | 采集后回栈报告，不能和-a一起使用。 | 122| --dumpoptions | dump命令选项。 | 123 124``` 125Usage: hiperf record [options] [command [command-args]] 126``` 127 128对指定的PID为267的进程采样10秒，并且使用dwarf回栈。 129 130``` 131hiperf record -p 267 -d 10 -s dwarf 132``` 133 134 135 136 137 138## stat命令 139 140监听指定目标程序，周期性打印性能计数器的值。 141 142**stat命令参数说明** 143 144| 参数 | 参数说明 | 145| -------- | -------- | 146| -h/--help | 帮助命令。 | 147| -a | 采集整机信息，用于评估所有进程、线程。 | 148| -c | 设置采集的cpuid,限制采集哪些cpu数据。 | 149| -d | 采集时长。 | 150| -i | 设置每隔多少ms打印stat信息。 | 151| -e | 采集事件，以逗号隔开。 | 152| -g | 采集事件群组，以逗号隔开。 | 153| --no-inherit | 不采集子进程数据。 | 154| -p | 采集进程ID，以逗号隔开，不能和-a一起使用。 | 155| -t | 采集线程ID，以逗号隔开，不能和-a一起使用。 | 156| --app | 采集的应用程序名，以逗号隔开，应用程序必须是debuggable模式，应用程序未启动时会等待10秒。 | 157| --chkms | 设置查询的间隔时间，取值范围：1 - 200，默认10。 | 158| --per-core | 每个cpu核的打印计数。 | 159| --pre-thread | 每个线程的打印计数。 | 160| --restart | 收集应用启动的性能指标信息，如果进程在30秒内未启动，记录将退出。 | 161| --verbose | 输出更详细的报告。 | 162| --dumpoptions | dump命令选项。 | 163 164``` 165Usage: hiperf stat [options] [command [command-args]] 166``` 167 168下面展示了一个 stats 监听2349进程在CPU0上3秒的性能计数器命令。 169 170``` 171hiperf stat -p 2349 -d 3 -c 0 172``` 173 174## dump命令 175 176此命令主要以不加以处理的方式直接读取perf.data的数据，开发和测试人员可核对其中原始采样数据的正确性。 177 178**dump命令参数说明** 179 180| 参数 | 参数说明 | 181| -------- | -------- | 182| -h/--help | 帮助命令。 | 183| --head | 只输出数据头和属性。 | 184| -d | 只输出数据段。 | 185| -f | 只输出附加功能。 | 186| --syspath | 符号表文件路径。 | 187| -i | 资源文件路径。 | 188| -o | 输出文件路径，未设置则输出到屏幕。 | 189| --elf | 输出elf文件。 | 190| --proto | 输出protobuf格式数据。 | 191| --export | 将用户堆栈数据导出到某个分割文件，使用此命令生成ut数据。 | 192 193``` 194Usage: hiperf dump [option] \<filename\> 195``` 196 197使用dump命令将/data/local/tmp/perf.data文件读取出来，输出到/data/local/tmp/perf.dump文件中。 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 209此命令主要用于展示相关采样数据（从perf.data中读取）并且转换为用户需要的格式（比如Json或者ProtoBuf）。 210 211**report命令参数说明** 212 213| 参数 | 参数说明 | 214| -------- | -------- | 215| -h/--help | 帮助命令。 | 216| --symbol-dir | 符号表文件路径。 | 217| --limit-percent | 只显示前面多少百分比的内容。 | 218| -s | 显示回栈模式。 | 219| --call-stack-limit-percent | 只显示前面多少百分比的堆栈内容。 | 220| -i | 资源文件路径，默认perf.data。 | 221| -o | 输出文件路径，未设置则输出到屏幕。 | 222| --proto | 输出protobuf格式数据。 | 223| --json | 输出json格式数据。 | 224| --diff | 显示-i --diff两个文件的不同。 | 225| --branch | 从地址而不是ip地址显示分支。 | 226| --\<keys\> \<keyname1\>[,keyname2][,...] | 可选关键字：comms、pids、tids、dsos、funcs、from_dsos、from_funcs，例如： --comms hiperf。 | 227| --sort [key1],[key2],[...] | 按关键字排序。 | 228| --hide_count | 报告中不显示数值。 | 229| --dumpoptions | dump命令选项。 | 230 231``` 232Usage: hiperf report [option] \<filename\> 233``` 234 235范例输出普通报告的命令，限制为占比不超过1%。 236 237``` 238hiperf report --limit-percent 1 239``` 240 241 242 243## 脚本 244 245一般用户用脚本执行采样操作，可生成可视化的火焰图。工具可在[developtools_hiperf仓库](https://gitee.com/openharmony/developtools_hiperf/tree/master/script)中获取。 246 2471. 采样。 248 249 由 command_script.py 完成，它是 report 命令的包装脚本。 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 对指定包名采样，包名是 com.ohos.launch。 259 260 ``` 261 python command_script.py -app com.ohos.launch 262 ``` 263 264 对特定进程采样，进程名称是 hdcd。 265 266 ``` 267 python command_script.py -lp hdcd 268 ``` 269 2702. 收集符号表。 271 272 由 recv_binary_cache.py 完成，它主要根据 perf.data 里面记录的相关文件和库以及它们的 buildid， 在用户指定的路径中去寻找对应的 ELF 作为符号表文件用于回栈或者打印函数名等。 273 274 ``` 275 usage: recv_binary_cache.py [-h] [-i PERF_DATA] [-l LOCAL_LIB_DIR [LOCAL_LIB_DIR ...]] 276 ``` 277 278 指定了2个符号表路径的位置。 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 对应的符号表文件会复制到 binary_cache 文件夹，优先检查用户给出的符号表位置，如果没有则复制设备中的文件。 285 2863. 生成火焰图。 287 288 由 make_report.py 完成，将采样后的数据导出为HTML展示页面。 289 290 ``` 291 usage: make_report.py [-h] [-i PERF_DATA] [-r REPORT_HTML] 292 ``` 293 294 产生HTML文件，默认的文件名是 hiperf_report.html。 295 296 ``` 297 python make_report.py -i perf.data 298 ``` 299
