Perfetto 实战 FAQ命令行打开 Trace、JSON 兼容性、多进程/多 Trace 合并全解析【免费下载链接】perfettoProduction-grade client-side tracing, profiling, and analysis for complex software systems.项目地址: https://gitcode.com/GitHub_Trending/pe/perfettoPerfetto 是一个生产级的客户端侧 tracing 与性能分析平台。本文聚焦官方 FAQ 中开发者最高频的五个问题如何从命令行把 trace 一键打开到 UI、为什么不支持某些 JSON 格式特性、如何不改造程序就复用 Perfetto 分析工具链、多进程应用如何合并到同一条时间线、以及如何把多条 trace 合并到同一时间轴。读完本文你将掌握从采集、转换到多 trace 合并分析的完整工作流并理解其背后的时钟模型与机器模型。命令行直接打开 Trace 到 UI当通过命令行采集完 trace 后最便捷的打开方式是使用仓库根目录下的 tools/open_trace_in_ui 脚本。它会在本地启动一个临时 HTTP 服务把 trace 文件以 URL 参数形式传给 Perfetto UI默认https://ui.perfetto.dev并在浏览器新标签页中打开。快速上手没有 Perfetto 源码检出时直接下载脚本使用curl -OL https://github.com/google/perfetto/raw/main/tools/open_trace_in_ui chmod x open_trace_in_ui ./open_trace_in_ui -i /path/to/trace如果已经有 Perfetto 的源码检出前两步可以省略直接在仓库根目录执行tools/open_trace_in_ui -i /path/to/trace也可以把 trace 文件作为位置参数传入tools/open_trace_in_ui trace.pftrace脚本工作原理与可用参数从 tools/open_trace_in_ui 的源码可以看到该脚本是一个 Python 3 脚本其核心逻辑为复用 HTTPRPC 端口9001这是 CSP 唯一允许的端口通过socketserver.TCPServer在127.0.0.1:9001上启动一个只服务于指定文件的简易 HTTP 服务构造形如https://ui.perfetto.dev/#!/?urlhttp://127.0.0.1:9001/fnamereferreropen_trace_in_ui的深链接地址并用webbrowser.open_new_tab打开通过Access-Control-Allow-Origin响应头允许 UI 跨域读取本地文件allow_origin默认为去掉路径组件后的--origin并设置Cache-Control: no-cache防止缓存直到浏览器成功拉取到文件fname_get_completed置位才退出因此脚本会阻塞终端直到页面加载完成。脚本支持以下参数可在tools/open_trace_in_ui -h中查看完整帮助参数说明-i, --trace file指定要打开的 trace 文件优先级高于位置参数trace位置参数同样可以指定 trace 文件-n, --no-open-browser不自动打开浏览器仅打印 URL 供手动打开--origin url指定 UI 的源地址默认https://ui.perfetto.dev--dev-server在本地 devserverhttp://localhost:10000中打开是--origin的快捷方式若未指定文件或文件不存在脚本会分别提示Please specify trace file name与file not found并以退出码 1 结束。Perfetto 为什么不支持某些冷门的 JSON 格式特性JSON trace 格式即chrome://tracing的 JSON 导出格式在 Perfetto 中被视为遗留格式仅在尽力而为best-effort的基础上提供支持。官方维护者虽然努力保持与chrome://tracingUI 及其格式规范在事件解析与展示上的一致性但这并不总是能做到——尤其是那些在 Chrome 之外程序化生成、且依赖chrome://tracing实现细节的 trace。如果支持某个特性会引入不成比例的技术债维护者的普遍选择是不支持该特性。因此推荐做法改用 Perfetto 的原生 trace 格式 —— TrackEvent。迁移指南参考 docs/reference/synthetic-track-event.md该文档详细说明了常见的 JSON 事件如何用 TrackEvent 表达基本 slice、嵌套 slice、异步 slice、counter、flow 等。用 TrackEvent 表达 JSON 事件格式基础Perfetto 的 trace 文件.pftrace/.perfetto-trace本质上是 trace.proto 中Trace消息内一串 trace_packet.proto 的TracePacket消息。TrackEvent是其中最通用、最灵活的负载可以表达Tracks一条随时间展开的事件序列slice 或 counter对应 UI 中的一条泳道Slices带名称、起始时间戳和持续时长的事件如函数调用、任务Counters随时间变化的数值如内存用量、自定义指标Flows连接不同 track 上相关 slice 的箭头。入门转换流程可参考 docs/getting-started/converting.md先用pip install perfetto安装 Python 库再基于TraceProtoBuilder模板填充populate_packets(builder)函数生成.pftrace文件。例如最基本的 slicepacket builder.add_packet() packet.timestamp 1000 # 纳秒 packet.track_event.type TrackEvent.TYPE_SLICE_BEGIN packet.track_event.track_uuid CUSTOM_TRACK_UUID packet.track_event.name Task A packet.trusted_packet_sequence_id TRUSTED_PACKET_SEQUENCE_ID值得注意的是docs/reference/synthetic-track-event.md 还提供了比 JSON 兼容性更进一步的进阶能力将 track 关联到 OS 进程/线程TrackDescriptor.process/thread字段、控制 track 排序与合并child_ordering、sibling_merge_behavior、y_axis_share_key、用 interningiid压缩重复字符串与调用栈以减小 trace 体积、为事件附加调用栈权重与自定义 proto 扩展字段等。对程序化生成 trace 的开发者来说这些是比 JSON 更值得投入的方向。不改造程序也能用 Perfetto 分析工具很多用户想用 Perfetto 的可视化与分析能力但不想或不能改造自己的程序做插桩——可能是因为 Perfetto 不适合他们的用例也可能因为他们已有现成的 tracing 系统。官方推荐的做法同样是输出 Perfetto 原生的 TrackEvent proto 格式参考 docs/reference/synthetic-track-event.md。这样生成的是标准.pftrace文件可以直接在 Perfetto UI 中可视化、用 Trace Processor 做 SQL 分析无需修改被测程序本身。转换是语言无关的——任何支持 Protocol Buffer 的语言都可以按 protos/perfetto/trace/ 下的 schema 构造TracePacket并序列化为二进制文件。基于 Trace Processor 的脚本化分析生成或转换得到 trace 后可以用 Trace Processor CLI 进行命令行分析详见 docs/reference/trace-processor-cli.mdtrace_processor -q SELECT ts, dur, name FROM slice LIMIT 10 my_custom_trace.pftrace也可以在 docs/analysis/trace-processor-python.md 中使用 Python API 加载并查询把分析集成进 CI 或批量脚本。多进程应用如何出现在同一条 trace 中如果应用有多个进程希望把所有进程的事件合并到同一条 trace 的时间线上应该使用 Tracing SDK 的系统模式system mode。系统模式原理启用方式是在 SDK 初始化时设置kSystemBackend#include perfetto.h perfetto::TracingInitArgs args; // 1) 进程内后端只在应用自身进程内记录 args.backends | perfetto::kInProcessBackend; // 2) 系统后端通过 UNIX socket 写入系统 Perfetto 守护进程 traced // 可与 ftrace 等系统事件叠加到同一时间线Android 9 内置 traced args.backends | perfetto::kSystemBackend; perfetto::Tracing::Initialize(args);系统模式下所有进程都会通过 socket 连接到traced守护进程traced会把所有进程的事件汇总成一条trace 输出。其最大优势是能够创建融合 trace——把应用事件与 OS 事件调度、syscall 等叠加在同一条时间线上实现全栈性能分析。限制是需要外部traced守护进程可用并且系统模式的 tracing 会话必须由外部的perfetto命令行客户端控制数据生产者不允许读回 trace 数据以免泄露其他进程的信息。作为对比kInProcessBackend进程内模式不连接系统traced生成的 trace 只包含应用自身的事件不需要任何特殊 OS 权限支持 Android、Linux、macOS 与 Windows。两种模式可以同时启用且生成相同的 trace 文件格式。SDK 中的 TrackEvent 插桩SDK 用TRACE_EVENT宏做注解式插桩PERFETTO_DEFINE_CATEGORIES( perfetto::Category(rendering) .SetDescription(Events from the graphics subsystem), perfetto::Category(network) .SetDescription(Network upload and download statistics)); PERFETTO_TRACK_EVENT_STATIC_STORAGE(); // main() 中初始化并注册 perfetto::Tracing::Initialize(args); perfetto::TrackEvent::Register(); // 业务代码中直接埋点 void LayerTreeHost::DoUpdateLayers() { TRACE_EVENT(rendering, LayerTreeHost::DoUpdateLayers); // ... }对应的 TraceConfig 需要启用track_event数据源并声明启用的分类data_sources { config { name: track_event track_event_config { enabled_categories: rendering disabled_categories: * } } }多进程合并的进阶machine_id当多个进程内模式采集的 trace例如分布式系统中不同机器采集的之后要合并成一条 trace 时SDK 还支持为每台机器设置唯一的TracingInitArgs.machine_id每个 packet 都会被标记上来源机器合并后的 trace 能保持各机器的数据分离。注意设置非零machine_id时TraceConfig必须设置trace_all_machines: true否则数据源不会记录任何数据。此机制与下文多 trace 合并的机器模型完全一致。能否把多条 trace 打开到同一条时间线上可以。UI 与命令行两条路径都支持多 trace 合并UI 方式在侧边栏点击Open multiple trace files或直接多选/拖拽多个文件打开合并对话框配置它们如何对齐到共享时间线详见 docs/visualization/merging-traces.md命令行方式把多条 trace 打成 ZIP 或 TAR 归档传给trace_processor详见 docs/analysis/merging-traces.md。模型一个归档进一条 trace 出trace_processor只接受单个 trace 文件参数。要合并就传入一个包含待合并文件的归档ZIP 或 TARutil merge子命令可以帮你构建这样的归档trace_processor util merge -o merged.tar trace_a.pftrace trace_b.pftrace trace_processor merged.tar归档就是普通的 TARtar cf merged.tar trace_a.pftrace ...或任意 ZIP 工具均可util merge只是便利助手——它会处理归档布局成员命名、把 manifest 以perfetto_manifest.json名称打入归档并对结果做健全性检查--strict把警告变成失败退出码适合 CI--no-validate跳过检查。util子命令在 docs/reference/trace-processor-cli.md 中有说明其余工具还包括symbolize、deobfuscate、decompress_packets等。一切接受普通 trace 的入口都接受这种归档交互式 shell、-q批量查询、httpd 模式以及 C/Python API。无需配置即可合并的场景当 Trace Processor 已经能关联各文件的时钟时不需要任何额外配置同一设备上的 trace同一 boot 期间记录的多个文件共享时钟域如BOOTTIME含ClockSnapshotpacket 的文件还会显式关联各时钟域不同设备但墙钟同步REALTIME被假定在所有机器上读数一致实践中靠 NTP因此同一时间记录的两台手机 trace 会自动对齐到真实墙钟位置预先打上 machine id 的 traceSDK producer 以 machine id 初始化后每个 packet 都会被打标归档文件无需 manifest 即可保持数据按机器分离perfetto::TracingInitArgs args; args.backends perfetto::kInProcessBackend; args.machine_id 42; // 每台机器唯一的非零值 perfetto::Tracing::Initialize(args);C SDK 的等价调用是PerfettoProducerBackendInitArgsSetMachineId()。如果既没有共享时钟域也没有REALTIME可以定位某个文件其事件会被丢弃而不是猜测见下文检查合并结果这时就需要 manifest。用 trace manifest 自动化合并trace manifestperfetto_manifest是打进归档的 JSON 文件控制 Trace Processor 如何解释归档内的文件为合并场景命名机器、重映射内嵌机器 id、手动关联时钟。Trace Processor 总是先于任何 trace 文件处理 manifest无论它在归档中什么位置。它让合并变得可自动化工具知道自己产出的 trace 之间的关系把关系写进 manifest 并打包成一个归档用户在任何时候打开这个归档都能得到正确合并的视图。两台设备数据分离——默认情况下两个看似同一设备的 trace 会合并到同一台机器上命名机器可以让各文件的数据分组分离{ perfetto_manifest: { version: 1, files: [ {path: device_a.pftrace, machine: {name: device-a}}, {path: device_b.pftrace, machine: {name: device-b}} ] } }trace_processor util merge -o merged.tar --manifest manifest.json \ device_a.pftrace device_b.pftrace trace_processor merged.tar把无时钟的 trace 对齐到系统 trace——没有绝对时钟的格式Chrome JSON、Gecko、Instruments无法自行与系统 trace 对齐clocks条目可把该文件钉到另一个文件的时钟上并可带固定偏移{ perfetto_manifest: { version: 1, trace_time: {clock: BOOTTIME}, files: [ {path: system_trace.pftrace}, { path: app_trace.json, clocks: { sync_to: {file: system_trace.pftrace, clock: BOOTTIME}, offset_ns: 100000000 } } ] } }offset_ns的语义是在同一时刻源文件时钟读数为 T 时参考时钟读数为 T offset_ns因此正值会把文件在时间线上往后移。注意sync_to.file必须本身出现在files数组中。多机器 trace 的机器重命名——用 traced_relay 记录的 trace 本身包含多台机器用machines给它们可读的名字每个内嵌 id 都必须声明{ perfetto_manifest: { version: 1, files: [ {path: relay_capture.pftrace, machines: [ {id: 0, name: host}, {id: 1234, name: vm} ]} ] } }manifest 的完整语法、默认值与错误目录见 docs/reference/perfetto-manifest.md。提示Perfetto UI 的 Open multiple trace files 对话框就是在交互式生成这种格式——在对话框里配置好合并后用 Copy manifest 或 Download .tar 即可引导出脚本化配置。底层机制时钟图与机器模型合并背后的模型见 docs/concepts/merging-traces.md时钟是按机器和文件作用域的合并把单 trace 内的多时钟域模型ClockSnapshot扩展到跨文件、跨机器。所有时钟存在于一个全局时钟图中节点是时钟边是时钟 A 读 X 时时钟 B 读 Y的对应关系。边来自 trace 内的ClockSnapshot、录制时的时钟同步如多机器录制的 ping 协议、以及 manifest 中的声明。转换时间戳时Trace Processor 在图中寻找从源时钟到 trace-time 时钟的路径并逐边换算所有边都会记录到clock_snapshot表可用 SQL 完整检查。无共享时钟时的放置优先级(1) REALTIME 会合——两台机器经 NTP 同步墙钟(2) 同域假设——不同机器/文件的同一时钟域在零偏移下关联仅当没有更好依据时适合同一机器同一次 boot 的文件(3) 丢弃——两个不同的真实时钟域绝不盲目等价无法关联的事件被丢弃并计入错误统计。机器模型机器即一台设备或 OS 实例手机、服务器、VM是machine表中的一行process、thread、cpu、sched等机器作用域的表都带machine_id列。机器来源包括 trace 内嵌 idtraced_relay 或 SDKmachine_id、manifest 声明命名机器得到 2^32 起跳的合成raw_id以及SystemInfo.machine_name。注意machine.id跨版本不稳定查询时应使用machine.raw_id或machine.name。检查合并结果合并后的 trace 暴露了合并过程的全部信息可用 SQL 检查-- 合并 trace 中的机器及各自的数据量 SELECT m.name, m.raw_id, (SELECT COUNT(*) FROM thread t WHERE t.machine_id m.id) AS threads FROM machine m; -- 输入文件及处理顺序 SELECT name, trace_type, size FROM trace_file; -- 合并过程中被丢弃或错位的内容空结果表示所有事件都放上了时间线 SELECT name, value, machine_id, trace_id FROM stats WHERE severity error AND value 0;需要重点关注的统计项clock_sync_unrelatable_clock_domains与clock_sync_failure_no_path统计时钟无法关联到时间线的事件解决方法是记录时钟快照或在 manifest 中加clocks条目trace_sorter_negative_timestamp_dropped统计被offset_ns移到时间线起点之前而丢弃的事件。互操作注意事项Android bugreportbugreport.zip本身就是归档Trace Processor 会解压并合并其中的 tracetrace_processor bundletrace_processor bundle生成的 TARtrace 加符号走的是同一套归档机制PythonBatchTraceProcessor不做合并它把 N 条 trace 加载到 N 个独立实例并行查询要合并就把一个归档传给单个TraceProcessor实例归档不能递归合并包含 trace 的归档不能再嵌套进另一个合并需直接合并叶子文件隐藏文件被忽略任何名称中带以.开头的路径组件的归档条目都会被跳过这覆盖了 macOStar/Finder 生成的._foo与.DS_Store条目避免出现未知 trace 类型错误。总结围绕官方 FAQ 的五个高频问题本文给出了完整闭环命令行用 tools/open_trace_in_ui 一键打开 trace面对 JSON 格式的兼容性局限时改用原生 TrackEvent见 docs/reference/synthetic-track-event.md 与 docs/getting-started/converting.md不想改造程序时直接程序化产出.pftrace再用 Trace Processor 分析多进程应用用 Tracing SDK 系统模式汇总到同一条 trace多条 trace 则通过归档 manifest 在 UI 或命令行合并到共享时间线。合并的时钟图与机器模型是理解这一切的关键相关参考文档见 docs/concepts/merging-traces.md、docs/analysis/merging-traces.md、docs/visualization/merging-traces.md 与 docs/reference/perfetto-manifest.md。【免费下载链接】perfettoProduction-grade client-side tracing, profiling, and analysis for complex software systems.项目地址: https://gitcode.com/GitHub_Trending/pe/perfetto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考