android-perfetto-capture

Android：Perfetto 采集（adb 主线）

何时用本 skill

• 需要 adb shell perfetto 在真机/工程机上录 系统级 Perfetto trace，并用 adb pull 取回。
• 需要 可版本化 的采集配置（本 skill 自带 configs/*.pbtxt），避免「设置里找不到系统跟踪」类 OEM 差异。
• ANR：出现时间不可预期，短固定 duration_ms 容易录空；用 configs/anr-surveillance.pbtxt + 后台/分离式启动，复现到 ANR 后 尽快结束 perfetto 再 adb pull（见下文「ANR 场景」）。需要 view/gfx atrace 时改用 configs/anr-surveillance-graphics.pbtxt（体积更大）。
• 采集完成后要衔接 Perfetto UI 或 trace_processor + perfetto-sql 做分析（SQL 细节不在本 skill 展开）。

本 skill 给出 Agent 协助时的 稳定默认路径。涉及 TraceConfig 字段、平台对 perfetto 的说明、与 adb 配套的官方表述 时，不得以未经验证的网页摘要或第三方索引代替正文：须按 android-cli-docs-skills 使用终端 android docs search（如 perfetto、system trace、TraceConfig 等关键词），对结果中的 kb://... 用 android docs fetch 拉取后再引用；未 fetch 到正文不得编造。

前置检查

1. adb devices 为 device；多设备一律 -s <serial>（细则见 android-adb-emulator）。
2. 设备 Android 10+；存在可执行的 /system/bin/perfetto（极少数裁剪 ROM 可能没有）。
3. 配置为 文本 proto 时，命令必须带 --txt。

默认工作流（推荐）

1. 使用本目录下的 configs/minimal.pbtxt（先打通）或 configs/standard.pbtxt（通用卡顿/调度向）。
2. adb push 配置到设备 /data/local/tmp/（示例见 examples.md）。
3. 执行：
   adb shell perfetto -c /data/local/tmp/<配置名>.pbtxt --txt -o /data/local/tmp/<输出名>.perfetto-trace
   进程会阻塞至配置中的 duration_ms 结束。
4. adb pull 将输出拉回 PC；本地文件名建议带 时间戳 + serial。

设备路径原则：优先 /data/local/tmp/ 作为配置与输出目录；避免默认假设可写 /data/misc/perfetto-traces/（权限因 ROM 而异）。

ANR 场景（不定时长看守）

问题：minimal / standard 以固定 duration_ms 为主，适合「已知短复现窗」；ANR 往往 长时间偶发，短窗录不到、长窗阻塞终端且文件暴涨。

推荐做法：

1. 使用 configs/anr-surveillance.pbtxt：主缓冲为 RING_BUFFER、duration_ms 仅作上限（默认 2 小时量级，可按需改小），数据源相对 standard 略减（减轻长时间开销）。
2. 先启动采集（非阻塞），再去做复现；一旦出现 ANR（或弹窗/卡死可判定），尽快结束 设备上的 perfetto 进程，使输出文件落盘完整，然后 adb pull。具体 --background / nohup ... & / pidof+kill 以设备 perfetto --help 与 android-cli-docs-skills 拉取的正文为准（示例见 examples.md 第 5 节）。团队内可统一用 scripts/anr-perfetto-watch.py（Python 3） 自动监听 logcat 或手动收尾并拉取产物（见 examples.md 第 6.9 节）。
3. 与文本证据配合：traces.txt / bugreport 里的 ANR 栈仍用 parsing-android-anr；Perfetto trace 提供 时间线、调度与 log 侧证，两者互补。