以编程方式生成 trace 的高级指南

本文档作为以编程方式创建 Perfetto trace 文件的高级参考。它基于"将任意时间戳数据转换为 Perfetto"中介绍的基本概念和示例。

我们假设你熟悉：

• Perfetto traces 的基本结构(包含 TracePacket 消息流的 Trace 消息)
• 在 TracePacket 中使用 TrackEvent 有效负载创建具有各种类型的 Slice(简单、嵌套、异步)、Counter 和流程的自定义 Track
• 用于生成 trace 的 Python 脚本模板（trace_converter_template.py），并且此处提供的 Python 示例旨在在其 populate_packets(builder) 函数中使用。

本指南涵盖高级 TrackEvent 功能，分为以下几个领域：

• 将 Track 与 OS 概念相关联： 将 Timeline 数据附加到操作系统（OS）进程和线程，以实现更丰富的集成。
• 自定义 Track 显示： 控制 UI 如何排序、合并和呈现 Track。
• Interning： 通过去重频繁重复的字符串和调用栈来减小 trace 大小。
• 用额外数据丰富事件： callstack weight、correlation ID，以及通过 proto 扩展定义的完全自定义类型字段。
• 处理大型 trace： 将 packet 流式传输到磁盘以保持低内存使用。

虽然 TrackEvent 是表示 Timeline 数据的主要方法，但 TracePacket 是一个多功能容器。将来，本指南可能会扩展以涵盖其他对合成 trace 生成有用的 TracePacket 有效负载。

示例将继续使用 Python，但这些原则适用于任何具有 Protocol Buffer 支持的语言。有关所有可用字段的完整定义，请始终参考官方 Perfetto protobuf 源代码，特别是 TracePacket 及其各种子消息，包括 TrackEvent。

将 Track 与操作系统概念相关联

虽然 "将任意时间戳数据转换为 Perfetto" 指南演示了创建通用自定义 Track，但你可以通过将 Track 与操作系统（OS）进程和线程相关联来为 Perfetto 提供更具体的上下文。这允许 Perfetto 的 UI 和分析工具提供 更丰富的集成和与其他系统范围数据的更好关联。

将 Track 与进程相关联

你可以创建表示操作系统进程的顶级 Track。任何其他自定义 Track（可能包含 Slice 或 Counter）都可以父化到此进程 Track。这有助于：

• UI 分组： 你的自定义 Track 将出现在 Perfetto UI 中指定进程名称和 PID 下，与为该进程收集的任何其他数据（例如，CPU 调度、内存 Counter）一起。
• 关联： 你的自定义 Track 上的事件可以更容易地与与该进程相关的系统级别活动相关联。
• 清晰标识： 明确命名进程并提供其 PID 使你的自定义数据与哪个进程相关变得明确。

要定义进程 Track，请在其 TrackDescriptor 中填充 process 字段。至少，你应该提供 pid，理想情况下还应提供 process_name。

还建议将 timestamp 添加到包含进程的 TrackDescriptor 的 TracePacket 中。这尤其重要，当 trace 包含来自其他源的数据（例如，来自内核的调度信息）时。与"全局"Track 不同，这些 Track 类型可能会与其他数据源交互，因此具有时间戳可确保 Trace Processor 可以准确地将描述符排序到正确的位置。

Python 示例：进程范围的 Counter

假设你想发出一个自定义 Counter（例如，"活动数据库连接"）并让它出现在名为 "MyDatabaseService" 且 PID 为 1234 的特定进程下。

将以下 Python 代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

你可以在 Perfetto UI 的 Query 选项卡中使用 SQL 或使用 Trace Processor 查询与进程关联的 Counter 数据：

一旦你定义了进程 Track，就可以将各种其他类型的 Track 父化到它。这包括该进程内特定线程的 Track(见下一节)，以及进程范围 Counter 的自定义 Track（如上所示）或与此进程相关的异步操作组(使用 "将任意时间戳数据转换为 Perfetto" 指南中描述的异步 Slice 技术)。

有关如何显式控制进程 Track 显示顺序的详细信息，请参阅控制 Track 排序顺序。

将 Track 与线程相关联

你可以创建明确与操作系统进程内特定线程关联的 Track。这是表示线程特定活动（如函数调用堆栈或线程本地 Counter）的最常见方式。

好处：

• 正确的 UI 放置： 当线程 Track 的 pid 和 tid 在其 TrackDescriptor 中指定时，Perfetto UI 通常将其分组在对应的进程（由该 pid 标识）下。这有助于组织 trace。
• 与系统数据关联： Perfetto 可以自动将你的线程 Track 上的事件与该线程的系统级别数据（如 CPU 调度 Slice）相关联。
• 清晰命名： 你可以为线程提供人类可读的名称。

要定义线程 Track:

1. 为线程创建 TrackDescriptor。
2. 填充其 thread 字段，提供此线程所属进程的 pid 和线程的唯一 tid。你还应该设置 thread_name。
3. 可选但鼓励的是，你还可以为父进程本身定义一个单独的 TrackDescriptor(使用其 process 字段和 pid)，尽管这不是线程 Track 被识别为该 PID 的线程的严格要求。UI 通常根据线程 Track 中存在的 PID 推断进程分组。

与进程 Track 类似，还建议将 timestamp 添加到包含线程的 TrackDescriptor 的 TracePacket 中。这尤其重要，当 trace 包含来自其他源的数据（例如，来自内核的调度信息）时。与"全局"Track 不同，这些 Track 类型可能会与其他数据源交互，因此具有时间戳可确保 Trace Processor 可以准确地将描述符排序到正确的位置。

Python 示例：特定于线程的 Slice

此示例定义了一个属于进程 "MyApplication" (PID 1234) 的线程 "MainWorkLoop" (TID 5678)。然后，它直接在此线程的 Track 上发出几个 Slice。为了清晰起见，我们还定义了进程本身的 Track，尽管线程 Track 的关联主要通过其 pid 和 tid 字段进行。

将以下 Python 代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

你可以在 Perfetto UI 的 Query 选项卡中使用 SQL 或使用 Trace Processor 查询特定于线程的 Slice：

有关如何显式控制进程内线程显示顺序的详细信息，请参阅控制 Track 排序顺序。

自定义 Track 显示

除了将 Track 与操作系统概念相关联之外，Perfetto 还提供了微调 Track 在 UI 中呈现方式的方法：同级 Track 如何排序和合并、counters 如何共享其比例，以及 Track 如何向用户描述。

控制 Track 排序顺序

默认情况下，Perfetto UI 应用自己的启发式方法对 Track 进行排序（例如，按名称字母顺序，或按 Track UUID）。但是，对于复杂的自定义 trace，你可能希望明确定义 Track 的出现顺序。此排序行为因你是排列标准自定义子 Track、进程还是进程内的线程而有所不同。

Child Track 排序

对于通过 parent_uuid 父化到另一个自定义 Track 的标准自定义 Track，你可以在父 Track 上配置子 Track 排序。

此设置仅影响该父 Track 的直接子 Track。

可用的 child_ordering 模式（在 TrackDescriptor.ChildTracksOrdering 中定义）：

• UNKNOWN：默认值。UI 将使用自己的启发式方法。
• LEXICOGRAPHIC：子 Track 按其 name 或 static_name 的字母顺序排序。
• CHRONOLOGICAL：子 Track 根据每个 Track 上发生的最早 TrackEvent 的时间戳排序。具有较早事件的 Track 排在前面。
• EXPLICIT：子 Track 根据各自 TrackDescriptor 中设置的 sibling_order_rank 字段排序。排名较低的排在前面。如果排名相等或未设置 sibling_order_rank，则决胜顺序未定义。

进程排序

要显式控制 UI 如何显示顶级进程 Track 之间的相对顺序，你必须配置根 Track 描述符（uuid = 0）。

1. 将根 Track 描述符（uuid = 0）上的 process_ordering 设置为 PROCESS_ORDERING_EXPLICIT。
2. 在各个进程 TrackDescriptor 上定义 sibling_order_rank。排名较低的进程将首先出现。未指定的排名默认为 0。

可用的 process_ordering 模式（在 TrackDescriptor.ProcessOrdering 中定义）：

• PROCESS_ORDERING_UNSPECIFIED：默认值。UI 将使用自己的启发式方法。
• PROCESS_ORDERING_EXPLICIT：按进程 Track 描述符的 sibling_order_rank 对进程进行排序。

线程排序

要显式控制 UI 如何显示进程组内线程 Track 之间的相对顺序，你必须配置根 Track 描述符（uuid = 0）。

1. 将根 Track 描述符（uuid = 0）上的 thread_ordering 设置为 THREAD_ORDERING_EXPLICIT。
2. 在各个线程 TrackDescriptor 上定义 sibling_order_rank。排名较低的线程将首先出现。未指定的排名默认为 0。

可用的 thread_ordering 模式（在 TrackDescriptor.ThreadOrdering 中定义）：

• THREAD_ORDERING_UNSPECIFIED：默认值。UI 将使用自己的启发式方法。
• THREAD_ORDERING_EXPLICIT：按线程 Track 描述符的 sibling_order_rank 对线程进行排序。

注意： UI 将这些视为强提示。虽然它通常尊重这些排序，但在某些情况下，UI 保留不按此顺序显示它们的权利；通常，如果用户明确请求此操作，或者 UI 对这些 Track 有特殊处理，则会发生这种情况。

Python 示例：演示所有排序类型

此示例定义了三个父 Track，每个 Track 演示不同的 child_ordering 模式，同时在根 Track 上配置了显式的进程和线程排序。

将以下 Python 代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

控制 Track 合并

默认情况下，Perfetto UI 合并共享相同名称的 Track。这通常是用于分组相关异步事件的所需行为。但是，在某些情况下，你需要更明确的控制。你可以使用 TrackDescriptor 中的 sibling_merge_behavior 和 sibling_merge_key 字段覆盖此默认合并逻辑。

这允许你：

• 防止合并： 强制 Track（即使具有相同名称）始终单独显示。
• 按键合并： 强制 Track 根据自定义密钥合并，无论它们的名称如何。

sibling_merge_behavior 字段可以设置为以下值之一：

• SIBLING_MERGE_BEHAVIOR_BY_TRACK_NAME(默认)：合并具有相同 name 的同级 Track。
• SIBLING_MERGE_BEHAVIOR_NONE：防止 Track 与其任何同级合并。
• SIBLING_MERGE_BEHAVIOR_BY_SIBLING_MERGE_KEY：合并具有相同 sibling_merge_key 字符串的同级 Track。

Python 示例：防止合并

在此示例中，我们创建两个具有相同名称的 Track。通过将其 sibling_merge_behavior 设置为 SIBLING_MERGE_BEHAVIOR_NONE，我们确保它们 始终在 UI 中显示为不同的 Track。

Python 示例：按键合并

在此示例中，我们创建两个具有不同名称但相同 sibling_merge_key 的 Track。通过将其 sibling_merge_behavior 设置为 SIBLING_MERGE_BEHAVIOR_BY_SIBLING_MERGE_KEY，我们指示 UI 将它们 合并到单个视觉 Track 中。合并组的名称将取自其中一个 Track(通常是具有较低 UUID 的 Track)。

在 Counters 之间共享 Y 轴

在可视化多个 Counter Tracks 时，让它们共享相同的 Y 轴范围通常很有用。这允许轻松比较它们的值。Perfetto 通过 CounterDescriptor 中的 y_axis_share_key 字段支持此功能。

所有具有相同 y_axis_share_key 和相同父 Track 的 Counter Tracks 将在 UI 中共享它们的 Y 轴范围。

Python 示例：共享 Y 轴

在此示例中，我们创建两个具有相同 y_axis_share_key 的 Counter Tracks。这将导致它们在 Perfetto UI 中使用相同的 Y 轴范围进行渲染。

添加 Track 描述

你可以向任何 Track 添加人类可读的描述，以提供有关其包含数据的更多上下文。在 Perfetto UI 中，当用户单击 Track 名称旁边的帮助图标时，此描述会出现在弹出窗口中。这对于解释 Track 代表什么、其事件的含义或应如何解释它特别有用，尤其是在复杂的自定义 trace 中。

要添加描述，只需在 Track 的 TrackDescriptor 中设置可选的 description 字段。

Python 示例：Track 描述

此示例定义了两个 Track：一个设置了 description 字段，一个没有，以说明 UI 中的差异。

将以下 Python 代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

驻留数据以优化 trace 大小

驻留是一种通过仅在 trace 中发出一次频繁重复的字符串（如事件名称或类别）来减少 trace 文件大小的技术。对这些字符串的后续引用使用紧凑的整数标识符（"驻留 ID"或 iid）。当你有许多事件共享相同名称或其他基于字符串的属性时，这特别有用。

它如何工作：

1. 定义驻留数据： 在 TracePacket 中，你包含一个 interned_data 消息。在其中，你将字符串映射到 iids。例如，你可以定义 event_names，其中每个条目都有一个 iid（你选择的一个非零整数）和一个 name 字符串。此数据包建立映射。

2. 通过 IID 引用： 在后续的 TrackEvent 中（在相同的 trusted_packet_sequence_id 内且在驻留状态被清除之前）， 你不是直接设置 name 字段，而是将相应的 name_iid 字段设置为你定义的整数 iid。

3. 序列标志： TracePacket.sequence_flags 字段至关重要：

   • SEQ_INCREMENTAL_STATE_CLEARED（值 1）：如果此序列的驻留字典（和其他增量状态）需要在处理此数据包的 interned_data 之前被视为已重置，请在此数据包上设置。这通常用于定义驻留条目的序列的第一个数据包上。
   • SEQ_NEEDS_INCREMENTAL_STATE（值 2）：在定义新驻留数据条目或使用在先前数据包中（在序列的当前有效状态内）定义的 iid的任何数据包上设置此数据包。

   通常为序列初始化驻留字典的数据包将设置两个标志： TracePacket.SEQ_INCREMENTAL_STATE_CLEARED | TracePacket.SEQ_NEEDS_INCREMENTAL_STATE。 使用这些已建立的驻留条目（或向现有的有效字典添加更多条目）的数据包将设置 TracePacket.SEQ_NEEDS_INCREMENTAL_STATE。

Python 示例：驻留事件名称

此示例显示如何为事件名称定义驻留字符串，然后多次使用它。

将以下 Python 代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

驻留调用堆栈

入门指南 涵盖了简单用例的内联调用堆栈。本节涵盖了高效驻留调用堆栈，用于调用堆栈重复或需要二进制映射信息进行符号化的情况。

驻留调用堆栈在 InternedData 中定义一次调用堆栈结构，并从多个事件中通过 ID 引用它。至少你只需要定义： 帧、调用堆栈，并从你的事件中引用这些调用堆栈。其他部分是可选的，当你拥有该信息时可以提供：

1. 构建 ID 和 映射路径 → 映射(二进制文件/库)。如果你没有二进制元数据，则可以完全跳过此内容。
2. 映射 → 帧(函数 + 位置)。mapping_id、rel_pc、source_path_iid、line_number 等都是可选的——只设置对你的数据有意义的部分。
3. 帧 → 调用堆栈(帧序列)
4. 调用堆栈 → 事件(通过 callstack_iid)

Python 示例：驻留调用堆栈

此示例演示了驻留调用堆栈的完整工作流程，包括映射、帧和调用堆栈。对于最小 trace，你可以跳过映射条目，并仅使用函数名称（以及你拥有的任何位置详细信息）填充帧。

将以下 Python 代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

注意：

• 序列标志：定义驻留数据（首次）时使用 SEQ_INCREMENTAL_STATE_CLEARED | SEQ_NEEDS_INCREMENTAL_STATE；之后仅使用 SEQ_NEEDS_INCREMENTAL_STATE 来引用它或定义更多增量数据。
• 帧顺序： frame_ids 从最外到最内排序（与内联调用堆栈相同）。
• 重用：事件 3 重用 CALLSTACK_1，演示效率增益。

运行脚本后，在 Perfetto UI 中打开生成的 trace 并进行区域选择将显示以下输出：

用额外数据丰富事件

除了名称和时间戳之外，每个事件还可以携带额外数据：改变 callstack 如何聚合到火焰图的 weight、将相关事件链接在一起的 correlation ID，以及通过你自己的 protobuf schema 定义的完全自定义类型字段。

加权调用堆栈与自定义 measure

默认情况下，附加到事件的每个 callstack 在聚合到火焰图时只计数一次：这就是 Samples measure。然而，通常每次出现应该贡献不同的量：该 stack 分配的字节数、归因于它的延迟，等等。

TrackEvent 上的 callstack_weight 字段为记录在该事件上的 callstack 附加一个可选的加性值。它适用于 inline callstacks 和 interned callstacks（callstack_iid），以及 begin 和 end 事件：

需要记住的关键规则：加权聚合只包含设置了 callstack_weight 的事件；加权和未加权样本永远不会混合。 如果你的某些事件设置了 weight 而其他事件没有，则 "Weight" measure 只覆盖加权事件，而 "Samples" 继续计数所有事件。要获得有意义的加权火焰图，请在每个事件上（在给定 track 上）都设置 weight，或都不设置。

除了 weight 之外，附加到携带 callstack 的事件的任何数字参数都可以在 UI 中用作额外的火焰图 measure。这包括 debug annotations 和来自 proto 扩展 的整数/双精度字段 — 任何最终作为 args 表中数字条目的内容。这让单个事件流可以携带多个并行 measure：例如，allocation profiler 可以使用 callstack_weight 表示字节数，使用 objects debug annotation 表示对象数量。

Python 示例：加权调用堆栈

此示例模拟一个简单的 allocation profiler：每个 slice 记录分配的 callstack，callstack_weight 设置为分配的字节数，以及两个额外的每事件 measure — 一个统计分配对象数量的 objects debug annotation，以及一个记录分配耗时的 alloc_stats.latency_us proto 扩展字段。

该扩展使用 使用 Proto 扩展附加自定义类型字段 中描述的双文件描述符设置。如果你只需要 weight 和 debug annotation，可以跳过两个 .proto 文件并删除 Python 代码中与扩展相关的行。

文件 1 — alloc_stats.proto （数据模式，编译为 Python 绑定）：

文件 2 — alloc_stats_extension.proto （扩展 hook，编译为嵌入 trace 的描述符集）：

然后将以下 Python 代码复制到 trace_converter_template.py 脚本中的 populate_packets(builder) 函数。

运行脚本后，在 Perfetto UI 中打开生成的 trace 并对 Allocations track 进行区域选择。"Track Event Callstacks" 标签页中的火焰图默认使用 Weight measure，前提是至少有一个选中的样本设置了 callstack_weight；否则回退到 Samples：

measure 选择器（火焰图左上角的下拉菜单）允许你在内置 measure 之间切换并添加新的 measure。"Add measure..." 打开一个可搜索列表，包含所选事件上找到的每个数字参数。Debug annotations 显示为 debug. 前缀（本例中为 debug.objects），而 proto 扩展字段显示在其字段名（alloc_stats.latency_us）下：

选择一个会将其添加为 measure：然后火焰图会像 weight 一样聚合该参数在所选 callstack 中的值。下面是按 debug.objects 测量的相同选择 — 注意火焰图的形状如何变化，因为 RenderOutput 分配的对象比 ParseInput 多得多，尽管分配的字节数更少：

与 callstack_weight 一样，只有实际拥有该参数的样本才会包含在该 measure 中。

使用关联 ID 链接相关事件

关联 ID 提供了一种视觉上将属于同一逻辑操作的 Slice 链接起来的方法，即使它们没有因果连接。与代表直接因果关系的流程不同，关联 ID 对共享公共上下文或属于同一高级操作的事件进行分组。

常见用例：

• GPU 渲染： 链接在不同 GPU 阶段中涉及渲染同一帧的所有切片
• 分布式系统： 在通过不同服务移动时对与同一 RPC 请求相关的所有 Slice 进行分组
• 网络处理： 连接通过不同内核阶段处理同一网络请求的所有 Slice

视觉好处： Perfetto UI 可以使用关联 ID 为相关 Slice 分配一致的颜色，或者在悬停一个 Slice 时突出显示整个关联集，从而更容易追踪不同 Track 上的相关操作。

与流程的关系：

• 当事件有直接的因果关系时使用流程(A 触发 B)
• 当事件是同一逻辑操作的一部分但未直接连接时使用关联 ID
• 你可以同时使用两者：在关联组内的因果连接使用流程

Perfetto 支持三种类型的关联标识符：

• correlation_id：一个 64 位无符号整数(最高效，推荐用于 大多数情况)
• correlation_id_str：一个字符串值(最灵活，人类可读)
• correlation_id_str_iid：一个驻留字符串 ID(参见 驻留数据以优化 trace 大小 有关驻留的详细信息)

Python 示例：关联 ID

此示例通过模拟跨越多个服务 Track 的两个单独请求的处理的不同阶段来演示使用整数标识符的关联 ID。

将以下 Python 代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

使用 Proto 扩展附加自定义类型字段

当 debug_annotations 不够表达力时 — 你想要具有嵌套消息、重复字段或下游工具可以依赖的类型的真实模式 — 使用 protobuf 扩展扩展 TrackEvent。Trace Processor 会自动将每个解码的扩展字段解析到 args 表中，前提是其描述符可用。

有关该机制的完整说明（字段编号分配、包装消息要求、描述符到达 Trace Processor 的三种方式），请参阅使用自定义 Proto 扩展 TrackEvent。本节重点介绍手动 trace 写入流程：如何使用标准 protobuf Python API 设置扩展字段并将描述符嵌入 trace 中，使结果自包含。

双文件设置

将模式拆分为两个 .proto 文件。

文件 1 — acme_data.proto 是你的常规数据模式。你将为此文件生成 Python 绑定并像任何其他 protobuf 消息一样使用它们。

文件 2 — acme_extension.proto 是扩展 Hook：它将数据消息绑定到 TrackEvent 上的特定字段编号。你永远不要为此文件导入 Python 绑定 — 其唯一目的是生成嵌入在 trace 中的 FileDescriptorSet，以便 Trace Processor 知道如何解码该字段编号。

将 perfetto_trace.proto 的副本（从 GitHub 下载）放在 protos/perfetto/trace/ 下：

从 project/ 编译：

Python 示例：设置扩展字段

扩展有效负载作为 protobuf 线字节写入 TrackEvent — 一个长度分隔的字段（线类型 2），其值是数据消息的序列化字节。

将以下代码复制到你的 trace_converter_template.py 脚本中的 populate_packets(builder) 函数中。

导入生成的 trace 后，扩展字段可以使用 EXTRACT_ARG 查询。Trace Processor 按名称（request_metadata）键入扩展字段，并使用点表示法展平嵌套消息；重复字段使用 [N] 索引。

使用流处理大型 trace

到目前为止，所有示例都使用了 TraceProtoBuilder，它在将 trace 写入文件之前在内存中构建整个 trace。这对于中等大小的 trace 简单有效，但如果你生成具有数百万事件的 trace，则可能会导致高内存消耗。

对于这些情况，StreamingTraceProtoBuilder 是推荐的解决方案。它在创建每个 TracePacket 时将其写入文件，无论 trace 大小如何，都保持内存使用最小化。

它如何工作

流式构建器的 API 略有不同：

1. 初始化： 你使用以二进制写入模式打开的类文件对象初始化 StreamingTraceProtoBuilder。
2. 数据包创建： 调用 builder.create_packet() 而不是 builder.add_packet() 来获取新的空 TracePacket。
3. 数据包写入： 填充数据包后，必须显式调用 builder.write_packet(packet) 以将其序列化并写入文件。

Python 示例：完整的流式脚本

这是一个完整的、独立的 Python 脚本，演示如何使用 StreamingTraceProtoBuilder。它基于 入门指南 中的"创建基本 Timeline Slice"示例。

你可以将此代码保存为新文件（例如，streaming_converter.py）并运行它。