📚 课程目录第4章环境搭建与快速上手

4. 环境搭建与快速上手

Perfetto 的分析能力再强，也必须先拿到一份合格的 Trace。很多初学者第一次采集失败，并不是工具不会用，而是设备端没配置好、adb 版本不匹配、或者抓取时长与缓冲区设置不合理。本节把环境搭建拆成“设备端—主机端—采集入口—验证”四步，帮助你一次跑通第一个 Trace。

一、核心原理：Perfetto 的三层结构

理解环境搭建，先要理解 Perfetto 的组成。它由三部分协同工作：设备端的 traced 与 traced_probes 守护进程负责收集内核与用户空间数据；主机端的 perfetto 命令行工具或 Perfetto UI 负责下发配置、拉取结果；Trace 文件本身是 protobuf 格式，可被 UI 或 trace_processor 解析。设备端配置决定了“能采到什么”，主机端工具决定了“怎么采、怎么读”。

二、设备端配置：让采集权限与数据源就绪

Android 10 及以上系统已内置 Perfetto，无需额外安装。但采集系统级数据需要权限，通常有两种方式：

userdebug / eng 版本：可直接 adb root，随后 adb shell setprop persist.traced.enable 1 开启 traced 服务。
user 版本：无法 root，需使用 adb shell perfetto 或通过 --drop-box 方式，并依赖系统预置的 perfetto 可执行文件与 traced 服务。

验证设备端是否就绪，可执行以下命令：

adb shell getprop persist.traced.enable
# 返回 1 表示 traced 已启用

adb shell ps -A | grep traced
# 应看到 traced 与 traced_probes 两个进程

adb shell perfetto --help
# 能输出帮助信息，说明设备端 perfetto 可用

如果 ps 中看不到 traced，先确认系统版本是否 ≥ Android 10，再检查 persist.traced.enable 是否为 1。部分厂商 ROM 会裁剪该服务，此时只能使用 atrace 或 systrace 兼容模式。

三、主机端工具：adb、Perfetto CLI 与 UI

主机端需要准备三样东西：adb、Perfetto 命令行工具、以及浏览器中的 Perfetto UI。adb 建议使用较新版本（1.0.41 以上），否则可能出现 adb: failed to read command 等兼容问题。Perfetto CLI 可从官方 release 页面下载对应平台的可执行文件，放入 PATH 后即可使用。

工具	作用	典型命令 / 入口
adb	连接设备、传输文件、执行 shell	`adb devices`、`adb pull`
perfetto CLI	下发配置、采集、查询 Trace	`perfetto -c config.pbtx -o out.perfetto-trace`
Perfetto UI	浏览器可视化分析	ui.perfetto.dev
trace_processor	SQL 查询与指标计算	`trace_processor_shell out.perfetto-trace`

四、第一个 Trace：从配置到落盘

下面是一份最小可用的采集配置，覆盖 ftrace、进程统计与 atrace 三类常用数据源。保存为 config.pbtx：

buffers {
  size_kb: 16384
  fill_policy: RING_BUFFER
}

data_sources {
  config {
    name: "linux.ftrace"
    ftrace_config {
      ftrace_events: "sched/sched_switch"
      ftrace_events: "sched/sched_wakeup"
      ftrace_events: "power/cpu_frequency"
      atrace_categories: "gfx"
      atrace_categories: "view"
      atrace_categories: "sched"
      atrace_apps: "com.example.app"
    }
  }
}

data_sources {
  config {
    name: "linux.process_stats"
    process_stats_config {
      scan_all_processes_on_start: true
    }
  }
}

duration_ms: 10000

随后通过 adb 将配置推送到设备并启动采集：

adb push config.pbtx /data/misc/perfetto-configs/config.pbtx

adb shell perfetto \
  -c /data/misc/perfetto-configs/config.pbtx \
  --txt \
  -o /data/misc/perfetto-traces/first.perfetto-trace

adb pull /data/misc/perfetto-traces/first.perfetto-trace ./first.perfetto-trace

如果主机端已安装 Perfetto CLI，也可以直接在主机侧完成采集，无需手动 push：

perfetto -c config.pbtx --txt -o first.perfetto-trace \
  --android-device-connection adb

采集完成后，用 Perfetto UI 打开 first.perfetto-trace，即可看到 CPU 频率、调度切换、应用帧等轨道。若想用 SQL 验证数据是否完整，可执行：

trace_processor_shell first.perfetto-trace
> select count(*) from slice;
> select name, dur from slice order by dur desc limit 10;

五、常见误区与复盘

误区一：缓冲区太小。默认 4MB 在高负载场景下几秒就会写满，导致 Trace 被截断。建议至少 16MB，长采集可到 64MB 以上。

误区二：忘记设置 duration_ms。不设时长会一直采集，直到手动停止，容易产生超大文件。首次采集建议 10 秒。

误区三：atrace_apps 包名写错。包名错误不会报错，但应用相关轨道为空。采集前用 adb shell pm list packages | grep 关键词 确认。

误区四：user 版本直接 adb root。会失败并提示 adbd cannot run as root in production builds，应改用 adb shell perfetto 方式。

复盘一次成功的采集，检查清单如下：设备端 traced 进程存在、adb devices 能识别设备、配置文件语法正确、采集时长与缓冲区匹配、Trace 文件大小合理（通常几 MB 到几十 MB）、UI 中能看到至少一条 CPU 调度轨道。满足这些条件，说明环境搭建已经完成，可以进入后续的轨道解读与性能分析环节。