EN

Android Perfetto 系列 13:Perfetto SDK、Track Event 与 App 现场 Trace

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

系统 Trace 能显示线程、CPU、帧和 Binder 等系统事件;播放器的 frame id、游戏 scene 名称或业务队列里的等待时间,需要应用自己提供。缺少这些标记时,一段主线程耗时只能定位到系统活动,难以对应业务阶段。

Perfetto SDK 的 Track Event 可以记录解码、纹理上传、队列深度和跨线程任务 ID。与系统轨道放在同一个时间窗口后,能先找到业务候选阶段,再用 RenderThread、GPU 和 FrameTimeline 验证它是否影响了可见帧。

接入前要先定事件名称、参数单位和采样频率。否则埋点虽然能显示在 UI 中,后续 SQL 仍无法稳定地按业务阶段聚合。

版本说明(2026-10 核查):本文 C++ SDK、类别优先级和触发器以 Perfetto v58.3 为核查基线;AndroidX tracing-perfetto 按 1.0.0 的职责说明。设备上的 tracing service、App SDK 和分析端 Trace Processor 可来自不同版本,需分别记录。示例参数供实验室起步使用,不代表所有 Android 设备或线上环境都支持。

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 系统优化分享

什么时候需要业务语义

没有业务语义缺口时,不需要接 SDK。先按场景选工具:

场景 建议
Java/Kotlin 层临时标记函数耗时 用 android.os.Trace 或 AndroidX tracing,抓取时打开应用 atrace
Android native / C++ 模块要长期埋点 用 Perfetto SDK 的 Track Event
跨平台引擎、游戏、播放器、Camera pipeline 用 Track Event,加稳定参数和 counter
要输出复杂结构化状态,普通 slice/counter 不够 再考虑自定义 DataSource
只想知道系统线程状态、Binder、频率 先用系统数据源,没业务语义缺口时不用接 SDK

业务事件与系统事件同窗查看

示意图:system backend 会话将 App 业务事件与独立系统数据源放在同一 Trace 中。

Android-only 场景里,如果 android.os.Trace 和 NDK ATrace_* 已经够用,官方也建议继续使用它们:这类事件会进入 Perfetto 的 atrace 路径,适合普通 App 函数标记,抓取时要在 linux.ftrace 里配置 atrace_apps: "com.example.app",或通过命令行 -a com.example.app 打开对应 App。SDK 仍然适合 Android 的 native、跨平台和结构化业务语义场景;简单 Android-only section 不必为了形式替换 ATrace。

Perfetto SDK 更适合 native 模块和跨平台模块。它直接产生 Track Event,支持 category、slice、counter、flow、参数、独立 track,也方便和系统 Trace 放在同一个时间轴上。本文示例使用 C++ SDK。上游仓库还包含 Java 接口源码 和 Rust SDK,不能再把“官方只有 C/C++”作为选型前提。不过 v58.3 的 src/android_sdk 中,PerfettoTrace 标有 @hide,并依赖 JNI 与平台相关注解;有源码不等于普通 App 已有稳定公开的 Java API 或可直接引入的发布包。Java/Kotlin 项目应先确认库的发布、native 链接和兼容合同;简单 section 继续用 android.os.Trace,需要 SDK 能力时再评估已有封装。

App 侧 tracing 能力先按边界选:

能力 典型用途 版本和现场边界
android.os.Trace / AndroidX Trace Java/Kotlin 粗粒度 section 同步 section 从 API 18 提供;release App 的可采集条件需结合系统版本、debuggable/profileable 和采集工具核对,采集侧打开 atrace_apps
NDK ATrace_* native 粗粒度 section 同步 section 从 API 23、async/counter 从 API 29 提供;旧设备需 API 可用性保护
AndroidX tracing-perfetto 向 Perfetto SDK 写入低开销事件,配合外部采集工具启用 1.0.0 支持预先配置后的启动期初始化;本身不授予 App 系统 trace 的读取权限
Perfetto SDK kSystemBackend native / 跨平台模块写 Track Event 到系统 Trace Android 9 起平台集成 traced;仍需核对具体设备是否启用、producer socket 与 consumer 权限

ATrace 也有开销。热循环、每次锁尝试、每个对象都打 android.os.Trace / ATrace_*,会让 JNI、trace_marker 和内核路径本身扰动结果。Java/Kotlin 和 NDK ATrace 更适合粗粒度 section;高频业务状态优先用 SDK category gating、sampling,或者默认关闭的 debug category。

SDK 接入边界

Perfetto SDK 里有两层能力:

能力 适合表达 代价
Track Event 函数耗时、业务阶段、队列长度、frame id、请求 id、跨线程关系 接入成本低,Trace Processor 和 UI 原生支持
Custom DataSource 自定义 protobuf 状态、高频结构化数据、专用二进制格式 需要维护 schema,通常还要给 Trace Processor 补解析

只要 slice、counter、flow 和参数能表达问题,优先用 Track Event。自定义 DataSource 的门槛更高,不适合作为第一版埋点方案。

自定义 DataSource 适合两类情况:一类是普通 slice、counter 和 debug annotation 表达不了结构,比如要周期性转储一个子系统状态;另一类是数据量太大,需要强类型 schema 减少每条事件的体积。

自定义 protobuf 还要维护解析与查询接口。现有 slice、counter、flow 和参数能回答问题时,Track Event 的维护成本更低。

业务阶段字典先于代码

Track Event 不是把宏塞进每个函数。我更愿意先把业务阶段字典定下来,再写代码:事件叫什么、属于哪个阶段、字段单位是什么、缺字段时怎么降级,后续 SQL 和报告都要靠它。

event_name category phase 必填参数 可选参数 单位/基数 采样 报告指标
DecodeFrame player decode frame_id、stream_id、codec width、height frame_id 在 stream_id 内唯一 每帧一次,debug 字段按需开 decode_dur_ms、decode_max_ms
UploadTexture rendering upload frame_id、texture_bytes surface_id texture_bytes 用 bytes 每帧最多一次 upload_dur_ms、upload_bytes
RenderSubmit rendering submit frame_id、surface_id queue_depth queue_depth 用 items 每帧一次 submit_dur_ms、queue_depth_items
WaitForBuffer camera wait request_id、buffer_queue producer request_id 在 session 内唯一 只在等待超过阈值时记录 wait_for_buffer_ms

字段改名、删字段、改单位,都要提升 arg_schema_version。长期报告字段不要叫 debug.frame_id,而应叫业务 schema 里的 frame_id / request_id,并记录 frame_id_domain、nullable_policy 和兼容策略。缺 RenderSubmit 时,报告只能输出 decode/upload 阶段,不能写端到端结论;字段里应写 missing_marker=RenderSubmit、evidence_grade=partial。

后文三阶段 SQL 还要求每个阶段携带同类型的 session_id/stream_id/frame_id,不能只给 DecodeFrame 写完整身份。WaitForBuffer 若等结束后才判断阈值,需要保存真实起止时间,并用正确时钟域回填;临时在结束处包一个 scope,测到的是打点耗时。

两种 backend 解决不同问题

Perfetto SDK 可以用 in-process backend,也可以用 system backend:

Backend 谁控制 Trace 适合场景
kInProcessBackend App 自己创建 tracing session 单进程验证、离线测试、只看业务事件
kSystemBackend 外部 perfetto 命令或系统服务控制 和 sched、freq、Binder、FrameTimeline 合并分析

Android 性能分析里更常用 system backend。本例让 App 只做 producer,由有权限的外部 consumer 控制系统 tracing session。连接 producer socket 不等于有权限读取系统 Trace;普通 App 不能据此获取其他进程的数据。SDK 本身也有 consumer API,能否使用 system backend 的读取能力取决于平台权限,不能把角色约束误写成 API 不存在。

以下系统采集示例以 Android 12+ 的 FrameTimeline 数据源为前提,仍需核对设备支持情况;SDK 的 system backend 并非从 Android 12 才出现。线上接入还要单独评估包体、初始化开销和开关策略。

最小接入骨架

最小接入只解决三件事:稳定 category、system backend、可查询事件名。native 模块接入骨架如下。

1
2
3
4
5
6
7
8
9
10
11
12
13
// tracing_categories.h
#pragma once

#include <perfetto.h>

PERFETTO_DEFINE_CATEGORIES(
perfetto::Category("rendering")
.SetDescription("Rendering pipeline"),
perfetto::Category("player")
.SetDescription("Media pipeline"),
perfetto::Category("pipeline.debug")
.SetDescription("Verbose pipeline events")
.SetTags("debug"));

头文件只声明 category。category 名会进入 Trace 和后续 SQL,名字要稳定,不要把动态 id、页面实例号或请求号塞进 category 名里。

1
2
3
4
// tracing_categories.cc
#include "tracing_categories.h"

PERFETTO_TRACK_EVENT_STATIC_STORAGE();

PERFETTO_TRACK_EVENT_STATIC_STORAGE() 给 Track Event 注册需要的静态存储留位置。它只应该出现在一个 .cc 文件里,避免多重定义。

1
2
3
4
5
6
7
8
9
10
11
12
13
// tracing_init.cc
#include "tracing_categories.h"
#include <mutex>

void InitPerfetto() {
static std::once_flag once;
std::call_once(once, [] {
perfetto::TracingInitArgs args;
args.backends |= perfetto::kSystemBackend;
perfetto::Tracing::Initialize(args);
perfetto::TrackEvent::Register();
});
}

初始化阶段选择 backend,并把前面定义的 category 注册给 Track Event。Android 系统 Trace 场景里通常用 kSystemBackend,这样 App 事件才能和系统 sched、Binder、FrameTimeline 放在同一份 Trace 里。

之后就能在业务代码里打点。这段用 slice 表示耗时,用参数记录 frame id:

1
2
3
4
void DecodeFrame(int frame_id) {
TRACE_EVENT("player", "DecodeFrame", "frame_id", frame_id);
DecodeFrameImpl(frame_id);
}

TRACE_EVENT 是作用域事件。进入当前作用域时开始,离开当前作用域时结束。它适合包住一段同步工作,例如 decode、layout、upload、submit。

不跟随函数作用域的事件,用 TRACE_EVENT_BEGIN 和 TRACE_EVENT_END。这对跨多个函数的阶段有用,但不要把 begin/end 分散到完全不相关的调用路径里,容易造成同线程 slice 嵌套混乱、闭合错配或 SQL 解释困难。

接 SDK 时还要留一个构建层面的边界。官方 C++ SDK 是 C++17 库,发布包里常见形态是 perfetto.h 和 perfetto.cc 两个合并版源文件,适合塞进已有 native 构建系统。

只放进 perfetto.h 还不够:要确认编译标准、线程库、符号裁剪、包体增量,以及 App 进程启动早期是否已经完成 Tracing::Initialize()。

perfetto.h 与 perfetto.cc 要取自同一 SDK 发布包,并把后者编译链接进目标;不要混用不同版本的头文件与实现。上面的 std::call_once 只保护本模块入口,整个进程内的其他库也应共用初始化策略。

普通初始化路径中,Track Event 要等数据源启用才开始记录。v58.3 另有 SetupStartupTracingBlocking 这一显式 startup-tracing API,不能把它当作普通 Initialize 的默认行为。AndroidX tracing-perfetto 1.0.0 可在外部工具预先配置后,于 App 启动时初始化埋点;它不独自采集 zygote、ActivityTaskManager 或首帧呈现。冷启动分析仍需同时开启对应系统数据源。

初始化时机和进程边界要一起定。Tracing::Initialize() 全进程只做一次,放在进程入口的确定路径上(比如 JNI_OnLoad 或 Application#onCreate 触发的 so 加载),并做好幂等保护;注册之前发出的 Track Event 会被静默丢弃,不报错,事后很难和真丢包区分。多进程 App 的每个进程都要各自 Initialize + Register,:remote、:player 这类子进程不会继承主进程的初始化。system backend 下,进程在 tracing session 已经开始后才启动也没关系:producer 连上 traced 之后,符合配置的数据源会被自动启用,只是连接之前的事件不存在,分析时不要把这段空白当成业务空闲。

category 是线上开关

category 决定哪些事件会被打开。建议把它当成配置接口设计,不要随手起名。C++ SDK(perfetto::Category)里没有命中任何规则时,非 debug、非 slow category 默认会被打开;C SDK(PerfettoTeCategory)的默认行为相反,未命中规则的 category 默认关闭。

线上 preset 的主规则很简单:显式 disabled_categories: "*",再白名单打开需要的 category。这样可以避开 C/C++ 默认差异,也能避免 debug category 在现场意外打开。debug 和 slow tag 默认关闭,专项分析时再显式打开。

规则有优先级:精确 enabled category 先于 disabled tag 判断,因此显式放行一个带 debug tag 的类别,仍会把它打开。这个 allowlist 是事件开关控制,不是不可绕过的安全边界。

常见划分方式:

  • player:播放器主阶段,例如 prepare、decode、render。
  • rendering:渲染提交、纹理上传、场景切换。
  • camera:request、HAL callback、buffer queue。
  • pipeline.debug:调试用高频事件,定义 category 时加 debug tag。
  • pipeline.slow:开销较高的事件,定义 category 时加 slow tag。

category 应按子系统和开关粒度设计,不按页面、实验组、请求类型命名;页面、实验组、请求类型放参数或 metadata,避免 category 数量膨胀。

以下配置明确选择 category:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
buffers {
size_kb: 65536
fill_policy: RING_BUFFER
}

data_sources {
config {
name: "track_event"
target_buffer: 0
track_event_config {
disabled_categories: "*"
enabled_categories: "player"
enabled_categories: "rendering"
}
}
producer_name_filter: "com.example.app"
}

这样做的好处是,现场抓 Trace 时不必换包,只改配置就能决定打开哪些业务事件。system backend 下 track_event 可能来自多个 producer,现场或线上 preset 要用 producer_name_filter / regex 把范围收住。示例里的 com.example.app 只是占位;先从 trace、data source 或 producer 列表确认实际 producer name,多进程 App 用多个 exact filter 或 regex filter。

和系统 Trace 一起抓

业务事件只解释“业务正在做什么”。系统事件解释“这段业务为什么慢”。合抓时,一般把 track_event 和 ftrace 放在同一份配置里:

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
buffers { size_kb: 16384 fill_policy: RING_BUFFER } # 0: sched / ftrace
buffers { size_kb: 4096 fill_policy: RING_BUFFER } # 1: app track event

data_sources {
config {
name: "linux.ftrace"
target_buffer: 0
ftrace_config {
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: "binder_driver"
atrace_apps: "com.example.app"
}
}
}

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

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

duration_ms: 10000

这里两个 central buffer 合计 20 MiB;原示例 160 MiB 会超出 v58.3 启用 extra guardrails 时默认的 128 MiB 总量限制。20 MiB 也不保证留存 10 秒,应按写入速率和 stats 调整,per-CPU ftrace buffer 另算。把这段完整配置保存为 app-sdk.pbtxt,替换 App 包名和实际 producer 名称后,在授权测试设备上执行:

1
2
3
adb shell perfetto --query
adb shell perfetto --txt -c - -o /data/misc/perfetto-traces/app-sdk.perfetto-trace < app-sdk.pbtxt
adb pull /data/misc/perfetto-traces/app-sdk.perfetto-trace .

第二条命令前台运行 10 秒,期间在设备上触发待测业务;确认采集成功后再 pull。--query 用于核对当前注册的数据源和 producer,目标进程还未启动时不一定出现在列表中。系统版本缺少数据源、权限被拒或同路径已有旧文件时,不能把 pull 到文件当成采集成功。

抓完后,用 SQL 确认事件进来了。这条 SQL 用第 11 篇讲过的 thread_slice 视图,直接把进程名、线程名和业务参数查出来。thread_slice 是 slices.with_context 提供的视图,已经把 slice、track、thread、process 关联好;单篇阅读时只要保留前面的 INCLUDE 即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
INCLUDE PERFETTO MODULE slices.with_context;

SELECT
id AS slice_id, upid, utid, ts AS ts_ns, dur AS dur_ns,
ROUND(ts / 1e6, 3) AS ts_ms,
CASE WHEN dur >= 0 THEN ROUND(dur / 1e6, 3) END AS dur_ms,
name,
thread_name,
process_name,
EXTRACT_ARG(arg_set_id, 'debug.frame_id') AS frame_id
FROM thread_slice
WHERE process_name = 'com.example.app'
AND name IN ('DecodeFrame', 'RenderScene', 'UploadTexture')
ORDER BY ts;

这条查询适合默认线程 track 上的 Track Event 或 atrace slice。独立 track、process track 事件不一定有 utid,可能不会出现在 thread_slice 里;这类事件要改用 process_slice、thread_or_process_slice,或直接从 slice JOIN track 查,再按 track.name/parent_id 还原上下文。

这条 SQL 的价值不止是“查到了事件”,它还能继续和 thread_state、CPU 频率、Binder 事件、FrameTimeline 做时间范围关联。TrackEvent slice 是业务时间轴证据,不等于 CPU 一直在执行这段业务;CPU 执行要再关联 sched / thread_state,并区分默认 ThreadTrack、自定义 Track 和跨线程 flow。普通 key/value 参数会作为 debug annotation 进入 args,SQL 用 debug.<key> 读取;typed TrackEvent 字段不走这个 debug.* args 口径,需要对应解析、表或专用字段。

时间范围关联只是第一步。App 的 frame_id 是业务帧,FrameTimeline 的 frame/vsync 是系统帧;只靠时间重叠容易把排队、预渲染、跨线程工作归到错误帧。最终要结合 Choreographer frame/vsync、JankStats frame start、RenderThread/HWUI slice、actual_frame_timeline_slice / expected_frame_timeline_slice 再确认。

这里的 frame_id 是 debug annotation,适合排查和临时 SQL。debug annotation 默认是调试字段;如果进入长期指标,要把字段名、类型、单位、缺省值和迁移策略当成接口冻结。只有能控制 Perfetto proto、解析和发布流程时,再考虑 typed TrackEvent 字段或自定义 DataSource。现场 preset 可用 filter_debug_annotations / filter_dynamic_event_names 减少部分内容,但不是完整脱敏;前者也会移除这里 SQL 依赖的 ID,报告必须按 missing_identity 降级。

业务阶段报告必须按进程、session、stream、frame 组合键检查三个必需 marker,不能只看见 RenderSubmit 就标完整。以下查询要求三个阶段都写入 session_id/stream_id/frame_id;前面的最小单点示例只有 frame_id,需要先补齐参数。缺身份字段的事件应单列为 missing_identity,不要与其他空 ID 事件合并。

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
INCLUDE PERFETTO MODULE slices.with_context;

WITH app_events AS (
SELECT
id, upid, thread_name, name AS phase, ts, dur,
EXTRACT_ARG(arg_set_id, 'debug.session_id') AS session_id,
EXTRACT_ARG(arg_set_id, 'debug.stream_id') AS stream_id,
EXTRACT_ARG(arg_set_id, 'debug.frame_id') AS frame_id
FROM thread_slice
WHERE process_name = 'com.example.app'
AND name IN ('DecodeFrame', 'UploadTexture', 'RenderSubmit')
),
frame_quality AS (
SELECT
upid, session_id, stream_id, frame_id,
CASE
WHEN SUM(phase = 'DecodeFrame') = 1
AND SUM(phase = 'UploadTexture') = 1
AND SUM(phase = 'RenderSubmit') = 1
AND MIN(dur) >= 0 THEN 'complete'
ELSE 'partial_or_duplicate'
END AS evidence_grade
FROM app_events
WHERE session_id IS NOT NULL AND stream_id IS NOT NULL AND frame_id IS NOT NULL
GROUP BY upid, session_id, stream_id, frame_id
)
SELECT
e.upid, e.session_id, e.stream_id, e.frame_id, e.phase,
e.id AS slice_id, e.ts AS start_ns, e.dur AS raw_dur_ns,
ROUND(e.ts / 1e6, 3) AS start_ms,
CASE WHEN e.dur >= 0 THEN ROUND(e.dur / 1e6, 3) END AS dur_ms,
e.thread_name,
COALESCE(q.evidence_grade, 'missing_identity') AS evidence_grade
FROM app_events e
LEFT JOIN frame_quality q USING (upid, session_id, stream_id, frame_id)
ORDER BY e.upid, e.session_id, e.stream_id, e.frame_id, e.ts;

这里的 complete 只表示业务 marker 数量和闭合状态符合本例契约,不证明帧已经显示。下面是另加 FrameTimeline 关联和缺项展开后的报告示意,并非上述 SQL 的直接输出:

这也不检查阶段时序、采样覆盖或版本混用;整个 frame 都没打点时,本查询不会产生一行“缺失帧”。要统计漏帧或端到端覆盖率,还需要独立的预期帧清单与身份映射。

1
2
3
4
trace_name,scenario,frame_or_request_id,phase,start_ms,dur_ms,thread_name,frame_jank_type,evidence_grade,missing_marker
run01.perfetto-trace,feed_scroll,1082,DecodeFrame,1240.2,5.8,decoder-1,jank,partial_or_duplicate,
run01.perfetto-trace,feed_scroll,1082,UploadTexture,1248.7,9.1,RenderThread,jank,partial_or_duplicate,
run01.perfetto-trace,feed_scroll,1082,RenderSubmit,,,,jank,partial,RenderSubmit

跨线程任务用 flow 或独立 track

很多业务慢不在单个函数里,而在队列之间。比如 UI 线程提交一个请求,decoder 线程处理,render 线程消费。只用同线程 slice,读者很难看出它们属于同一个 frame。

可以用 flow 把相关事件连起来。下面在入队前分配 token,把同一个 FrameToken 随任务传给后续线程;不要在每个阶段重新分配,也不要把容易复用的 frame_id 或哈希直接当作唯一 ID。这里只展示埋点封装,实际队列负责传递 token;三个 callable 分别包住真实的入队、解码和消费工作。分配器应全进程唯一,不能在每个 so 中各放一份,且不得回绕复用:

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
#include <atomic>
#include <cstdint>
#include "tracing_categories.h"

struct FrameToken {
uint64_t flow_id;
uint64_t session_id;
uint64_t stream_id;
uint64_t frame_id;
};

FrameToken AllocateFrameToken(uint64_t session, uint64_t stream, uint64_t frame) {
static std::atomic<uint64_t> next{1};
return {next.fetch_add(1, std::memory_order_relaxed), session, stream, frame};
}

template <typename Work>
void EnqueueFrame(const FrameToken& t, Work&& enqueue) {
TRACE_EVENT("player", "EnqueueFrame", perfetto::Flow::ProcessScoped(t.flow_id),
"session_id", t.session_id, "stream_id", t.stream_id,
"frame_id", t.frame_id);
enqueue();
}

template <typename Work>
void DecodeFrame(const FrameToken& t, Work&& decode) {
TRACE_EVENT("player", "DecodeFrame", perfetto::Flow::ProcessScoped(t.flow_id),
"session_id", t.session_id, "stream_id", t.stream_id,
"frame_id", t.frame_id);
decode();
}

template <typename Work>
void RenderFrame(const FrameToken& t, Work&& consume) {
TRACE_EVENT("player", "RenderFrame",
perfetto::TerminatingFlow::ProcessScoped(t.flow_id),
"session_id", t.session_id, "stream_id", t.stream_id,
"frame_id", t.frame_id);
consume();
}

选中事件时,Perfetto UI 会用箭头展示关系。中间阶段继续使用 Flow,最终消费阶段再用 TerminatingFlow。

这里用的是 ProcessScoped(flow_id),所以 id 至少要在进程内、一次 Trace 生命周期内稳定,不要直接拿容易复用的临时指针当 flow id;跨进程 flow 不要继续用 ProcessScoped 语义,至少要使用全局唯一 id,并明确 namespace 和来源进程。多阶段 pipeline 也可以给每条边单独分配 flow id,例如 enqueue_to_decode_flow_id、decode_to_render_flow_id,避免一条 flow 被多条路径复用。

如果一个任务跨函数、跨线程持续很久,也可以放到独立 track 上:

1
2
3
4
5
6
7
8
9
10
11
12
13
void StartRequest(uint64_t request_id) {
perfetto::Track track(request_id);
auto desc = track.Serialize();
desc.set_name("player.request");
perfetto::TrackEvent::SetTrackDescriptor(track, desc);

TRACE_EVENT_BEGIN("player", "Request", track,
"request_id", request_id);
}

void FinishRequest(uint64_t request_id) {
TRACE_EVENT_END("player", perfetto::Track(request_id));
}

这类事件适合任务队列、播放器 pipeline、异步加载、跨线程 GPU 提交。它比“每个函数都打点”更能解释业务路径。

同一 track 上的 begin/end 仍按栈闭合;并发且非嵌套的任务要使用不同 track,取消和异常路径也要配对结束。v58.3 的 Track(id) 默认以进程 track 为父级并派生 UUID,id=0 会与父级冲突;专用 ID 仍需在该命名空间内唯一。

高基数任务结束且不再写入后,可用 TrackEvent::EraseTrackDescriptor(track) 清理 SDK 内的自定义 descriptor,避免长期运行时注册表持续增长;这不会删掉已经写入 trace 的历史事件。

perfetto::Track(request_id) 里的 id 要在一次 Trace 内对这个并发任务唯一。线上 request id、frame id 很容易复用,复用后不同任务会合到同一条 track,看起来像一个长任务或错误串行。更稳的做法是加 session/pipeline namespace,或者生成专用 64-bit track id;需要长期阅读时,补 track descriptor / name,让 UI 和 SQL 都能识别生命周期。descriptor / interning 丢失时,要回到第 12 篇的 stats 检查。

Counter 只放状态,不放日志

counter 适合随时间变化的数值,例如队列长度、in-flight 请求数、buffer 占用。frame id 是标识符,不是可聚合指标;它更适合放在 slice 参数或 flow id 里。这个例子记录 decode 队列深度:

1
2
3
4
5
void ReportDecodeQueueDepth(int depth) {
TRACE_COUNTER("player",
perfetto::CounterTrack("DecodeQueueDepth", "items"),
depth);
}

counter 不适合承载日志文本,也不适合拿标识符做 avg/max。日志放 logcat,Trace 里只保留能和时间轴关联、可以被解释为状态的数值。

counter 要固定单位和聚合口径。上例实际 track 名是 DecodeQueueDepth,items 是 unit_name,并不会自动拼到名字上。队列深度的窗口均值应按状态保持的时长加权,不能直接平均稀疏样本;窗口前没有已知初始值的部分保持 unknown。InFlightRequests 看峰值和持续时间,BufferBytes 看峰值、增长斜率和是否回落;标识符不能求 avg/max。

事件名是 SQL 接口

事件名一旦进了 SQL、看板和回归报告,就变成了接口。不要把动态 id 拼进事件名。

1
2
3
4
5
// 不建议:每个 frame 都会生成不同事件名,SQL 很难稳定统计。
TRACE_EVENT("player", perfetto::DynamicString{"DecodeFrame_123"});

// 建议:事件名稳定,动态信息放参数。
TRACE_EVENT("player", "DecodeFrame", "frame_id", frame_id);

更好的命名方式是“阶段 + 动作”:

  • DecodeFrame:解码一个业务帧,参数带 frame_id、stream_id、codec。
  • UploadTexture:上传纹理或 buffer,参数带 frame_id、texture_bytes。
  • RenderScene:提交一轮场景渲染,参数带 scene_id 或 surface_id。
  • SubmitRequest:提交一个跨线程请求,参数带 request_id 和 queue_depth。
  • WaitForBuffer:等待上游 buffer,可和 Binder、线程状态、buffer queue 证据关联。

事件名稳定以后,后面的 SQL 才能稳定。耗时列统一用 / 1e6 换算:time.conversion 的 time_to_ms() 是整数除法,会把最大耗时截断成整毫秒,和平均值不在一个精度上:

下面按 upid/utid 分组,避免同名进程重启或同名线程混到一起;统计范围是整份 trace 内已闭合的匹配 slice,不代表某次操作或总体帧分布。专项窗口需另加时间与身份筛选,并单独报告未闭合记录。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
INCLUDE PERFETTO MODULE slices.with_context;

SELECT
upid, process_name,
utid, thread_name,
name,
COUNT(*) AS count,
MAX(dur) AS max_ns,
ROUND(AVG(dur) / 1e6, 1) AS avg_ms,
ROUND(MAX(dur) / 1e6, 1) AS max_ms
FROM thread_slice
WHERE process_name = 'com.example.app'
AND name IN ('DecodeFrame', 'UploadTexture', 'RenderScene')
AND dur >= 0
GROUP BY upid, process_name, utid, thread_name, name
ORDER BY max_ns DESC;

控制写入量

Track Event 开销低,但不是免费。常规 ATrace 路径会压 ftrace per-CPU buffer;SDK Track Event 主要压 producer shared memory、central buffer 和 incremental state。v58.3 还有 atrace_categories_prefer_sdk 等改路能力,不能只凭 API 名判断链路;按实际 data source 和 stats 定位瓶颈。

建议给每类埋点设一个预算:

  • 事件密度:按 events/sec、每帧事件数、参数字节数和目标 Trace 时长估算写入量。120Hz、多线程、多阶段和动态字符串叠加后,每帧一次也可能过密。
  • 数据形状:每个小对象、每次锁尝试、每个像素级循环都不适合默认开启;高频 debug category 默认关闭,专项 Trace 可用 1/N 采样或触发后短窗口开启。
  • 参数开销:便宜标量可直接传;昂贵字符串、JSON、容器遍历、锁内状态快照放在 enabled 判断或 lambda 内。参数在宏调用前已经拼好时,category gating 救不了这部分开销。
  • producer 侧兜底:确认瓶颈来自 shared memory 突发时,再评估 shmem_size_hint_kb 和 BufferExhaustedPolicy::kStall,两者的取舍第 12 篇已经展开;默认先降事件密度、拆大包,不要一上来就调参数。
  • 采集验收:长 Trace 里把业务 Track Event 放到独立 central buffer,抓完用下面的验收查询过一遍 traced_buf_* 和 track_event_* 统计项;分 buffer 只能隔离 central buffer 竞争,不能修复 producer shared memory burst loss。
  • Ring Buffer 场景要关注 Track Event 的 descriptor / string interning / incremental state,可让同一 packet sequence 上的元数据随增量状态重建而重发,并降低同 buffer 的写入竞争。clear_period_ms 只是请求支持该能力的 producer 周期重建;它不能恢复已丢事件,也不能把相关元数据随意拆到另一序列。

统一验收查询可以先从第 12 篇的 health check 开始,再补 Track Event 专用项:

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
SELECT name, idx, severity, source, value
FROM stats
WHERE value != 0
AND (
severity IN ('error', 'data_loss')
OR name IN (
'traced_buf_chunks_overwritten',
'traced_buf_chunks_discarded',
'traced_buf_trace_writer_packet_loss',
'traced_buf_sequence_packet_loss',
'traced_buf_incremental_sequences_dropped',
'traced_buf_patches_failed',
'track_event_parser_errors',
'track_event_tokenizer_errors',
'track_hierarchy_missing_uuid',
'track_event_thread_invalid_end',
'track_event_missing_sequence_id',
'interned_data_tokenizer_errors',
'tokenizer_skipped_packets',
'packet_skipped_seq_needs_incremental_state_invalid'
)
OR name GLOB 'track_descriptor_*'
OR name GLOB 'track_event_skipped_*'
)
ORDER BY name, idx;

报告里单独给 track_event_trust_level。即使已提供的 packet loss 统计为 0,非零 track_event_tokenizer_errors 或 track_hierarchy_missing_uuid 仍需定位,受影响的业务事件不能直接作为完整证据。

验收时先区分统计项存在且值为 0、统计项未提供、解析失败。上述非零查询返回空集不等于所有检查都通过;错误还需定位到受影响的 sequence/track/时间窗,避免把局部问题扩大成整份 Trace 不可用。

App 侧现场 Trace 协议

App 侧接 Perfetto,最容易踩的坑是把 App 当成一个小型 adb shell perfetto 客户端。普通 App 没有随意启动系统 tracing 的权限,也不适合在线上动态下发高开销 TraceConfig。现场方案更适合拆成三层:

  • 平台侧:预置受控 TraceConfig,声明 trigger、Ring Buffer、文件路径、数据源白名单和采集上限。
  • App 侧:记录业务埋点和页面状态,检测慢帧、卡死、超时等异常,按平台约定激活 trigger。
  • 服务端:接收 Trace package,跑 stats、摘要 SQL 和聚合索引,给人工分析留出可复查入口。

Perfetto 的 STOP trigger 很适合这类场景:trace 先以 Ring Buffer 方式循环记录,App 检测到问题后触发一个已声明的名字,系统在 stop_delay_ms 之后收尾。这样能保留问题发生前的一段现场,也能把触发后的尾巴收进来。

一个受控现场 UI 卡顿 preset 可以长这样。它适合灰度白名单、采样率受控、写入速率已实测、stats 可验收的实验室或现场排查;线上默认 preset 应减少 atrace category,必要时只保留 sched、FrameTimeline 和最小 Track Event。它不是“全量图形专项 preset”,但足够支持主线程、RenderThread/HWUI、FrameTimeline、CPU 调度、SurfaceFlinger 侧 FrameTimeline/线程调度线索和 App Track Event 的第一轮定位;涉及 Layer、Transaction、HWC、Display 归因时,切换图形专项 preset。

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
buffers { size_kb: 16384 fill_policy: RING_BUFFER } # 0: sched / ftrace
buffers { size_kb: 4096 fill_policy: RING_BUFFER } # 1: app track event / frame context

incremental_state_config {
clear_period_ms: 5000
}

trigger_config {
trigger_mode: STOP_TRACING
trigger_timeout_ms: 1800000 # 最长等待 trigger 的窗口
triggers {
name: "app_ui_jank"
stop_delay_ms: 1000
max_per_24_h: 8
skip_probability: 0.8
}
}

data_sources {
config {
name: "linux.ftrace"
target_buffer: 0
ftrace_config {
ftrace_events: "sched/sched_switch"
ftrace_events: "sched/sched_wakeup"
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_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: "player"
enabled_categories: "rendering"
}
}
producer_name_filter: "com.example.app"
}

这里 skip_probability: 0.8 表示先以 80% 概率跳过,再检查滚动 24 小时次数限制。实验室验证应另存一份 preset,把 skip_probability 设为 0,并使用未耗尽配额的测试 trigger。未被接受的触发不产生预期结果;30 分钟内没有接受到 trigger,STOP_TRACING 会结束且不返回数据。30 分钟是等待期限,不保证 Ring Buffer 保留了 30 分钟历史。产品仍要做平台侧权限、采样与配额管理。

实验室先把上面 trigger 配置保存为单独的 app-trigger.pbtxt,按上文命令启动该配置,另一个终端再发送 trigger;原 10 秒配置没有声明 trigger,不能拿它验证。STOP 会结束这次 session,持续监测需要平台另行启动下一次 session。确认实验室采样与配额后,命令为:

1
adb shell /system/bin/trigger_perfetto app_ui_jank

Perfetto trigger 的模型是:有权限的 consumer 预先声明 trigger 名字,App 这类 producer 只能激活已声明的名字。接了 Perfetto SDK 的 native 模块也可以用 SDK 触发;产品上仍建议由平台接口统一控制权限和配额:

1
perfetto::Tracing::ActivateTriggers({"app_ui_jank"}, 10000);

第二个参数单位为 ms:调用立即返回,向当前已连接及未来 10000 ms 内连接的已初始化 backend 发信号;它不是阻塞等待时长,也不是采集后的 1 秒尾窗。返回不证明请求被接受或 trace 已生成。未配置 producer_name_regex 时,任何已连接 producer 都能激活匹配名称;名称与 producer 过滤都不应被当作业务授权凭证。

线上 App 不应假设自己能执行 /system/bin/trigger_perfetto。更推荐由平台提供受控接口,例如系统服务、厂商 SDK、企业版设备管理组件或测试框架代理。App 只提交一个受限请求:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"preset": "ui_jank_field_v3",
"trigger": "app_ui_jank",
"reason": "three_jank_frames_in_2s",
"jank_frames_is_excerpt": true,
"scenario_id": "feed_scroll_120hz",
"session_id": "s-20260504-001",
"action_id": "scroll-42",
"page": "Feed",
"action": "scroll",
"elapsed_realtime_ns": 123456789000000,
"jank_frames": [
{
"frame_start_ns": 123456700000000,
"clock_domain": "CLOCK_MONOTONIC",
"duration_ns": 32000000,
"expected_duration_ns": 8333333,
"states": {
"page": "Feed",
"action": "scroll"
}
}
]
}

平台侧根据 preset 白名单、采样率、权限、设备状态和每日配额决定是否触发。这套接口约定比“App 自己拼 TraceConfig”更适合长期维护。服务端匹配时应输出 trigger_event_ts、nearest_marker、marker_delta_ms、matched_by,避免外部 JSON 和 trace 时间轴只靠人工猜。

触发策略要靠近用户感知,而不是靠近内部实现细节:

触发 典型信号 Trace 里要看什么
UI 慢帧 JankStats 连续慢帧、严重超预算 主线程、RenderThread、FrameTimeline、CPU
主线程卡死前兆 2s / 4s / 8s watchdog 主线程状态、Binder、锁、IO、系统服务
业务 timeout Camera open、播放器 prepare、首屏 timeout App marker、Binder、HAL、线程状态

触发名进入平台 preset 后要保持稳定。改名会让服务端聚合、SQL 模板和历史数据断开。

Trace package 要带上下文

一份现场包先分最小必需和平台化扩展。本篇只要求最小必需:Trace 本体、业务 metadata、采集 preset、stats 可信度结果。上传策略、日志白名单和保留周期属于平台化后的规则,可以后续单独设计。

1
2
3
4
5
6
7
8
trace-package/
trace.perfetto-trace
app_metadata.json
app_events.jsonl
trace_preset.txt
trace_stats.json
upload_policy.json # 平台化后再补
log_excerpt.txt # 平台化后再补

app_metadata.json 描述这次问题现场,字段要固定并带 schema 版本:

以下 JSON 都是假设数据。trigger 请求中的 jank_frames 只展示三帧中的一帧,真实请求应提供完整依据或明确摘要;8.333333 ms 仅为固定 120 Hz 的周期示意,不直接等于 JankStats 阈值或可变刷新率下的帧 deadline。未知刷新率和温度状态保留 null/unknown,不能默认填 120/normal。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"schema_version": 3,
"app_version": "8.12.0",
"package_name": "com.example.app",
"page": "Feed",
"action": "scroll",
"trigger": "app_ui_jank",
"trigger_reason": "three_jank_frames_in_2s",
"trigger_elapsed_realtime_ns": 123456789000000,
"scenario_id": "feed_scroll_120hz",
"session_id": "s-20260504-001",
"action_id": "scroll-42",
"refresh_rate_hz": 120,
"thermal_state": "normal",
"trace_preset": "ui_jank_field_v3"
}

其他几个文件也要有最小字段:

trace_stats.json 至少保留第 12 篇 health check 的结果:

覆盖 chunk 的计数不等于丢失事件数,也不能单独证明目标帧受损。下面 idx=1 对应本 preset 中 Track Event 与 FrameTimeline 共用的 buffer;先检查目标时间窗、闭合状态和解析错误,再决定哪些指标可用,不能直接降级全部 App marker。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"trace_quality_status": "needs_scope_check",
"track_event_trust_level": "undetermined",
"stats": [
{
"name": "traced_buf_chunks_overwritten",
"idx": 1,
"idx_semantics": "buffer",
"severity": "info",
"source": "trace",
"value": 12,
"buffer_sources": ["track_event", "android.surfaceflinger.frametimeline"],
"decision": "check_target_window_before_grading"
}
]
}

upload_policy.json 说明这份现场包能不能上传、保留多久:

1
2
3
4
5
6
7
{
"policy_version": 2,
"network": "wifi_only",
"daily_device_quota": 3,
"retention_days": 14,
"encryption": "required"
}

app_events.jsonl 用一行一个 JSON 事件保存触发点和少量 App 侧状态,并和 Track Event 共享 scenario_id/session_id/action_id:

1
{"elapsed_realtime_ns":123456789000000,"event":"trigger","scenario_id":"feed_scroll_120hz","session_id":"s-20260504-001","action_id":"scroll-42","page":"Feed","action":"scroll"}

log_excerpt.txt 只放白名单 tag 的短窗口摘要,至少记录 tag、level、elapsed realtime 和脱敏后的 message。

时间戳应记录真实 clock domain、单位与同一次开机的关联标识。Android 的 elapsedRealtimeNanos 对应包含休眠时间的 CLOCK_BOOTTIME;JankStats 的 frameStartNanos 基于 uptime/System.nanoTime 时间域,不能直接改名为 elapsed_realtime。需要同一现场的时钟配对或 ClockSnapshot 转换;跨休眠时不能套用一个旧的固定 offset。Perfetto 只会处理 trace 内的时钟映射,外部 JSON 不会自动归一,单独记 trace start/end 也不足以求出不同时间域的关系。Track Event 默认让 SDK 取时间;只有转换有据可查时才回填显式 timestamp。

App 侧不要直接截断 trace.perfetto-trace。Perfetto Trace 是 protobuf 流,粗暴二进制裁剪可能破坏 packet、时钟同步和增量状态。更稳的做法是在采集侧控制窗口:Ring Buffer 控制触发前窗口,stop_delay_ms 控制触发后窗口,trigger 限频控制重复抓取。

max_file_size_bytes 是文件大小硬上限,达到后会停止 tracing;长时间 flight recorder 如果 cap 太小,可能在 trigger 前就结束。它适合和 write_into_file / file_write_period_ms 一起控制落盘风险,不是窗口裁剪工具。

平台化后,上传策略再把配额、隐私和重试写进产品规则:

  • 设备侧配额:按用户、设备、版本、trigger 和天维度限频。
  • 网络条件:默认只在 Wi-Fi 或用户允许的网络上传,低电量、温度异常、后台受限时延后。
  • 内容白名单:metadata 字段固定,log 只允许白名单 tag,App trace section 禁止拼接用户输入。
  • Trace 本体:最小化数据源,限制进程/producer,避免默认 logcat;ftrace、sched、Binder、线程名、进程名本身也可能是敏感信息。
  • 传输和保留:加密上传,服务端访问审计,Trace、log 摘要、聚合结果设置独立 TTL,到期自动清理。

App 记录业务阶段和异常触发;平台控制采集配置、文件大小与上传;服务端检查数据质量并保存可追溯的摘要。现场问题复现后,先核对这些记录是否覆盖同一操作窗口,再谈跨设备聚合。

总结

Track Event 补上系统 Trace 缺少的业务标识。它能说明某个阶段何时运行、队列多深、请求如何跨线程移动;能否解释最终卡顿,还要与系统轨道和帧时间线对齐。

工程上建议按这个顺序做:Java/Kotlin 层先用 android.os.Trace,native 长期埋点用 Track Event,复杂结构再考虑自定义 DataSource。事件名稳定、category 可控、counter 有单位、flow 有稳定 id,后面的 SQL 和报告才可长期复用。进入现场 Trace 后,App 还要把触发、metadata、证据包和上传策略一起设计好。

参考文档

  1. Tracing SDK
  2. Track events
  3. Recording In-App Traces with Perfetto
  4. androidx.tracing.perfetto
  5. Trace configuration - Triggers
  6. android.os.Trace
  7. JankStats Library

本次核对:v58.3 SDK、类别优先级、Track/CounterTrack、触发器 API 与 TraceConfig。AndroidX 另参考 Tracing 1.0.0 发布记录、FrameData 和 SystemClock 和 NDK ATrace API。以下保留原文 2026-09-19 的源码入口供对照。

关于我 && 博客

欢迎关注 Android Performance。

CATALOG
  1. 1. Perfetto 系列文章
  2. 2. 什么时候需要业务语义
  3. 3. SDK 接入边界
  4. 4. 业务阶段字典先于代码
  5. 5. 两种 backend 解决不同问题
  6. 6. 最小接入骨架
  7. 7. category 是线上开关
  8. 8. 和系统 Trace 一起抓
  9. 9. 跨线程任务用 flow 或独立 track
  10. 10. Counter 只放状态,不放日志
  11. 11. 事件名是 SQL 接口
  12. 12. 控制写入量
  13. 13. App 侧现场 Trace 协议
  14. 14. Trace package 要带上下文
  15. 15. 总结
  16. 16. 参考文档
  17. 17. 关于我 && 博客