PERFETTO(1)
名称
perfetto - 捕获 traces
描述
本节介绍如何使用 perfetto 命令行二进制文件捕获 traces。示例以通过 ADB 连接的 Android 设备给出。
perfetto 有两种配置 Tracing Session 的模式(即收集什么以及如何收集):
轻量级模式
:所有配置选项都作为命令行标志提供,但可用的数据源限制为 ftrace 和 atrace。此模式类似于
systrace。
普通模式
:配置在协议缓冲区中指定。这允许对收集的 traces 进行完全自定义。
常规选项
以下列出了在任一模式下使用 perfetto 时的可用选项。
-d,--background: Perfetto 立即退出命令行界面并在后台继续采集你的 trace。
-D,--background-wait: 类似于
--background,但会等待(最多 30 秒)所有数据源启动完成后再退出。
--notify-fdFD:类似于
--background-wait,但不是守护进程化并在退出前等待,而是写入一个状态字节并关闭给定的文件描述符。成功时写入0,超时/错误时写入非零值。Windows 上不支持。
-o,--outOUT_FILE:指定输出 trace 文件的所需路径,或
-用于 stdout。perfetto将输出写入上述标志描述的文件。 输出格式符合 AOSPtrace.proto中定义的格式。
--no-clobber:不覆盖已存在的输出文件。
--cloneTSID:创建由 session ID(TSID)标识的现有 tracing session 的只读克隆(参见
--query)。
--clone-by-nameNAME:创建由
unique_session_name标识的现有 tracing session 的只读克隆。
--clone-for-bugreport:只能与
--clone或--clone-by-name一起使用。在克隆的 session 上禁用trace_filter。
--add-attributekey[=value]::添加一个 trace attribute,即描述 trace 的键值对。如果省略
=value,值为空字符串。属性在 Trace Processor 的metadata表中显示为trace_attribute.<key>行。
--version:打印
perfetto版本字符串并退出。
--dropboxTAG:已弃用。通过 DropBoxManager API 使用你指定的标签上传你的 trace。仅限 Android。请改用
--upload。
--upload:将 trace 输出上传到
TraceConfig(android_report_config)中配置的 Android 框架报告路径。仅限 Android。
--alert-idID:Statsd 元数据。触发此 trace 的 alert 的 ID。
--config-idID:Statsd 元数据。触发配置的 ID。
--config-uidUID:Statsd 元数据。注册触发配置的应用的 UID。
--subscription-idID:Statsd 元数据。触发此 trace 的 subscription 的 ID。
--save-for-bugreport:如果有一个
bugreport_score > 0的 trace 正在运行,则将其保存到文件中,并在完成后输出文件路径。
--save-all-for-bugreport:克隆所有符合条件的错误报告 session,并将它们保存到错误报告输出文件中。
--no-guardrails:在使用
--upload时禁用防止过度资源使用的保护措施(仅用于测试)。
--reset-guardrails:兼容性选项。Guardrails 在
perfetto_cmd中已不再存在;保留此选项是为了向后兼容。
--query:查询服务状态并将其作为人类可读的文本打印。
--long:展开
--query输出中的某些字段(例如类别列表)。只能与--query一起使用。
--query-raw:类似于
--query,但打印tracing_service_state.proto的原始 proto 编码字节。
--detachKEY:使用给定的密钥从 tracing session 分离。
--attachKEY:使用给定的密钥重新附加到已分离的 tracing session。
--stop:仅在与
--attach一起使用时支持。重新附加后停止 tracing。
--is_detachedKEY:检查 session 是否可以被重新附加。退出代码语义:
0可以,2不可以,1错误。
-h,--help:打印
perfetto工具的帮助文本。
简单模式
为了便于使用,perfetto 命令包括通过命令行参数支持配置子集。在设备上,这些配置的行为与 CONFIG_FILE(见下文)提供的相同配置等效。
使用 perfetto 在 简单模式 中的通用语法如下:
adb shell perfetto [ --time TIMESPEC ] [ --buffer SIZE ] [ --size SIZE ]
[ --app APP_NAME ]
[ ATRACE_CAT | FTRACE_GROUP/FTRACE_NAME]...以下列出了 perfetto 在简单模式下的可用选项。
-t,--timeTIME[s|m|h]:指定 trace 持续时间(秒、分钟或小时)。 例如,
--time 1m指定 1 分钟的 trace 持续时间。 默认持续时间为 10 秒。
-b,--bufferSIZE[mb|gb]:指定环形缓冲区大小(兆字节或千兆字节)。 默认参数为
--buffer 32mb。
-s,--sizeSIZE[mb|gb]:指定最大文件大小(兆字节或千兆字节)。 默认情况下,
perfetto仅使用内存中的环形缓冲区。
-a,--appAPP_NAME:为 atrace 应用级 tracing 指定 Android 应用名称。
后面跟着事件说明符列表:
ATRACE_CAT:指定要为其采集 trace 的 atrace 类别。 例如,以下命令使用 atrace 追踪窗口管理器:
adb shell perfetto --out FILE wm。要记录其他类别,请参阅 atrace 类别列表。 注意:可用类别取决于 Android 版本。
FTRACE_GROUP/FTRACE_NAME:指定要为其采集 trace 的 ftrace 事件。 例如,以下命令追踪 sched/sched_switch 事件:
adb shell perfetto --out FILE sched/sched_switch
普通模式
使用 perfetto 在 普通模式 下的通用语法如下:
adb shell perfetto [ --txt ] --config CONFIG_FILE以下列出了 perfetto 在普通模式下的可用选项。
-c,--configCONFIG_FILE:指定配置文件的路径。在普通模式下,某些 配置可以在配置协议缓冲区中编码。 此文件必须符合 AOSP
trace_config.proto中定义的协议缓冲区模式。 你使用 TraceConfig 的 DataSourceConfig 成员选择和配置数据源,如 AOSPdata_source_config.proto中所定义。 使用-从 stdin 读取配置字节。
--txt:指示
perfetto将配置文件解析为 pbtxt。此标志 是实验性的,不建议在生产环境中启用。