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-fd FD

:类似于 --background-wait,但不是守护进程化并在退出前等待,而是写入一个状态字节并关闭给定的文件描述符。成功时写入 0,超时/错误时写入非零值。Windows 上不支持。

-o, --out OUT_FILE

:指定输出 trace 文件的所需路径,或 - 用于 stdout。 perfetto 将输出写入上述标志描述的文件。 输出格式符合 AOSP trace.proto 中定义的格式。

--no-clobber

:不覆盖已存在的输出文件。

--clone TSID

:创建由 session ID(TSID)标识的现有 tracing session 的只读克隆(参见 --query)。

--clone-by-name NAME

:创建由 unique_session_name 标识的现有 tracing session 的只读克隆。

--clone-for-bugreport

:只能与 --clone 或 --clone-by-name 一起使用。在克隆的 session 上禁用 trace_filter。

--add-attribute key[=value]

::添加一个 trace attribute,即描述 trace 的键值对。如果省略 =value,值为空字符串。属性在 Trace Processor 的 metadata 表中显示为 trace_attribute.<key> 行。

--version

:打印 perfetto 版本字符串并退出。

--dropbox TAG

:已弃用。通过 DropBoxManager API 使用你指定的标签上传你的 trace。仅限 Android。请改用 --upload。

--upload

:将 trace 输出上传到 TraceConfig(android_report_config)中配置的 Android 框架报告路径。仅限 Android。

--alert-id ID

:Statsd 元数据。触发此 trace 的 alert 的 ID。

--config-id ID

:Statsd 元数据。触发配置的 ID。

--config-uid UID

:Statsd 元数据。注册触发配置的应用的 UID。

--subscription-id ID

: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 编码字节。

--detach KEY

:使用给定的密钥从 tracing session 分离。

--attach KEY

:使用给定的密钥重新附加到已分离的 tracing session。

--stop

:仅在与 --attach 一起使用时支持。重新附加后停止 tracing。

--is_detached KEY

:检查 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, --time TIME[s|m|h]

:指定 trace 持续时间(秒、分钟或小时)。 例如,--time 1m 指定 1 分钟的 trace 持续时间。 默认持续时间为 10 秒。

-b, --buffer SIZE[mb|gb]

:指定环形缓冲区大小(兆字节或千兆字节)。 默认参数为 --buffer 32mb。

-s, --size SIZE[mb|gb]

:指定最大文件大小(兆字节或千兆字节)。 默认情况下,perfetto 仅使用内存中的环形缓冲区。

-a, --app APP_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, --config CONFIG_FILE

:指定配置文件的路径。在普通模式下,某些 配置可以在配置协议缓冲区中编码。 此文件必须符合 AOSP trace_config.proto 中定义的协议缓冲区模式。 你使用 TraceConfig 的 DataSourceConfig 成员选择和配置数据源,如 AOSP data_source_config.proto 中所定义。 使用 - 从 stdin 读取配置字节。

--txt

:指示 perfetto 将配置文件解析为 pbtxt。此标志 是实验性的,不建议在生产环境中启用。