Simpleperf 命令和选项参考

本页面介绍最常用的 Simpleperf 命令和选项。 您可使用 simpleperf --help 命令查看选项和子命令的完整列表。

语法

simpleperf [--version] [--help] command [command options]

全局选项

全局选项 说明
--help 显示用法帮助。
--log severity 设置日志记录的最低严重程度。 有效的严重程度值包括:
  • verbose
  • debug
  • warning
  • info
  • error
  • fatal
默认设置为 info
--version 显示版本信息。

关键命令和选项

命令和选项 说明
list [hw|sw|cache|tracepoint] 列出本计算机上所有可用的性能事件。
record [options] [command [command-args]] 记录一段时间内已分析进程的样本。 如果您在参数中指定 command,Simpleperf 将仅收集运行 command 的进程的采样信息。 之后,其会将采样数据写入 perf.data 文件。 您可使用 -a/-p/-t 记录选项来更改采样目标。
  • -a:从所有 CPU 收集整个系统内的相关信息。
  • -b:启用发生分支堆栈采样。 此操作与使用“'-j any”选项的结果相同。 请参阅此选项的相关文档,了解更多信息。
  • -c :设置事件采样周期。 也就是说,在发生 count 事件时,记录一个样本。 此选项不可与 -f/-F 选项搭配使用。 对于跟踪点事件,默认选项为 -c 1
  • --call-graph fp | dwarf[, dump_stack_size]:启用调用关系图记录。 您可使用帧指针或 dwarf 调试帧作为收集方法,收集用于显示调用关系图的信息。 默认设置为 dwarf,65528
  • --cpu cpu_item1,cpu_item2,...:仅在选定的 CPU 上采集样本。 例如,您可指定 [cpu_item] 为 CPU 编号 1,或 CPU 范围 0-3。
  • --dump-symbolsperf.data 文件中的转储符号。 默认情况下,perf.data 不包含样本的符号信息。 报告环境中没有符号信息时,可使用此选项。
  • --duration time_in_sec:监控线程 time_in_sec 秒,而非运行 command。 其中 time_in_sec 可以是任何正浮点数。
  • -e event1[:modifier1],event2[:modifier2],... : 选择要采样的事件列表。 使用 `simpleperf list` 查找所有可能的事件名称。 您可以添加修饰符来定义事件的监控方式。 可能的修饰符包括:
    • u:仅监控用户空间事件
    • k:仅监控内核空间事件
  • -f freq:设置事件采样频率。 这表示按每秒最大 freq 样本进行记录。 对于非跟踪点事件,默认选项为 -f 4000
  • -F freq:与“-f freq”相同。
  • -g:与“--call-graph dwarf”相同。
  • --group event1[:modifier],event2[:modifier2], ...:与 -e 选项类似,但在同一 --group 选项中指定的事件可按组进行监控,并安排在同一时间进出。
  • -j branch_filter1,branch_filter2,...:启用发生分支堆栈采样。 每个样本捕获一系列连续的发生分支。 您可以指定以下过滤器:
    • any:任何类型的分支。
    • any_call:任何函数调用或系统调用。
    • any_ret:任何函数返回或系统调用返回。
    • ind_call:任何间接分支。
    • u:仅当分支目标处于用户级别时。
    • k:仅当分支目标处于内核中时。 此选项要求具有 anyany_callany_retind_call 中至少一个分支类型。
  • -m mmap_pages:设置用于从内核接收样本数据的缓冲区大小。 该值应是 2 的幂。如果未设置,将使用最大可能值 <=1024
  • --no-dump-kernel-symbols:不要转储 perf.data 中的内核符号。 默认情况下,Simpleperf 将在必要时转储内核符号。
  • --no-inherit:不要记录已创建的子线程或进程。
  • --no-unwind:默认情况下,如果使用 `--call-graph dwarf` 选项,则用户的堆栈将回退。 使用此选项以禁用用户堆栈回退。
  • -o record_file_name:设置记录文件的名称;默认名称为 perf.data
  • -p pid1,pid2,...:记录现有进程中的事件。 与 -a 互斥。
  • --post-unwind:默认情况下,如果使用 `--call-graph dwarf` 选项,则用户的堆栈将在记录时回退。 记录可能会丢失,因为堆栈回退会很耗时。 使用此选项在记录后回退用户的堆栈。
  • --start_profiling_fd fd_no:开始分析后,将“STARTED”写入 fd_no,然后结束 fd_no
  • --symfs dir:查找包含与此目录相关的符号的文件。 使用此选项提供包含符号表和调试信息的文件,此类信息由 --dump-symbols-g 使用。
  • -t tid1,tid2,...:记录现有线程中的事件。 与 -a 互斥。
report [options] 读取 perf.data 文件(由 simpleperf record 创建),并显示报告,表明花费时间的地方。
  • -b:使用已采样的发生分支中的分支目的位置地址,而非指令地址。 仅对使用 -b/-j 选项记录的 perf.data 有效。
  • --brief-callgraph:打印简要的调用关系图。
  • --children:打印出现在调用链中的累积开销。
  • --comms comm1,comm2,...:仅报告选定的命令。
  • --dsos dso1,dso2,...:仅报告选定的动态共享对象。
  • -g [callee|caller]:打印调用关系图。 如果使用被调用方模式,调用关系图将显示函数如何被其他方调用。 否则,调用关系图将显示函数如何调用其他方。 默认模式是 caller
  • -i file:指定记录文件的路径;默认路径为 perf.data
  • --kallsyms file:设置文件以读取内核符号。
  • --max-stack frames:设置打印调用关系图时显示的最大堆栈帧数。
  • -n:打印各项的样本数。
  • --no-demangle:不要解码符号名称。
  • --no-show-ip:对于未知符号,不要在文件中显示 vaddr。
  • -o report_file_name:设置报告文件名,默认文件名是 stdout
  • --percent-limit percent:设置打印调用关系图时显示的最小百分比。
  • --pids pid1,pid2,...:仅报告选定的进程 ID。
  • --raw-period:报告周期计数,而不是周期百分比。
  • --sort key1,key2,...:选择用于排序和打印报告的键。 您指定键的顺序将决定用于排序和打印报告的键顺序。 可能的键包括:
    • pid:进程 ID。
    • tid:线程 ID。
    • comm:线程名称(可在线程生命周期中进行更改)。
    • dso:共享库。
    • symbol:共享库中的函数名称。
    • vaddr_in_file:共享库中的虚拟地址。

    键仅可与 -b 选项搭配使用:

    • dso_from:分支起始共享库。
    • dso_to:分支目的地共享库。
    • symbol_from:分支起始函数名称。
    • symbol_to:分支目的地函数名称。

    默认排序键为:commpidtiddsosymbol

  • --symbols symbol1;symbol2;...:仅报告选定的符号。
  • --symfs dir:查找包含与此目录相关的符号的文件。
  • --tids tid1,tid2,...:仅报告选定的线程 ID。
  • --vmlinux file:解析来自 file 的内核符号。
stat [options] [command [command-args]] 获取一段时间内已分析进程中发生的事件数摘要。 如果您在参数中指定 command,Simpleperf 将仅收集运行 的进程的性能计数器信息。 您可使用 -a/-p/-t 选项来更改计数器信息收集的目标。
  • -a:收集整个系统的信息。
  • --cpu cpu_item1,cpu_item2,...:仅收集选定的 CPU 上的信息。 例如,cpu_item 可以是 CPU 编号 1,或 CPU 范围 0-3。
  • --csv:以逗号分隔的形式编写报告。
  • --duration time_in_sec:监控 time_in_sec 秒,而非运行 command。 在此处,time_in_sec 可以是任何正浮点数。
  • --interval time_in_ms:打印每 time_in_ms 毫秒的统计数据。 在此处,time_in_ms 可以是任何正浮点数。
  • -e event1[:modifier1],event2[:modifier2],... :选择要计数的事件列表。 使用 simpleperf list 查找所有可能的事件名称。 可以添加修饰符来定义事件的监控方式。 可能的修饰符有:
    • u:仅监控用户空间事件。
    • k:仅监控内核空间事件。
  • --group event1[:modifier],event2[:modifier2] ,...:与 -e 选项相似。 在同一 --group 选项中指定的事件可按组进行监控,并安排在同一时间进出。
  • --no-inherit:不要统计已创建的子线程或进程。
  • -o output_filename:将报告写入 output_filename,而非标准输出。
  • -p pid1,pid2,...:统计现有进程中的事件。 与 -a 互斥。
  • -t tid1,tid2,...:统计现有线程中的事件。 与 -a 互斥。
  • --verbose:以详细模式显示结果。

Python 脚本

Simpleperf 工具包含数个位于 ndk-location/simpleperf/ 目录中的 Python 脚本,可帮助简化 Android 设备上性能数据的记录和报告过程。 您可在连接至目标 Android 设备的主机开发计算机上运行这些脚本。 要查看如何使用此类脚本的示例,请参考 GitHub 上的 Simpleperf 演示样本。

脚本 说明
annotate.py 根据从 perf.data 获得的分析数据对源文件进行注释。 您可通过 annotate.config 文件配置此脚本的行为。
app_profiler.py 分析 Android 应用。 此脚本会准备好分析环境,将 Simpleperf 可执行文件推送至 Android 设备,在设备上生成 perf.data 文件,然后将生成的文件返回至主机。 您可通过 app_profiler.config 文件配置此脚本的行为。
binary_cache_builder.py 从 Android 设备提取库。 此脚本由 app_profiler.py 使用。
pprof_proto_generator.py 将分析数据转换为 pprof 使用的格式。
report.py 发布图形界面以报告分析结果。
report_sample.py 生成 flamegraph 输出。
simpleperf_report_lib.py 提供用于解析分析数据的 Python 界面。 您可使用此脚本将 perf.data 中的分析数据转换为其他格式。 Simpleperf 中提供的 report_sample.py 显示此转换操作的示例。