Trace Event

fengchen 收录于 Computer

2026-01-13 约 1400 字预计阅读 3 分钟

Google Trace Event JSON 格式详解（兼容 Trace Viewer / Perfetto）

一、事件通用字段

google 的 trace-viewer 项目，合并到了 catapult 中，工具 perfetto 打算替换 Trace Viewer。

字段名	含义	备注
`ph`	phase，事件类型	关键字段，决定事件表现形式
`name`	事件名称	会显示在时间线上
`pid`	进程ID	相同 pid 会归入一个进程框
`tid`	线程ID	相同 tid 会归入一个线程框
`ts`	时间戳	单位：微秒（Perfetto 使用纳秒，需要转换）
`dur`	持续时间	仅 `ph: X` 使用，单位：微秒
`args`	附加参数	可以添加任意键值对，支持 UI 展示
`id`	异步/Flow事件的唯一标识	`ph: b/e/s/t/f/O` 使用
`cat`	分类	Flow事件可用，UI可根据分类渲染
`cname`	自定义颜色	例如：“good”, “bad”, “terrible” 等
`bp`	绑定点	Flow 事件专用（`ph: f`），指定关联事件的开始(“s”)或结束(“e”)

二、事件类型（ph）

1. 完整事件 (Complete Event)

ph: "X"
表示一个完整的区间，包含开始和结束。
显示：块状，带宽度。
示例：

1
{"ph": "X", "name": "hipMalloc", "pid": "0", "tid": "Node0/Proc0/Thread20041", "ts": 11607, "dur": 17783, "args": {"...": "..."}}

等价于：

1
2
{"ph": "B", "name": "hipMalloc", "pid": "0", "tid": "Node0/Proc0/Thread20041", "ts": 11607, "args": {"...": "..."}},
{"ph": "E", "name": "hipMalloc", "pid": "0", "tid": "Node0/Proc0/Thread20041", "ts": 29390, "args": {"...": "..."}}

2. 开始/结束事件 (Begin/End Event)

ph: "B"：开始事件
ph: "E"：结束事件
显示：与 Complete Event 一样，显示为区间块。

3. 元数据事件 (Metadata Event)

ph: "M"
用于设置进程名、线程名、排序等信息，不显示时间区间。
显示：在进程、线程的标题栏显示
示例：

1
{"ph":"M","pid":0,"name":"process_name","args":{"name":"[1] Runtime API"},"sort_index":0} //sort_index好像没起作用

4. 瞬时事件 (Instant Event)

ph: "I"
单点时间标记，类似打断点。
显示：时间轴上的垂直标记线
示例：

1
{"ph": "I", "name": "dispatch", "pid": "0", "tid": "Node0/Proc0/Thread20041", "ts": 12000}

5. 异步事件 (Async Event)

ph: "b"：异步开始
ph: "e"：异步结束
必须指定 id，用来标识唯一事件对。
显示：独立轨道，斜体名称，顶部有黑色持续时间条
示例：

1
2
{"ph": "b", "name": "测试", "cat": "test", "id": "test", "pid": "0", "tid": "Node0/Proc0/Thread20041", "ts": 0},
{"ph": "e", "name": "测试", "cat": "test", "id": "test", "pid": "0", "tid": "Node0/Proc0/Thread20041", "ts": 59510}

6. Flow 事件（箭头依赖）

模式1 跨线程/进程依赖
- ph: "s"：Flow Start
- ph: "t"：Flow Step
- ph: "f"：Flow End
模式2：绑定到事件端点
- ph: "s" + ph: "f" + "bp": "e"（绑定到终点）
- ph: "s" + ph: "f" + "bp": "s"（绑定到起点，默认）
显示：用箭头连接两个事件，表示数据或依赖关系流动。
示例：

1
2
3
4
5
6
7
8
9
{"ph": "X","name": "hipMalloc","pid": "0","tid": "Node0/Proc0/Thread20041","ts": "11607","dur": "17783","args": {"...":"..."}},
{"ph": "X","name": "Memset","pid": "1","tid": "Node0/SET","ts": "29329","dur": "12","args": {"...":"..."}},

{"ph": "s", "cat": "DataFlow", "id": 220041, "pid": 0, "tid": "Node0/Proc0/Thread20041", "ts": 29329, "name": "dep"},
{"ph": "t", "cat": "DataFlow", "id": 220041, "pid": 1, "tid": "Node0/SET", "ts": 29330, "name": "dep"}


{"ph": "s", "cat": "DataFlow", "id": 220041, "pid": 0, "tid": "Node0/Proc0/Thread20041", "ts": 29329, "name": "dep"},
{"ph": "f", "bp": "e", "cat": "DataFlow", "id": 220041, "pid": 1, "tid": "Node0/SET", "ts": 29330, "name": "dep"}

7. Snapshot 事件

ph: "O"
单点事件，显示为显眼的圆点，可以绑定 args.snapshot 提供详细快照信息。
示例：

1
{"ph": "O", "name": "测试", "id": "test", "pid": "0", "tid": "Node0/Proc0/Thread20041", "ts": 59600, "args": {"snapshot": "data state"}}

三、可选参数

cname：自定义颜色（颜色列表）

1
{"ph": "X", "name": "hipMalloc", "cname": "good", "pid": "0", "tid": "Node0/Proc0/Thread9643", "ts": 35996, "dur": 17868, "args": {"...": "..."}}

常见颜色：
- "rail_load"：蓝色
- "good"：绿色
- "bad"：红色
- "terrible"：深红
- "cq_build_running"：紫色

四、事件类型总结表

Phase	含义	显示效果	备注
X	完整事件	区间块	推荐
B/E	开始/结束	区间块	可用
M	元数据	标题栏显示	设置名称、排序
I	瞬时事件	小点	类似标记
b/e	异步事件	独立一行，斜体	顶部黑线
s/t 或 s/f	Flow事件	箭头连接	数据/依赖流动
O	快照	圆点	提供状态信息