Perfetto UI 嵌入 API 参考

本页面是用于在宿主页面的 <iframe> 中嵌入 Perfetto UI (ui.perfetto.dev)的 postMessage 和 URL 参数接口的参考。

关于面向任务的嵌入流程介绍,参见 嵌入 Perfetto UI。 关于 window.open()(新浏览器标签页)变体和共享 / appStateHash 详情, 参见深度链接到 Perfetto UI。

NOTE: 这是一份参考文档,而非教程。此处未列出的字段和消息类型不属于 受支持的接口。

消息通道

宿主页面通过 window.postMessage 与嵌入的 UI 通信。UI 的消息处理器 仅处理 event.source 为以下之一的消息:

event.source 何时
window.parent UI 运行在宿主的 <iframe> 内(嵌入场景)。
window.opener 宿主通过 window.open() 启动 UI(新标签页场景)。
本 UI 打开的窗口 event.source.opener === window。

对于 iframe 嵌入,UI 的 window.parent 即宿主页面,因此宿主向 iframe.contentWindow 发送消息,UI 接受它们。

由于通道不是缓冲的,在发送 trace 之前需要进行握手:

  1. 宿主重复向 UI 窗口发送字符串 'PING'。
  2. UI 回复字符串 'PONG'。回复发送到 '*',且仅在 UI 的消息监听器 已注册且 document.readyState === 'complete' 时才发送。
  3. 宿主监听 'message' 事件;在首次从 UI 窗口收到 data === 'PONG' 时停止 ping 并发送 trace。

健壮的宿主应以间隔(例如每 50-250ms)进行 ping,并在第一个 PONG 时 清除该间隔。

带有 {perfettoIgnore: true} 的消息会被有意忽略。这允许宿主在同一通道 上复用其他流量。

打开 trace

要打开一个 trace,发送一个带有单个 perfetto 键的对象。传入 buffer 或 stream 中的恰好一个:

iframe.contentWindow.postMessage({perfetto: {buffer, title}}, '*');

ReadableStream 必须以转移方式传递。背压(backpressure)会从 trace 解析传导到流的生产端,限制生产端能够超前多少:

iframe.contentWindow.postMessage( {perfetto: {stream, title, bytesTotal}}, '*', [stream]);

perfetto 对象的字段:

字段 类型 必需 默认值 含义
buffer ArrayBuffer buffer 或 stream 二选一 - 原始 trace 字节,例如来自 fetch(...).then(r => r.arrayBuffer())。
stream ReadableStream<ArrayBuffer | ArrayBufferView> buffer 或 stream 二选一 - 经转移的原始 trace 数据块流。
bytesTotal number 否 0 用于进度报告的流总大小;0 表示未知。
title string 是 - 在 UI 中显示的 trace 标题。
fileName string 否 - 用户下载 trace 时建议的文件名。
url string 否 - 分享 URL。分享详情参见深度链接到 Perfetto UI。
appStateHash string 否 - 40 字符十六进制哈希;从 GCS 恢复已保存的 UI 状态。参见深度链接到 Perfetto UI。
shareable boolean 否 false 若为 true,UI 可以共享该 trace(例如上传以生成永久链接)。
downloadable boolean 否 false 若为 true,用户可以下载该 trace。
localOnly boolean 否 true 遗留字段。设为 false 会将 shareable 和 downloadable 都设为 true。显式指定的 shareable/downloadable 优先。
keepApiOpen boolean 否 false 若为 true,监听器保持活跃,宿主之后可以发送更多 trace。若为 false/省略,处理器在第一个 trace 之后移除自己的消息监听器(避免重复发送,b/182502595)。
pluginArgs {[pluginId: string]: {[key: string]: unknown}} 否 - 传递给 plugin 的 onTraceLoad()。

流式传输的 trace 在解析后不会被保留,因此无法下载、分享或缓存。fileName、url、shareable、downloadable、localOnly 和 pluginArgs 因而不适用于 stream。

裸 ArrayBuffer 简写

裸 ArrayBuffer(event.data instanceof ArrayBuffer)也会被接受。它 会被视为 {title: 'External trace', buffer}。

滚动到时间范围

trace 加载后发送以下消息,将视口滚动/缩放到一个时间范围:

iframe.contentWindow.postMessage( {perfetto: {timeStart, timeEnd, viewPercentage}}, '*');
字段 类型 必需 含义
timeStart number 是 范围开始,绝对 trace 时间(秒)(非相对于 trace 起点;会被钳制到 trace 边界)。
timeEnd number 是 范围结束,绝对 trace 时间(秒)。
viewPercentage number 否 该范围应填充的视口比例,取值 (0.0, 1.0]。越界值会被忽略并以 0.5 替代。

处理器会在内部重试(大约每 200ms 一次,共约 20 次)直到 trace 就绪,因此 这条消息可以在发送 trace 后不久发出,无需等待显式的"已加载"信号。

字符串命令

处理器可理解以下字符串消息:

消息 效果
'PING' 回复 'PONG'(发送到 '*')。
'SHOW-HELP' 打开帮助对话框。
'RELOAD-CSS-CONSTANTS' 重新加载 CSS 常量。

URL 参数

在 iframe 的 src 上设置这些参数。路由基于 hash: https://ui.perfetto.dev/#!/?key=val&...。

参数 值 效果
mode embedded 启用嵌入模式:侧边栏被完全禁用(而非仅隐藏),且不安装文件拖放处理器。嵌入时使用此项。
hideSidebar true 在视觉上隐藏侧边栏,但不完全禁用它。
hideStatusbar true 隐藏窗口底部的状态栏。
url <https url> UI 自行获取公开 trace(要求 CORS 允许 UI 源)。公开 trace 场景下可作为 postMessage 的替代方案。
s <hash> 加载一个 permalink(已保存状态)。
visStart <ns> 初始视口起点,原始纳秒时间戳(与 SQL 表中一致)。与 visEnd 配对使用。
visEnd <ns> 初始视口终点,原始纳秒时间戳。
ts <ns> 加载时要选择的 slice 的时间戳,单位纳秒。链接依据是 ts+dur,而非 id(id 不稳定)。
dur <ns> 加载时要选择的 slice 的持续时间,单位纳秒。
query <sql> 加载时运行一个 SQL 查询(对值进行 URL 编码)。
startupCommands <url-encoded JSON array> 加载后运行 UI 命令,例如 [{id:'dev.perfetto.PinTracksByRegex', args:['.*CPU [0-3].*']}]。
enablePlugins <comma,list> 按 id 启用特定 plugin。

NOTE: visStart/visEnd 和 ts/dur 是原始的纳秒值, 而 timeStart/timeEnd 的 postMessage 字段是秒。

NOTE: slice 选择通过 ts+dur 进行,绝不通过 id,因为 ID 在不同运行之间不稳定。

来源信任

如果发送消息的来源受信任,trace 会立即打开。受信任集合为:

如果来源不受信任,UI 会显示一个模态框:

<origin> 正在尝试打开一个 trace 文件。你信任该来源并想继续吗?

选项为 No、Yes 和 Always trust。"Always trust" 将来源 持久化在 localStorage 中。

因此,从生产域名嵌入会向用户显示一次性同意提示,除非你自行托管 UI (同源 => 受信任)。

title 和 url 中的字符串会被清理为字符集 [A-Za-z0-9.\-_#:/?=&;%+$ ]。

约束

源码

上述行为定义于: