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

现场抓取要先确定触发点前后各保留多久,再选 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 triggerApp marker、FrameTimeline 覆盖目标窗口、触发前窗口足够
ANR 前兆Ring Buffer + STOP trigger主线程、Binder、锁等待、I/O 和关键业务阶段同时在场
温升降频write_into_file 或 snapshotCPU freq、idle、thermal 状态和 App 关键阶段按分钟级趋势保留
业务 timeoutApp marker + STOP/START trigger要保留 timeout 前后用 STOP 并留足 stop_delay;仅需事后窗口时才用 START
音频 underrunRing Buffer + STOP triggeraudio/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 前兆、音频 underrunBuffer 太小会覆盖根因;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。