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

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

我们假设你熟悉：

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

本指南目前将专注于高级 TrackEvent 功能，例如：

• 将你的 Timeline 数据与操作系统（OS）进程和线程相关联，以实现更丰富的集成。
• 显式 Track 排序和数据驻留，以优化 trace 大小和细节。

虽然 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（例如，"活动数据库连接"）并让它出现在名为 "MyDatabaseService" 且 PID 为 1234 的特定进程下。

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

如果你只有符号化的函数名称，则仅使用驻留的函数名称 ID 调用 add_frame(...)：例如，add_frame(packet.interned_data, FRAME_MAIN, FUNC_MAIN)。

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

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

将 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 与操作系统概念相关联之外，Perfetto 还提供了微调 Track 呈现方式和数据编码方式的方法。

控制 Track 排序顺序

默认情况下，Perfetto UI 应用自己的启发式方法对 Track 进行排序（例如，按名称字母顺序，或按 Track UUID）。但是，对于复杂的自定义 trace，你可能希望明确定义同级 Track 在父 Track 下出现的顺序。这是使用父 Track TrackDescriptor 上的 child_ordering 字段和对于 EXPLICIT 排序使用子 Track TrackDescriptor 上的 sibling_order_rank 来实现的。

父 Track 上的此 child_ordering 设置仅影响其直接子 Track。

可用的 child_ordering 模式(在 TrackDescriptor.ChildTracksOrdering 中定义):

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

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

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

此示例定义了三个父 Track，每个 Track 演示不同的 child_ordering 模式。

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

在 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：一个设置了 description 字段，一个没有，以说明 UI 中的差异。

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

高级事件写入

本节涵盖了专业用例的高级 TrackEvent 功能，包括数据优化技术和事件链接机制。

驻留数据以优化 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_file_id、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并进行区域选择将显示以下输出：

使用关联 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 示例

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

将以下 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)。

使用流处理大型 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。它基于 [入门指南](/docs/getting-started/converting.md）中的"创建基本 Timeline Slice"示例。

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