跳转至

快速开始

前置要求

  • Python >= 3.10
  • adb 在 PATH 中（仅 trace 命令需要）

安装

通过 pip

pip install perfetto-cli

通过 uvx（免安装）

uvx perfetto-cli --help

从源码安装

git clone https://github.com/SYKernel/perfetto-cli.git
cd perfetto-cli
pip install -e ".[dev]"

AI 工具集成（可选）

perfetto-cli 提供 skills 系统，可与 AI 编程助手集成。安装后，AI 工具能自动理解并使用 perfetto-cli 进行 trace 分析。

支持的 AI 工具： Claude Code、Cursor、Codex、Gemini CLI、OpenCode

# 交互式安装 — 自动检测 AI 工具并引导完成配置
perfetto-cli skills install

# 或一键安装所有 skills 到所有检测到的工具
perfetto-cli skills install --all --target all --scope global

# 查看安装状态
perfetto-cli skills list

安装完成后，你可以自然地与 AI 助手对话 — 它会自动运行相应的 perfetto-cli 命令并解读结果。详见 AI 辅助使用。

第一次分析

1. 获取 trace 文件

从设备抓取：

perfetto-cli trace start --duration 10s
perfetto-cli trace stop

或使用已有的 .perfetto-trace 文件。

2. 运行分析

# 检测 ANR 事件
perfetto-cli -t trace.perfetto-trace -p com.example.app anr detect

# 检查帧性能
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank

# 查看 CPU 利用率
perfetto-cli -t trace.perfetto-trace -p com.example.app cpu utilization

3. 选择输出格式

# 人类友好的彩色输出（默认）
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank

# ASCII 表格
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank -f table

# JSON 用于脚本处理
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank -f json

全局选项

选项 说明 默认值
-t, --trace <path> Trace 文件路径 必填
-p, --process <name> 进程名过滤 无
-f, --format <type> 输出格式：text / table / json text
-v, --verbose 详细输出 关闭
--tp-path <path> 自定义 trace_processor 路径 自动
--version 显示版本号 —

下一步