EN

Android Perfetto 系列 15:Boot Trace、长时间现场 Trace 与偶发问题抓取

字数统计: 9.3k阅读时长: 39 min
2026/05/04
loading

开机慢、亮屏后偶发卡顿或几小时后才出现的音频断续,通常等不到工程师连上电脑再按「开始录制」。要保留问题发生前的调度、帧或音频事件,采集配置必须提前在设备上运行。

现场抓取要先确定触发点前后各保留多久,再选 Ring Buffer、周期写文件或 trigger。文件写出后,还要确认问题窗口没有被覆盖、关键数据源没有丢失。设备开机属于更早的特殊窗口,单独处理。

版本说明(2026-10 核查):以下配置和命令以 Perfetto v58.3 为核查基线。Android 版本、设备端 perfetto CLI、traced 服务和主机分析工具需分别确认;Android 14 支持 session clone,不代表自带 v49+ 的 --clone-by-name。write_flush_mode 属于 v54+,旧设备应删除不支持字段并核对该版本的手动 flush 策略。

Perfetto 系列文章

  1. Android Perfetto 系列目录
  2. Android Perfetto 系列 1:Perfetto 工具简介
  3. Android Perfetto 系列 2:Perfetto Trace 抓取
  4. Android Perfetto 系列 3:熟悉 Perfetto View
  5. Android Perfetto 系列 4:使用命令行在本地打开超大 Trace
  6. Android Perfetto 系列 5:Android App 基于 Choreographer 的渲染流程
  7. Android Perfetto 系列 6:为什么是 120Hz?高刷新率的优势与挑战
  8. Android Perfetto 系列 7:MainThread 和 RenderThread 解读
  9. Android Perfetto 系列 8:深入理解 Vsync 机制与性能分析
  10. Android Perfetto 系列 9:CPU 信息解读
  11. Android Perfetto 系列 10:Binder 调度与锁竞争
  12. Android Perfetto 系列 11:PerfettoSQL、Trace Processor 与回归检测
  13. Android Perfetto 系列 12:Trace 数据流与丢失排查
  14. Android Perfetto 系列 13:Perfetto SDK、Track Event 与 App 现场 Trace
  15. Android Perfetto 系列 14:heapprofd 与内存 Profiling
  16. Android Perfetto 系列 15:Boot Trace、长时间现场 Trace 与偶发问题抓取
  17. Android Perfetto 系列 16:GPU、Power Counters 与硬件瓶颈分析
  18. Android Perfetto 系列 17:专项场景自动化、问题清单与平台体系
  19. Android Perfetto 系列 18:响应速度实战,从输入事件到首帧反馈
  20. 视频(B站) - Android Perfetto 基础和案例分享
  21. 视频(B站) - Android Perfetto 分享 - 出图类型分享:AOSP、WebView、Flutter + OEM 系统优化分享

长录制期间,数据源持续写入,Buffer 容量和文件周期决定最后能留下哪一段。配置里只放目标问题需要的信号,并按估计写入速率计算保留窗口;开太多数据源容易让根因发生前的事件先被覆盖。

三种现场采集方式

示意图:STOP trigger 封存触发窗口,周期写文件分批落盘,clone 则保留原会话继续运行。

长 Trace 先设计证据窗口

长 Trace 的核心是取舍:问题前后各保留多少,哪些数据源值得留下。开始写配置前,先把问题窗口问清楚:

问题 影响配置的地方
问题多久复现一次 duration_ms、是否需要后台运行、是否需要周期 snapshot
根因在问题前还是问题后 选择 STOP trigger 还是 START trigger
需要保留问题前多少秒 Ring Buffer 大小、数据源宽度、写文件周期
用户能不能手工停止 是否需要自动 trigger、是否接入 bugreport
早期 ADB 不可用 Boot Trace、平台预置、init/service 触发或厂商方案
trace 启动后可能断 USB --background-wait、detached mode、snapshot 或后台服务
文件最大能多大 max_file_size_bytes、上传策略、本地 TTL
数据是否敏感 log tag 白名单、是否禁用 atrace_apps: "*"

偶发 UI 卡顿通常需要问题前几十秒;温升降频可能需要几分钟趋势;车机长稳问题可能要跑几个小时。这类场景通常只周期性拉取 snapshot,或只上传 summary。

常见场景可以先映射到 preset,再写 TraceConfig:

场景 推荐模式 触发和验收重点
UI 偶发卡顿 Ring Buffer + STOP trigger App marker、FrameTimeline 覆盖目标窗口、触发前窗口足够
ANR 前兆 Ring Buffer + STOP trigger 主线程、Binder、锁等待、I/O 和关键业务阶段同时在场
温升降频 write_into_file 或 snapshot CPU freq、idle、thermal 状态和 App 关键阶段按分钟级趋势保留
业务 timeout App marker + STOP/START trigger 要保留 timeout 前后用 STOP 并留足 stop_delay;仅需事后窗口时才用 START
音频 underrun Ring Buffer + STOP trigger audio/server 事件、sched、binder、wakeups 和 underrun marker 同步

现场采集先受设备和权限限制

现场方案不能只看 TraceConfig,还要看设备版本、build 类型和触发者权限。

环境 可以依赖什么 不该假设什么
userdebug / root 研发设备 按实际权限使用配置目录、log和更多系统事件 root不保证adb root可用,仍需检查adbd/SELinux、log白名单与资源预算
user build + adb shell 常规系统 Trace、包名限定的 atrace、审核过的 preset 不默认依赖 android.log;不能假设任意配置路径都可读;优先使用 /data/misc/perfetto-configs
普通 App 记录 App 侧 ATrace / Track Event,激活预先声明的 trigger 本例 trigger 合同不授予系统 consumer 权限;ProfilingManager 等受限请求接口另按 API/策略处理
CPU / native / Java profiling 按数据源要求检查 debuggable、profileable、Android 版本 不把 <profileable> 当成现场系统 Trace 的通用权限开关

文本 proto 配置的扩展名可以是 .pbtxt 或 .pbtx;解析方式由 perfetto --txt 或工具链里的编码步骤决定。本文后面统一用 .pbtxt 做文件名。

各节配置不能直接拼接:后台停止示例的field.pbtxt应使用含数据源、duration与write_into_file的完整配置;STOP模式则按trigger生命周期处理,不能用SIGINT兜底获取未命中现场。每轮输出路径要唯一,固定文件名仅用于单轮示例,使用前先归档旧产物。

Boot Trace 是特殊现场窗口

App 冷启动和系统开机是两类问题。App 启动路径在旧的 Systrace 响应速度实战里已经讲过,第 05 篇也覆盖了启动后的渲染链路,这里只处理设备级开机:ADB 还没可用、但 Android 已经进入 /data 挂载后的启动阶段,怎么把系统 Trace 抓全、看准、写成可复查结论。

需要 Boot Trace 的场景通常有几类:

现象 为什么普通 trace 不够
开机到桌面慢 问题发生在 ADB 可用前
OTA 后第一次启动慢 init、zygote、dexopt、system_server 都要看
Launcher 首帧晚 要同时看 system_server、SurfaceFlinger、Launcher
某服务开机阻塞 需要 init/service manager/Binder 上下文
用户说“重启后很久才能用” 要先定义 ready 标准

Boot Trace 是平台或系统启动专项窗口;App 冷启动不走这条路线。分析前要先讲边界:

  • Android boot tracing 是 Android 13+ 的能力。更早版本需要厂商自己的启动采集方案。
  • v58.3 的 init 规则还要求 persist.traced.enable=1、traced 已监听且 sys.boot_completed 尚未设置;persistent properties 加载发生在 /data 挂载后。不覆盖 PMIC 上电、bootloader、kernel early boot、first-stage init。更早阶段要靠 pstore、kernel cmdline/ftrace persistent buffer 或 vendor init instrumentation。
  • 这类流程通常假设研发设备或 userdebug 上可以 adb root。生产 user build 需要平台预置、工程版本或厂商诊断入口。
  • UI 的相对时间轴起点不等于电源键按下或 PMIC 上电;SQL ts 保留 Trace Processor 统一时钟域下的时间戳,并不会自动从 tracing 开始归零。报告里比较同一份 Trace 内的相对阶段,不要把不同设备的绝对 ts 硬比较。
  • “开机完成”没有唯一标准。Launcher 第一帧、可输入、网络可用、导航服务 ready、后台任务完成,可能是不同团队的指标。
  • 不写文件模式通常结束后才有输出;write_into_file 模式可以提前看到部分文件,但出现文件不等于录制完成。persist.debug.perfetto.boottrace 是 one-shot,下一次 boot 前要重新设置。

boottrace.pbtxt 是该启动入口要求的固定文本配置文件名,不能换成 binary proto。duration_ms 给这轮采集设终点;本例使用 write_flush_mode: WRITE_FLUSH_AUTO,写周期5秒时由v58.3自动按5秒请求flush,不能同时假定 flush_period_ms:10000 生效。第一版不要太贪心,先抓调度、进程生命周期和少量 ATrace,再按 ready 标准加信号。

DISCARD 保留未读的早期数据,但在消费者读取前写满仍会丢新事件;RING 则覆盖未读旧事件。这里已开周期写文件,容量应覆盖两次实际读取间的峰值和延迟,而不是直接按90秒全量估算。128 MiB 是示例预算,已占满 extra guardrails 默认总buffer上限,不能再无条件叠加其他buffer。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
duration_ms: 90000
prefer_suspend_clock_for_duration: true
write_flush_mode: WRITE_FLUSH_AUTO
write_into_file: true
file_write_period_ms: 5000
max_file_size_bytes: 536870912

buffers { size_kb: 131072 fill_policy: DISCARD }

data_sources {
config {
name: "linux.ftrace"
ftrace_config {
ftrace_events: "sched/sched_switch"
ftrace_events: "sched/sched_waking"
ftrace_events: "task/task_newtask"
ftrace_events: "task/task_rename"
ftrace_events: "sched/sched_process_exec"
ftrace_events: "sched/sched_process_exit"
ftrace_events: "sched/sched_process_fork"
ftrace_events: "sched/sched_process_free"
ftrace_events: "power/cpu_frequency"
ftrace_events: "power/cpu_idle"
atrace_categories: "am"
atrace_categories: "wm"
atrace_categories: "gfx"
}
}
}

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

下面流程用于已具备root权限的研发设备。先归档设备上上一次 boottrace:init 开始新录制时会删除同路径旧文件。脚本校验 boot id 已变化、one-shot 属性已消费、专用 init service 已停止,再检查非空输出;这些还不替代之后的内容验收。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
adb root || exit 1
adb wait-for-device
BOOT_ID_BEFORE=$(adb shell cat /proc/sys/kernel/random/boot_id) || exit 1
adb push boottrace.pbtxt /data/misc/perfetto-configs/boottrace.pbtxt || exit 1
adb shell setprop persist.debug.perfetto.boottrace 1 || exit 1
adb reboot || exit 1
adb wait-for-device
adb root || exit 1
adb wait-for-device
BOOT_ID_AFTER=$(adb shell cat /proc/sys/kernel/random/boot_id) || exit 1
[ "$BOOT_ID_BEFORE" != "$BOOT_ID_AFTER" ] || {
echo "Boot has not changed; do not pull a stale trace" >&2; exit 1;
}
adb shell '
attempts=0
while [ "$(getprop persist.debug.perfetto.boottrace)" = "1" ] ||
[ "$(getprop init.svc.perfetto_trace_on_boot)" != "stopped" ]; do
attempts=$((attempts + 1))
[ "$attempts" -lt 120 ] || { echo "Boot trace did not stop" >&2; exit 1; }
sleep 2
done
[ "$(getprop persist.debug.perfetto.boottrace)" != "1" ] || exit 1
[ -s /data/misc/perfetto-traces/boottrace.perfetto-trace ] || exit 1
' || exit 1
adb pull /data/misc/perfetto-traces/boottrace.perfetto-trace \
boottrace-$(date +%Y%m%d-%H%M%S).perfetto-trace

拿到 Boot Trace 后,先验收再分析:

本例没有开启 FrameTimeline 或特定的 ready marker。看见 Launcher 进程、sched 或首次绘制标记,不等于已证明首帧呈现/可输入;若这是验收目标,补相应数据源、业务标记或外部观测。

  • Trace 是否覆盖从 /data 挂载后的 Android boot 窗口到目标 ready 点。
  • stats 里是否有 data loss、packet loss、ftrace setup error。
  • init、system_server、surfaceflinger、launcher 这些进程是否可见。
  • process stats、sched、freq 是否都有数据;log 只在配置和 build 类型都支持时检查。
  • 设备是冷启动、adb reboot,还是 OTA 后第一次启动。
  • metadata.json 是否记录按键/重启方式、boot id、ready 标准、trace start/end、设备 build 和采集者权限。

分析顺序建议固定:init/service 启动、zygote、system_server、PackageManager/ActivityTaskManager、SurfaceFlinger、Launcher、首帧/可输入 ready 点。报告里要写清 ready 标准,否则“开机慢 3 秒”很容易变成跨团队争论。

若要读取崩溃重启前的末段 ftrace,可另看 Tracing across reboot 的 linux.frozen_ftrace。它依赖内核侧预置持久环形缓冲,和本文“在下一次 Android 启动时自动录制”的 boottrace 是不同方案。

三种现场长 Trace 模式

Perfetto 的现场长 Trace 可以按这三种模式设计:

模式 行为 适合场景 风险
Ring Buffer + STOP trigger 一直循环记录最近窗口,异常发生后停止 掉帧、ANR 前兆、音频 underrun Buffer 太小会覆盖根因;trigger 未命中就没有事故现场
write_into_file 长录制 周期把 Buffer 写到文件 几十分钟到数小时趋势 I/O 开销、文件过大
--clone-by-name snapshot 原始 session 继续跑,按需克隆当前窗口 调参、温控、电源策略实验 需要设备端 perfetto 支持 --clone-by-name,以 perfetto --help / --version 为准;clone 服务能力通常从 Android 14 提供,按名称克隆还需要 v49+ CLI 或对应厂商合入

选模式前,我会先问事故发生前的证据需要留多久:几十秒的偶发卡顿用 Ring Buffer,几小时的趋势问题就得考虑周期写文件。模式定了,再决定数据源。

Ring Buffer 的基线配置

下面这份配置用于 UI 偶发卡顿:trace 启动后立刻记录,Ring Buffer 只保留最近窗口;当 App、平台服务或测试 harness 检测到慢帧并激活 app_ui_jank trigger 后,Perfetto 再记录 1 秒并停止。

这份配置假设第 13 篇讲过的 App 侧业务 marker 和 trigger emitter 已经接入。trigger_config 不会自己根据 FrameTimeline 自动触发;没有 emitter,session 只会等到 trigger_timeout_ms 清理,不能当成“末尾窗口兜底”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
unique_session_name: "ui_jank_flight_recorder"

buffers {
size_kb: 65536
fill_policy: RING_BUFFER
}

buffers {
size_kb: 8192
fill_policy: RING_BUFFER
}

trigger_config {
trigger_mode: STOP_TRACING
trigger_timeout_ms: 3600000
triggers {
name: "app_ui_jank"
producer_name_regex: "com\\.example\\.app"
stop_delay_ms: 1000
max_per_24_h: 10
skip_probability: 0.0
}
}

incremental_state_config {
clear_period_ms: 10000
}

data_sources {
config {
name: "linux.ftrace"
target_buffer: 0
ftrace_config {
buffer_size_kb: 4096
buffer_size_lower_bound: true
drain_period_ms: 250
compact_sched {
enabled: true
}
ftrace_events: "sched/sched_switch"
ftrace_events: "sched/sched_waking"
ftrace_events: "power/cpu_frequency"
ftrace_events: "power/cpu_idle"
atrace_categories: "gfx"
atrace_categories: "view"
atrace_categories: "wm"
atrace_categories: "input"
atrace_categories: "binder_driver"
atrace_apps: "com.example.app"
}
}
}

data_sources {
config {
name: "android.surfaceflinger.frametimeline"
target_buffer: 1
}
}

data_sources {
config {
name: "track_event"
target_buffer: 1
track_event_config {
disabled_categories: "*"
enabled_categories: "ui"
enabled_categories: "memory"
enabled_categories: "app"
}
}
producer_name_filter: "com.example.app"
}

data_sources {
config {
name: "linux.process_stats"
target_buffer: 1
process_stats_config {
scan_all_processes_on_start: true
proc_stats_poll_ms: 5000
}
}
}

这里放了两个 Buffer:高频 ftrace/atrace 进入大 Buffer,FrameTimeline、process stats、App Track Event 进入小的语义 Buffer。原因在于:图形问题里,如果 sched 事件保住了、FrameTimeline、App marker 或进程描述却被覆盖,仍然无法判断是 App、SurfaceFlinger、BufferQueue 还是系统调度导致卡顿。

producer_name_regex 用来限定能激活 trigger 的 producer。正则要和实际 emitter producer 名称一致;如果由测试 harness 代理触发,就把 harness producer 加进白名单,或者为 harness 单独开 trigger 名称。

buffer_size_kb=4096 是每CPU预算,8核设备仅这一层就可能约32 MiB,另加shared memory和72 MiB中央buffer。buffer_size_lower_bound 会限制向下调整,但不保证实际配置始终等于请求值。drain_period_ms 控制周期读取,调小通常增加唤醒;当前250ms不是对所有设备都优于默认值。先查实际设置、setup errors和开销,再调参。

FrameTimeline 需要 Android 12 或更高版本。它不是 trigger emitter,只负责在 trace 里提供 app frame、SurfaceFlinger frame、jank_type、present_type、on_time_finish 和 app-SF flow 等事实。atrace_apps 必须限定目标包名,不要把 atrace_apps: "*" 当成现场默认方案。

Ring Buffer 能保留多久,不由 trigger_timeout_ms 决定,而由数据写入速率和 Buffer 大小决定。估算方式仍然是第 12 篇那条:单buffer保留窗口秒数 ≈ 容量MiB / 写入该buffer的MiB/s。

对 ftrace 还要再看三层 buffer:kernel per-CPU ftrace buffer、producer shared memory、Perfetto central buffer。central buffer 变大只能延长最终保留窗口,救不了 kernel buffer 被 traced_probes 来不及 drain 时的早期丢事件。

现场长 Trace 调优时才考虑 ftrace_config.buffer_size_kb、buffer_size_lower_bound、drain_period_ms、drain_buffer_percent;这些字段要先在短 Trace 里验证开销和设备兼容性。drain_buffer_percent 的当前语义从 Perfetto v48 引入,官方 proto 注释注明 Linux 内核低于 6.9 时不生效;不要把它当作旧内核上替代 drain_period_ms 的通用开关。

若一个64 MiB buffer的实际写入率为2 MiB/s,理想稳态窗口约32秒;增加写入同一buffer的事件会缩短它。其他buffer要分别计算,不能把不同buffer的数据源速率混在分母里。STOP触发后的1秒也继续占用Ring容量,会进一步覆盖前面的数据;要保留触发前窗口,需同时预算尾窗和停机/flush延迟。未命中STOP不返回数据,人工兜底应激活允许的人工trigger,或使用独立且已验证的snapshot会话。

UI jank preset 抓完后,先确认 FrameTimeline 真的存在:

1
2
3
4
5
SELECT 'expected' AS table_name, COUNT(*) AS rows
FROM expected_frame_timeline_slice
UNION ALL
SELECT 'actual' AS table_name, COUNT(*) AS rows
FROM actual_frame_timeline_slice;

再按 process 表确认 App 与 SurfaceFlinger 的 upid,把下列 NULL 替换为这两个进程实例和真实问题窗口的整数ns起止时间。查询保留零行计数和可能与窗口重叠的未闭合帧,不用同名进程或模糊cmdline混合实例;它只检查记录是否存在,不证明目标layer、因果关系或连续覆盖:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
WITH target_window(start_ns, end_ns) AS (
VALUES (NULL, NULL)
), targets(role, upid) AS (
VALUES ('app', NULL), ('surfaceflinger', NULL)
)
SELECT
t.role, p.upid, p.pid, p.name AS process_name,
COUNT(a.id) AS candidate_frame_rows,
COUNT(CASE WHEN a.dur >= 0 THEN 1 END) AS closed_frame_rows,
COUNT(CASE WHEN a.dur < 0 THEN 1 END) AS unclosed_frame_rows,
MIN(a.ts) AS first_start_ns,
MAX(CASE WHEN a.dur >= 0 THEN a.ts + a.dur END) AS last_known_end_ns
FROM targets t
JOIN process p ON p.upid = t.upid
CROSS JOIN target_window w
LEFT JOIN actual_frame_timeline_slice a
ON a.upid = p.upid
AND a.ts < w.end_ns
AND (a.dur < 0
OR (a.dur = 0 AND a.ts >= w.start_ns)
OR (a.dur > 0 AND a.ts + a.dur > w.start_ns))
WHERE typeof(w.start_ns) = 'integer' AND typeof(w.end_ns) = 'integer'
AND w.end_ns > w.start_ns
GROUP BY t.role, p.upid, p.pid, p.name;

如果怀疑 hardirq、softirq 或 kworker 抢 CPU,不要把这些事件放进默认长 Trace。先做短窗口专项 preset,再按结果决定是否进入现场方案:

以下是数据源片段,应并入带明确duration_ms的完整配置;这里不包含独立启动命令。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
data_sources {
config {
name: "linux.ftrace"
ftrace_config {
ftrace_events: "irq/irq_handler_entry"
ftrace_events: "irq/irq_handler_exit"
ftrace_events: "irq/softirq_entry"
ftrace_events: "irq/softirq_exit"
ftrace_events: "irq/softirq_raise"
ftrace_events: "workqueue/workqueue_queue_work"
ftrace_events: "workqueue/workqueue_execute_start"
ftrace_events: "workqueue/workqueue_execute_end"
}
}
}

长录制要周期写文件

几小时问题不能只靠内存Buffer。下面可保存为field.pbtxt,采集CPU频率、thermal节点和系统内存的低频趋势,供后面的后台/停止示例使用;它不包含sched或帧事件。专项加入高频数据源后,要重新测量文件增长与扰动:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
unique_session_name: "field_trends"
duration_ms: 3600000
prefer_suspend_clock_for_duration: true
write_into_file: true
file_write_period_ms: 10000
max_file_size_bytes: 2147483648
write_flush_mode: WRITE_FLUSH_AUTO

buffers {
size_kb: 32768
fill_policy: RING_BUFFER
}

data_sources {
config {
name: "linux.sys_stats"
sys_stats_config {
cpufreq_period_ms: 1000
thermal_period_ms: 1000
meminfo_period_ms: 1000
meminfo_counters: MEMINFO_MEM_AVAILABLE
meminfo_counters: MEMINFO_CACHED
}
}
}

duration_ms 默认不计算系统 suspend 时间。亮灭屏、待机、车机休眠这类按 wall-clock 看的现场问题,应该考虑 prefer_suspend_clock_for_duration: true;它也会影响 trigger stop_delay_ms 的时间语义。

下面大小按二进制单位计算:2147483648 bytes为2 GiB。若实际文件增长为1–2 MiB/s,约17–34分钟就会碰到上限,早于1小时duration。官方调度采集速率只是参考;容量预算要用当前preset的实测峰值/平均值,不能假定缩短写周期会减少总文件量。

log、syscall、page fault与宽泛的业务事件可能显著增加数据量。v58.3 的 write_into_file + AUTO 在写周期大于5秒时于每次写前flush;因此本例10秒写周期不会再按 flush_period_ms:30000 执行。若明确需要手动周期,支持该字段的版本可选 WRITE_FLUSH_DISABLED 配合 flush_period_ms;不能把旧文档10–30秒的经验值当当前AUTO规则。

后台运行和安全停止

现场测试经常会断USB。v58.3 的 --background-wait 最多等30秒获取启动确认,成功退出码为0;先打印PID不代表确认已经成功。它确认的是启动协议,不保证所有预期事件或晚注册producer已就绪;测试动作应等成功返回,采集后仍要核对数据源与窗口。超时后后台子进程可能还在,先查session状态,不能立刻重复启动。

Android 12 及以上设备可将配置放进 /data/misc/perfetto-configs,再启动后台 trace;具体写入权限仍以设备为准:

1
2
3
4
5
6
7
8
9
10
11
adb push field.pbtxt /data/misc/perfetto-configs/field.pbtxt || exit 1

PID=$(adb shell perfetto --background-wait --txt \
-c /data/misc/perfetto-configs/field.pbtxt \
-o /data/misc/perfetto-traces/field.perfetto-trace) || {
printf 'Startup unconfirmed; inspect session before retrying. Output: %s\n' "$PID" >&2
exit 1
}
PID=$(printf '%s' "$PID" | tr -d '\r')

echo "perfetto pid: $PID"

如果 Android 12–17 的目标设备无法使用上述配置路径,也可以从 stdin 传入配置。生产 M2M 工具链更应该用审核过的 preset 或 binary TraceConfig,而不是让服务端下发任意文本配置:

1
2
3
4
5
6
7
8
9
PID=$(adb shell perfetto --background-wait --txt \
-c - \
-o /data/misc/perfetto-traces/field.perfetto-trace < field.pbtxt) || {
printf 'Startup unconfirmed; inspect session before retrying. Output: %s\n' "$PID" >&2
exit 1
}
PID=$(printf '%s' "$PID" | tr -d '\r')

echo "perfetto pid: $PID"

两种启动方式二选一,并在同一主机shell中保存本轮PID、boot id和进程启动tick。跨终端时由工具把这些身份字段存入case metadata并恢复,不能只拿一个旧PID去kill。停止时别发完信号就马上 adb pull,Perfetto 还要写完尾部数据。先核对身份,发 SIGINT 后等待同一进程退出和文件稳定,再 pull;此处是非 detached 的示例。

1
2
3
4
5
6
7
8
9
10
11
12
13
case "$PID" in
''|*[!0-9]*) echo "Invalid perfetto PID" >&2; exit 1 ;;
esac
[ "$PID" -gt 1 ] || exit 1
read_start_ticks() {
proc_stat=$(adb shell "cat /proc/$1/stat") || return 1
printf '%s\n' "$proc_stat" | sed 's/.*) //' | awk '{print $20}'
}
RECORDING_BOOT_ID=$(adb shell cat /proc/sys/kernel/random/boot_id) || exit 1
RECORDING_START_TICKS=$(read_start_ticks "$PID") || exit 1
case "$RECORDING_START_TICKS" in
''|*[!0-9]*) echo "Cannot identify recording process" >&2; exit 1 ;;
esac

上段应紧接启动成功后执行。运行场景结束后,再执行以下停止/拉取步骤;若进程已自动结束,也要通过日志与stats区分正常结束和异常退出。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
CURRENT_BOOT_ID=$(adb shell cat /proc/sys/kernel/random/boot_id) || exit 1
[ "$CURRENT_BOOT_ID" = "$RECORDING_BOOT_ID" ] || exit 1
state=$(adb shell "if [ -d /proc/$PID ]; then echo PRESENT; else echo EXITED; fi") || exit 1
state=$(printf '%s' "$state" | tr -d '\r')
case "$state" in
PRESENT)
CURRENT_START_TICKS=$(read_start_ticks "$PID") || exit 1
[ "$CURRENT_START_TICKS" = "$RECORDING_START_TICKS" ] || exit 1
PROCESS_COMM=$(adb shell "cat /proc/$PID/comm") || exit 1
PROCESS_COMM=$(printf '%s' "$PROCESS_COMM" | tr -d '\r')
[ "$PROCESS_COMM" = "perfetto" ] || exit 1
adb shell "kill -INT $PID" || exit 1
;;
EXITED) ;;
*) exit 1 ;;
esac
attempts=0
while true; do
state=$(adb shell "if [ -d /proc/$PID ]; then echo PRESENT; else echo EXITED; fi") || exit 1
state=$(printf '%s' "$state" | tr -d '\r')
[ "$state" = "EXITED" ] && break
[ "$state" = "PRESENT" ] || exit 1
CURRENT_START_TICKS=$(read_start_ticks "$PID") || exit 1
[ "$CURRENT_START_TICKS" = "$RECORDING_START_TICKS" ] || break
attempts=$((attempts + 1))
[ "$attempts" -lt 60 ] || { echo "Recording process still present" >&2; exit 1; }
sleep 1
done
adb shell '
path=/data/misc/perfetto-traces/field.perfetto-trace
stable=0
prev=0
attempts=0
while [ "$stable" -lt 3 ] && [ "$attempts" -lt 60 ]; do
attempts=$((attempts + 1))
size=$(stat -c %s "$path" 2>/dev/null || echo 0)
if [ "$size" -gt 0 ] && [ "$size" = "$prev" ]; then
stable=$((stable + 1))
else
stable=0
fi
prev=$size
sleep 1
done
[ "$stable" -ge 3 ] || { echo "Trace missing or not stable" >&2; exit 1; }
' || exit 1
adb pull /data/misc/perfetto-traces/field.perfetto-trace

可用inotifyd时,先安装监听再发停止信号,以免漏掉close_write。大小稳定不是close/fsync证明;PID身份检查与kill之间也不是原子操作。长期自动化应由拥有session的服务管理生命周期;身份变更、超时或无法读进程状态时返回待核查,不能默认完整或去killall。

trigger 怎么用

Perfetto trigger 的价值是权限隔离:有权限的一方提前声明 trigger 名称和行为;普通 App 或系统组件只报告“事件发生了”,不能决定抓什么、抓多大、传哪里。

现场方案要把 trigger emitter 写清楚。UI jank 可以由 App 侧 JankStats / FrameMetrics / 自研阈值检测后激活 app_ui_jank,也可以由平台服务或测试 harness 代理激活。无论哪条路,都要做去重和限流,并在 metadata 里记录 trigger source、触发时刻和判断阈值。

App emitter 协议建议固定成一条 JSON 事件,并同时写入同 event_id 的 Track Event:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"clock_domain": "CLOCK_BOOTTIME",
"event_id": "evt-20260504-153012-001",
"trigger_name": "app_ui_jank",
"trigger_source": "app_jankstats",
"page": "Feed",
"action": "scroll",
"reason": "slow_frame",
"threshold_ms": 50,
"observed_value_ms": 83.4,
"window_start_elapsed_ns": 123456700000000,
"window_end_elapsed_ns": 123456789000000,
"dedupe_key": "Feed:scroll:slow_frame:202605041530",
"sample_decision": "record",
"app_state": "foreground"
}

服务端或分析脚本用 event_id 和时间窗口把外部 trigger 记录、trace 内 Track Event、FrameTimeline 慢帧对上。对不上时,这份 Trace 只能当系统侧上下文,不能直接归因到页面或业务动作。

JSON中的sample_decision=record只是App的决策,不是service已接受trigger。event_id标识业务事件,也不是FrameTimeline的frame token;需要明确目标进程、layer与关联规则。CLOCK_BOOTTIME只表示本例已完成时间转换,不能直接把JankStats原始起点塞进elapsed字段。

测试环境可以用下面两种 shell 方法激活 trigger,但上面的 preset 设置了 producer_name_regex: "com\\.example\\.app":shell 工具的 producer 名若不匹配,trigger 会被过滤。测试时应使用匹配的 App producer 激活,或在仅用于实验室的配置里调整这项过滤,不能把命令执行成功当成 trigger 已命中。

1
adb shell /system/bin/trigger_perfetto app_ui_jank

也可以用一段只包含 activate_triggers 的配置激活同名 trigger:

1
2
echo 'activate_triggers: "app_ui_jank"' | \
adb shell perfetto --txt -c -

STOP trigger 适合“根因在触发之前”的问题,比如慢帧、ANR 前兆、音频 underrun。START trigger 适合“事件发生后还要继续观察”的问题,比如温度进入 hot 状态后继续抓 10 秒。

使用 START trigger 时,不要再同时配置普通 duration_ms;触发窗口由 trigger_config 管。

只有确认session启动成功、达到trigger_timeout_ms且没有接受到触发,才能记trigger_matched=false:START/STOP此时不返回trace数据,文件可能为空或不存在。空文件本身也可能来自权限、配置、进程或I/O失败,原因未查清就保留unknown,不能直接归为“没有发生问题”。触发被接受后按stop_delay_ms结束;下一轮需新case id/文件并重新启动,重启间隙也要计入覆盖率。

snapshot 适合调参

有些场景不想停止原 Trace,只想每隔几秒拿一张当前窗口的快照,例如调 CPU policy、thermal 参数、电源策略。--clone-by-name 这个命令行入口是 Perfetto v49.0 加入的;session 克隆能力本身也要 Android 14+ 的平台侧支持或厂商合入,最终以 adb shell perfetto --help / --version 为准。

下面给出可独立保存为thermal.pbtxt的10分钟示例,按秒轮询CPU频率和thermal节点;字段与节点读取仍需设备支持。它不启用STOP trigger,也不周期写文件,因此snapshot读取的是当前Ring窗口:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
unique_session_name: "thermal_snapshot"
duration_ms: 600000
prefer_suspend_clock_for_duration: true

buffers { size_kb: 65536 fill_policy: RING_BUFFER }
data_sources {
config {
name: "linux.sys_stats"
sys_stats_config {
cpufreq_period_ms: 1000
thermal_period_ms: 1000
}
}
}

先确认没有同名session,再启动;成功后按需克隆,原session在10分钟到期前继续运行。每次clone输出应使用新的文件名。以下主机命令需要CLI支持--clone-by-name:

1
2
3
4
adb shell perfetto --query
SNAPSHOT_PID=$(adb shell perfetto --background-wait --txt \
-c - -o /data/misc/perfetto-traces/thermal-final.pftrace < thermal.pbtxt) || exit 1
printf 'snapshot session pid: %s\n' "$SNAPSHOT_PID"

启动成功后运行待测场景,再在需要保留窗口时执行下面两条命令。

1
2
3
4
SNAPSHOT_FILE="thermal-$(date +%Y%m%d-%H%M%S).pftrace"
adb shell perfetto --clone-by-name thermal_snapshot \
-o "/data/misc/perfetto-traces/$SNAPSHOT_FILE" || exit 1
adb pull "/data/misc/perfetto-traces/$SNAPSHOT_FILE" .

clone也会请求flush并消耗额外缓冲/读取资源,不是零扰动快照。过密snapshot可能彼此重叠,不能直接拼成无缝历史;它也无法恢复已被Ring覆盖的事件。要做连续趋势,仍需核对每次窗口的重叠与缺口。

detached mode 少用

--detach 会让 tracing session 脱离 perfetto 命令生命周期,由 traced 服务继续持有 session。官方文档明确不推荐常规使用,因为它容易泄漏 session,让设备长时间处在 tracing 状态。

必须用 detached mode 时,配置里要打开 write_into_file,并准备检查和停止命令:

1
2
3
4
5
6
adb shell perfetto --detach=field_session --txt \
-c /data/misc/perfetto-configs/field.pbtxt \
-o /data/misc/perfetto-traces/field.perfetto-trace

adb shell perfetto --is_detached=field_session
adb shell perfetto --attach=field_session --stop

工程脚本里要有兜底清理:启动前检查旧 session,测试结束后停止 session,超过 TTL 自动停止。

attach/detach的key不是unique_session_name,重新attach还要求同一Unix UID;先adb root再换shell可能改变身份。--is_detached返回0表示可attach、2表示找不到,1是错误,不能把通信失败当不存在。field.pbtxt必须是有数据源、write_into_file和duration_ms的完整配置。

Bugreport 是现场兜底入口

现场问题经常是用户、测试或运维先碰到,随后触发 bugreport。bugreport 保存的是符合条件且当时仍存在的 session。下面是要合并到完整配置的session字段,不是独立配置;例如合并到上面的thermal.pbtxt时,替换原unique_session_name,保留数据源和duration,重新启动后才生效:

1
2
3
unique_session_name: "field_thermal_bugreport"
bugreport_score: 100
bugreport_filename: "field-thermal.pftrace"

bugreport_score > 0 才会成为 bugreport 候选;分数越高,越优先被保存。bugreport_filename 从 Android 15 / Perfetto v42 起可用于 --save-all-for-bugreport 的可读文件名,旧版本会按默认名字保存。它和普通 -o /path/trace.perfetto-trace、--upload 是不同路径:前者服务 bugreport,后两者服务本次命令输出或 framework reporting。

研发或平台脚本可以用这两条命令验证 bugreport 行为:

1
2
3
4
adb shell perfetto --save-for-bugreport

# Alternative, only when supported:
adb shell perfetto --save-all-for-bugreport

Android 12/13 上,bugreport 保存会取走 trace 内容并提前停止 session;Android 14 及以上版本会创建只读 snapshot,原 session 可以继续运行。报告里要写清 Android 版本和验证命令输出,不要把 bugreport 合包当成普通后台 trace 的等价路径。

两条save命令是按设备能力选择的不同入口,不要求连续执行;--save-for-bugreport选最高分,支持的--save-all-for-bugreport保存全部符合条件者。保存到设备bugreport目录不等于已经生成或上传bugreport ZIP。正的bugreport_score还让session具备被其他UID克隆的资格,应按可进入bugreport的数据范围设计。

现场证据包里应该有什么

只拿 .perfetto-trace 不够。现场证据包至少要能回答“这是什么场景、什么时候触发、文件是否完整”。

1
2
3
4
5
6
7
case-20260504-153012/
trace.perfetto-trace
config.pbtxt
metadata.json
stats.sql.txt
log_excerpt.txt
summary.json

metadata.json 建议包含这些字段:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"clock_domain": "CLOCK_BOOTTIME",
"case_id": "case-20260504-153012",
"trace_config": "ui_jank_flight_recorder_v3",
"trigger": "app_ui_jank",
"trigger_source": "app_jankstats",
"trigger_elapsed_realtime_ns": 123456789000000,
"trigger_wall_time": "2026-05-04T15:30:12+08:00",
"trace_start_elapsed_realtime_ns": 123436789000000,
"trace_end_elapsed_realtime_ns": 123457790000000,
"boot_id": "device_boot_id",
"device": "device_name",
"build_fingerprint": "fingerprint",
"app_version": "1.2.3",
"battery_percent": 78,
"thermal_state": "nominal",
"upload_reason": "slow_frame"
}

这里的 metadata 不替代 trace,它给排查者定位问题窗口、过滤版本、判断环境差异。第 13 篇已经讲过 App 侧如何补页面、业务阶段和用户操作;现场证据包里的 metadata 要负责把这些业务 marker 对上。

summary.json 则是自动化入口,字段要能直接驱动 triage、上传和留存:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
"clock_domain": "CLOCK_BOOTTIME",
"case_id": "case-20260504-153012",
"preset_id": "ui_jank_flight_recorder_v3",
"trigger_name": "app_ui_jank",
"trigger_source": "app_jankstats",
"trigger_ts_elapsed_ns": 123456789000000,
"trace_start_ns": 123436789000000,
"trace_end_ns": 123457790000000,
"pre_trigger_window_ms": 20000,
"post_trigger_window_ms": 1001,
"trigger_matched": true,
"file_complete": true,
"stats_status": "warning",
"affected_sources": ["linux.ftrace"],
"usable_metrics": ["frame_timeline"],
"unusable_metrics": ["main_thread_sched"],
"evidence_grade": "B",
"privacy_mode": "log_tag_whitelist",
"upload_mode": "summary_first",
"conclusion_level": "probable",
"next_action": "collect_short_irq_preset",
"sampling_policy_version": "2026-05-04",
"sample_rate": 1.0,
"skip_probability": 0.0,
"sample_decision": "record",
"quota_bucket": "ui_jank_daily",
"quota_remaining": 8,
"upload_allowed": true,
"upload_block_reason": "",
"retention_until": "2026-05-07T15:30:12+08:00"
}

上述JSON是已完成独立验收后的假设记录:20秒前窗、约1秒尾窗,不是默认值或从文件大小推导的结果。trigger_matched、file_complete、usable_metrics与upload_allowed分别需要证据;未核实保留null/unknown,不能自动填true。最早和最晚事件包围窗口仍不证明中间完整。A/B/C/D只是报告策略,B的核心判断可用需独立证明,不能仅凭loss数量较小。

长Trace要写清clock domain。Android上的ftrace常用CLOCK_BOOTTIME;日志原始wall time进入解析器后可能已归一,不能再手动重复加offset。JankStats/FrameMetrics来源也不能只改字段名就当elapsed realtime。外部JSON不由Trace Processor自动转换,需要同一次开机的时钟配对与trace内marker核对,wall time还可能受校时影响。

外部 metadata 至少同时记录 elapsed realtime、wall time 和 boot id;更稳的做法是把 trigger 本身也写成 trace 内 Track Event。分析前如果看到 clock sync failure 或 invalid clock snapshot,跨数据源同步要降级处理。

裁剪优先发生在采集侧

Perfetto Trace 里有增量状态、track descriptor、stats、metadata。事后硬切二进制文件,很容易破坏解析。推荐顺序是:

  • 用 Ring Buffer 控制“只保留最近窗口”。
  • 用 stop_delay_ms 控制触发后保留多久。
  • 在write_into_file模式用max_file_size_bytes限制文件增长;触及上限会结束录制,可能早于问题发生,不能用于离线裁剪。
  • 上传完整问题窗口的原始 Trace。
  • 服务端生成 summary、截图、SQL 结果,作为轻量索引。

如果必须离线裁剪,工具要按 TracePacket 重写,并保留必要 descriptor 和 stats。不要用 dd、文本截断、随机切 protobuf 字节流。

上传和清理策略

现场长 Trace 接近真实用户环境,上传策略不能只考虑研发便利:

  • 默认只在 Wi-Fi、充电或用户授权条件下上传。
  • 文件超过阈值时先上传 summary,原始 trace 留在本地等待人工导出。
  • log 按 tag 白名单采集,并在上传前脱敏。
  • trace 文件设置 TTL,例如 3 天自动清理。
  • trigger 同时使用 TraceConfig 的 max_per_24_h 和客户端限流。
  • 上传前跑 stats,把 data loss 写进 metadata。
  • 不允许服务端下发任意 text proto 配置到用户设备,只允许选择审核过的 preset。

这些限制会减少临时调参空间,但能控制上传、隐私和稳定性风险。

分析前固定检查

拿到现场文件后,先确认 Trace 覆盖了触发点前后的目标时间,再查 stats 中与该场景相关的数据源。录制进程活了几小时,不等于文件里保留了几小时的有效事件。

1
2
SELECT trace_start() AS trace_start_ns, trace_end() AS trace_end_ns,
trace_dur() / 1e9 AS trace_span_s;

如果时长不符合预期,先查 trigger_timeout_ms、max_file_size_bytes、后台进程是否被杀、文件是否还没 close、duration_ms 是否按 suspend 语义计算。数据不完整时,报告要写明哪些判断不能下。

再跑全局质量检查。stats 体检的完整查询和“常见项 → 处置决策”的映射表第 12 篇已经给过,把那条 SQL 放进分析脚本开头直接复用即可,这里不重复。现场长 Trace 要在它之上多做两层。

先是 per-buffer 检查。traced_buf_* 的 idx 对应 buffer 下标;下面同时列出的全局 flush/config 项不能按 buffer 编号解释:

1
2
3
4
5
6
7
8
9
10
11
12
13
SELECT name, idx, severity, source, value
FROM stats
WHERE value != 0
AND (
name GLOB 'traced_buf_*'
OR name IN (
'traced_flushes_failed',
'traced_final_flush_failed',
'config_write_into_file_no_flush',
'config_write_into_file_discard'
)
)
ORDER BY idx, name;

RING_BUFFER 下的 traced_buf_chunks_overwritten 不一定是错误,它通常表示窗口外的旧数据被覆盖。要单独看它是否把 trigger 前根因覆盖掉:

1
2
3
4
5
SELECT name, idx, severity, source, value
FROM stats
WHERE name = 'traced_buf_chunks_overwritten'
AND value != 0
ORDER BY idx;

如果现场打开 ftrace,还要记录 ftrace clock、可用事件和 setup error。跨 trace 比较时,clock 或事件集不同,会直接影响 sched/freq 结论可信度:

1
2
adb shell cat /sys/kernel/tracing/trace_clock
adb shell cat /sys/kernel/tracing/available_events | head

把偶发问题变成证据

一次偶发问题的证据包至少要能回答:触发点在哪、触发前事件保留了多久、文件是否完成写入、哪些数据源发生丢失。缺任何一项,报告都应缩小结论范围。App 侧 Track Event 可标记业务触发点,系统 Trace 再解释触发前后发生了什么。

参考文档

  1. Trace configuration
  2. Buffers and dataflow
  3. Tracing in Background
  4. Running perfetto in detached mode
  5. Perfetto command-line reference
  6. TraceConfig proto reference
  7. Android boot tracing
  8. FrameTimeline
  9. ATrace
  10. Android Log
  11. Clock synchronization
  12. Trace Processor Stats

原文源码基线为b23c67be(2026-09-19),保留如下。本次另核对 v58.3 init规则、CLI实现、TraceConfig、service写入/flush 与 v49变更记录。

关于我 && 博客

欢迎关注 Android Performance。

CATALOG
  1. 1. Perfetto 系列文章
  2. 2. 长 Trace 先设计证据窗口
  3. 3. 现场采集先受设备和权限限制
  4. 4. Boot Trace 是特殊现场窗口
  5. 5. 三种现场长 Trace 模式
  6. 6. Ring Buffer 的基线配置
  7. 7. 长录制要周期写文件
  8. 8. 后台运行和安全停止
  9. 9. trigger 怎么用
  10. 10. snapshot 适合调参
  11. 11. detached mode 少用
  12. 12. Bugreport 是现场兜底入口
  13. 13. 现场证据包里应该有什么
  14. 14. 裁剪优先发生在采集侧
  15. 15. 上传和清理策略
  16. 16. 分析前固定检查
  17. 17. 把偶发问题变成证据
  18. 18. 参考文档
  19. 19. 关于我 && 博客