perfetto-performance-analysis

Perfetto 性能分析

许可证：AGPL-3.0-or-later。源：Perfetto Skills。

基于证据分析跟踪记录，而不是根据症状名称猜测。使用随附脚本执行确定性查询，并且仅加载所选工作流所需的参考资料。

要求

使用 Python 3.11+、本地文件系统和终端访问权限，以及经过校验和验证的 Perfetto trace_processor_shell。安装后可独立运行；无需 SmartPerfetto 或上游 Perfetto 检出版本。

操作约定

1. 将包含此 SKILL.md 的目录确定为 Skill 根目录。执行脚本前，将脚本和参考资料路径转换为绝对路径；不要假设存在特定于客户端的环境变量。
2. 分析前，记录每个输入跟踪文件的路径、SHA-256、请求的进程/线程、时间范围和跟踪侧。
3. 执行领域查询前，先运行 scripts/perfetto_probe.py。将不可用的表、模块、轨道或跟踪信号视为限制，而非否定性证据。
4. 从下方选择一个主要工作流。直接加载其 Markdown 文件，然后遵循其可用性门槛和证据顺序。
5. 使用 scripts/perfetto_skill.py run 执行完整的已导出 Skill，或使用 scripts/perfetto_query.py --query-id 执行一个清单查询。保存的每项结果都要附上查询源、参数、跟踪身份、时间戳、持续时间、单位和返回行数范围。
6. 执行编写或修改过的 SQL 前，先运行SQL 防护脚本。按照 SQL 防护约定解决阻断问题并审查提示。
7. 将观察、相关性、机制和已验证的根因区分开。没有证据支持所声称的进程、线程、时间窗口和跟踪时，不得将假设升级为结论。
8. 进行比较时，先独立分析每条跟踪记录，再计算差值。绝不能将一侧缺失的指标作为另一侧出现回退的证据。
9. 按照 assets/report-schema.json 中的结构输出。在 limitations 下列出缺失的证据和尚未排除的其他可能性。

请先阅读证据约定，然后在撰写结论前使用身份规则、缺失数据规则和结论验证。

工作流路由

• 跟踪健康状况、边界、身份和广泛分诊：跟踪概览
• 冷启动、温启动、热启动和首帧启动：启动
• 帧生成、呈现、滚动和卡顿：滚动
• 触摸、点击、输入分发、响应和导航：交互
• ANR、Binder、锁、futex 和阻塞链：ANR 和阻塞
• CPU 负载、拓扑、频率、空闲、IRQ 和调度延迟：CPU 调度
• RSS、堆、GC、LMK、DMA-BUF 和分配：内存
• GPU、SurfaceFlinger、栅栏、VRR 和帧合成：GPU 渲染
• Rails、唤醒锁、电池、热量和降频：电源和热量
• 文件系统、块 IO、网络、调制解调器、媒体和 WebView：IO、网络和媒体
• Compose、Flutter、React Native、游戏和厂商信号：框架和游戏
• 渲染架构检测与讲解：渲染管线
• 跨领域事件序列重建：场景重建
• 两个或更多跟踪记录或已保存的结果集：跟踪比较

选择或验证工作流 ID 时，请使用机器可读的工作流索引。

运行时命令

列出或运行确定性的可移植 Skill 图：

python3 <skill-root>/scripts/perfetto_skill.py list
python3 <skill-root>/scripts/perfetto_skill.py run /absolute/trace.pftrace \
  --skill startup_analysis --param 'package="com.example"' \
  --output-dir /absolute/output/run

只能通过 --param 传入 Skill 声明的输入；运行器会在接触跟踪数据前拒绝任何其他名称。具有进程身份门控的 Skill 也接受其身份别名（package、process_name 等）：该门控会使用 process_identity_resolver Skill 验证指定进程，并将别名重写为经过验证的 process.name。对于未经验证或存在歧义的目标，运行器会拒绝执行并说明原因（identity_blocked）；请从该 Skill 的候选项中选择准确的进程名称，而不要用同一个名称重试。经过验证的 upid（或对应一个 UPID 的 pid）会让 Skill 仅对该进程运行；如果 Skill 的 SQL 无法以这种方式运行，则会告知可运行的 Skill。

完整的 Skill 运行和 --query-id 运行会在执行 SQL 前，根据发布锁验证所选处理器的提交版本、RPC API、平台和 SHA-256。可独立检查该身份：

python3 <skill-root>/scripts/perfetto_doctor.py

仅在明确标记的金丝雀测试中使用 --allow-unsupported-processor；这不会使结果成为经过验证的证据。能力门控查询只有在对同一跟踪数据自动探测并证明其必需架构存在后才会运行；门控结果会保留在证据附属文件中。--allow-unverified 是单独的选择加入参数，仅用于明确归类为未经验证的查询，且绝不会绕过缺失的能力。

探测跟踪数据：

python3 <skill-root>/scripts/perfetto_probe.py /absolute/path/to/trace.pftrace \
  --output /absolute/path/to/output/probe.json

运行引用的 SQL 资源：

python3 <skill-root>/scripts/perfetto_query.py /absolute/path/to/trace.pftrace \
  --sql-file <skill-root>/references/generated/sql/<query>.sql \
  --format json --output /absolute/path/to/output/query.json

请通过公共封装器绑定 SmartPerfetto DSL 占位符，而不要编辑 SQL 文本。--param NAME=JSON 可安全绑定标量输入和 JSON 数组（会渲染为 IN (...) 的 SQL 字面量列表），--module android.example.module 会加载声明的先决条件，--result NAME=/path/prior.json 会将非空的已保存行数组作为关系提供给依赖步骤。诸如 ${prior_step.data[0].upid} 的管道表达式可从这些行中选取标量字段。占位符 ${name|default} 会在省略 name、解析结果为 JSON null 或索引超出已保存结果的行范围时使用默认值，因此，指向空前置步骤的默认路径无需 --result：

python3 <skill-root>/scripts/perfetto_query.py /absolute/trace.pftrace \
  --sql-file <skill-root>/references/generated/sql/<skill>/<step>.sql \
  --module android.frames.timeline \
  --param 'package="com.example"' --param start_ts=123 \
  --result prior_step=/absolute/output/prior-step.json \
  --output /absolute/output/current-step.json

运行时会拒绝未解析的占位符，并默认将 trace-processor 的标准输出和标准错误限制为 16 MiB。使用 --max-output-bytes 可降低此上限；只有对于经过审核且明确限制了输出大小的查询，才应提高上限。

进行比较时，请先使用 assets/comparison-input-schema.json 为每条独立分析的跟踪数据写入一个侧摘要文件，然后运行 scripts/perfetto_compare.py --side baseline=a.json --side candidate=b.json --baseline baseline。

如果无法使用 trace_processor_shell，请运行 scripts/bootstrap_trace_processor.py，或通过 --trace-processor 或 PERFETTO_TRACE_PROCESSOR 提供已锁定的可执行文件。

参考资料发现

生成的参考资料数量众多。无需加载整个目录，即可查找 SmartPerfetto Skill、SQL 步骤、表或信号：

rg -n "<skill-id|table|signal>" <skill-root>/references/generated

加载直接链接的结果及其来源证明。不要仅凭文件名推断步骤语义。

兼容性

需要 Python 3.11+、文件系统访问权限、终端执行能力，以及兼容的 Perfetto trace_processor_shell。这些可移植说明适用于 Codex、Claude Code、OpenCode，以及其他实现 Agent Skills 并提供这些功能的客户端。无法访问本地文件或终端的纯云端 Agent 可以使用方法参考资料，但不能执行跟踪查询。