记录跟踪记录以进行性能分析

ffx trace 命令可以记录 Fuchsia 设备的诊断轨迹数据。这些数据可用于衡量和调试性能问题、了解线程、进程和组件之间的互动，以及直观呈现整个系统。

添加 Fuchsia 跟踪事件

如需有关如何将 Fuchsia 跟踪添加到代码中的完整端到端指南，请参阅 Fuchsia 跟踪教程。

概念

Fuchsia 跟踪系统提供了一种机制，用于收集、汇总和直观呈现来自用户空间进程和 Fuchsia 设备上的 Zircon 内核的诊断跟踪信息。跟踪系统由跟踪管理器、内存缓冲区和一个或多个跟踪提供程序组成。轨迹提供程序是一个在设备上生成轨迹数据的组件，系统可以有多个轨迹提供程序。（如需将组件注册为轨迹提供程序，请参阅注册轨迹提供程序。）

ffx trace start 命令会将跟踪输出存储为宿主机上的 .fxt 文件。您可以在 Perfetto 查看器中打开此文件，以直观呈现轨迹结果以进行性能分析。（如需详细了解 Perfetto，请参阅 Perfetto 文档网站。）

默认情况下，ffx trace start 命令会尝试从一组预定义的轨迹类别收集轨迹数据（运行 ffx trace start --help 可查看默认类别）。不过，ffx trace start 还允许您选择跟踪记录类别来收集跟踪记录数据。

一台 Fuchsia 设备上一次只能运行一个轨迹会话，并且输出文件中只能记录一条轨迹。在下面的示例中，在运行 ffx trace 的目录中，所有输出文件默认为 trace.fxt，并且所有目标设备默认为同时连接到主机的可用 Fuchsia 设备。

以交互方式运行轨迹

使用交互式轨迹时，您可以按 Enter 键，实时决定何时结束轨迹。不过，如果指定了 --duration 标志，跟踪会在达到持续时间时自动停止。（如需详细了解在跟踪运行期间如何将结果存储在缓冲区中，请参阅附录中的缓冲模式选项。）

如需启动交互式轨迹，请运行以下命令：

ffx trace start

此命令会输出类似于以下内容的输出：

$ ffx trace start
Tracing started successfully on "fuchsia-5254-0063-5e7a".
Writing to /Users/alice/trace.fxt
Press <enter> to stop trace.

如需停止跟踪，请按 Enter 键。

该命令会退出，并输出类似于以下内容的输出：

Shutting down recording and writing to file.
Tracing stopped successfully on "fuchsia-5254-0063-5e7a".
Results written to /Users/alice/trace.fxt
Upload to https://ui.perfetto.dev/#!/  to view.

如需分析此次运行收集的结果，请参阅直观呈现轨迹结果。

在后台运行轨迹

只要未指定时长，后台轨迹就会无限期运行。如需停止在后台运行跟踪记录，您需要运行 ffx trace stop。（如需详细了解在轨迹运行期间如何将结果存储在缓冲区中，请参阅“附录”中的缓冲模式选项。）

如需启动后台轨迹，请运行以下命令：

ffx trace start --background

此命令会输出类似于以下内容的输出：

$ ffx trace start --background
Tracing started successfully on "fuchsia-5254-0063-5e7a".
Writing to /Users/alice/trace.fxt
Current tracing status:
- fuchsia-5254-0063-5e7a:
  - Output file: /Users/alice/trace.fxt
  - Duration: indefinite
  - Config:
    - Categories:
      - app,audio,benchmark,blobfs,gfx,input,kernel:meta

如需停止此跟踪，请参阅停止跟踪。

使用计时器在后台运行轨迹

与 Interactive Trace 类似，您可以在后台运行跟踪，并将其设置为在特定时长后停止。

如需使用计时器启动后台轨迹，请运行以下命令：

ffx trace start --background --duration <SECONDS>

将 SECONDS 替换为目标时长（以秒为单位），例如：

$ ffx trace start --background --duration 20

如需手动停止此跟踪，请参阅停止跟踪。

使用触发器在后台运行跟踪记录

如果使用触发器运行轨迹，则在检测到指定事件时停止跟踪。

如需使用触发器运行跟踪记录，请运行以下命令：

ffx trace start --background --trigger <TRIGGER>

使用语法 alert:action 将 TRIGGER 替换为操作，例如：

$ ffx trace start --background --trigger "myexample:terminate"

如需手动停止此跟踪，请参阅停止跟踪。

检查后台轨迹的状态

如需检查后台跟踪记录的状态，请运行以下命令：

ffx trace status

此命令会输出类似于以下内容的输出：

$ ffx trace status
- fuchsia-5254-0063-5e7a:
  - Output file: /Users/alice/trace.fxt
  - Duration: indefinite
  - Config:
    - Categories:
      - app,audio,benchmark,blobfs,gfx,input,kernel:meta

如果后台没有轨迹，该命令会输出以下内容：

$ ffx trace status
No active traces running.

停止跟踪记录

ffx trace stop 命令可停止在后台运行的跟踪记录。

如需停止跟踪，请运行以下命令：

ffx trace stop [--output <FILE>]

默认情况下，该命令会停止与默认目标设备匹配的轨迹。不过，您也可以使用 –output 标志来选择要停止的跟踪记录，该标志随后会停止与输出文件相关联的跟踪记录。

此命令会输出类似于以下内容的输出：

$ ffx trace stop
Tracing stopped successfully on "fuchsia-5254-0063-5e7a".
Results written to /Users/alice/trace.fxt
Upload to https://ui.perfetto.dev/#!/ to view.

如需分析从此运行收集的结果，请参阅直观呈现轨迹结果。

直观呈现跟踪记录结果

完成轨迹并创建 .fxt 文件后，在 Perfetto 查看器中打开该文件以直观呈现轨迹结果。

请执行以下操作：

  1. 在网络浏览器中访问 Perfetto 查看器网站。
  2. 点击导航栏中的 Open trace file。
  3. 从主机中选择 trace.fxt 文件。

符号化处理 FIDL 轨迹

如果收集的跟踪记录包含 kernel:ipc 类别，则 .fxt 跟踪记录文件将包含与跟踪记录期间进行的 FIDL 调用对应的一些通道消息事件。这些通道消息仅包含与 FIDL 调用关联的序数，即被调用方法的 SHA-256 哈希。

Fuchsia 构建目录包含名称以 .fidl.json 结尾的文件。这些文件包含在 Fuchsia build 期间生成，其中包含将序数转换为相应 FIDL 方法所需的信息。只要有 Fuchsia build 目录，这些文件就可以用于将轨迹文件中的原始符号化为相应的 FIDL 方法

如需转换轨迹文件中的所有序数，请使用以下命令：

ffx trace symbolize --fxt <FXT-FILE> [--outfile <OUTFILE>] [--ir-path <ir-path...>]

将 FXT-FILE 替换为轨迹文件的路径。默认情况下，符号化处理后，原始轨迹文件中的轨迹会被覆盖。指定 OUTFILE 参数将导致将跟踪记录写入指定的文件。

ir-path 参数可用于提供要用于符号化的特定 IR 文件。这样，即使没有 Fuchsia build 目录，也可以使用提供的 IR 文件执行符号化操作。

也可以使用以下命令对单个序数进行符号化处理：

ffx trace symbolize [--ordinal <ordinal>] [--ir-path <ir-path...>]

查看跟踪记录类别

借助 ffx trace start 命令，您可以选择用于收集轨迹数据的类别，例如：

$ ffx trace start --categories "kernel,kernel:arch"

如需查看 Fuchsia 设备上的所有可用轨迹类别，请运行以下命令：

ffx trace list-categories

此命令会输出类似于以下内容的输出：

$ ffx trace list-categories
Known Categories:
- app - Generic application traces
- benchmark - Benchmark traces
- cpu - several, run xyz for the list
- gfx - Graphics & Compositor
- input - Input system
- kernel - All kernel trace events
- kernel:arch - Kernel arch events

Default Categories:
- app
- audio
- benchmark
- blobfs

如需详细了解类别，请参阅附录中的类别和类别组。

查看轨迹提供程序

如需查看 Fuchsia 设备上的所有可用轨迹提供程序，请运行以下命令：

ffx trace list-providers

此命令会输出类似于以下内容的输出：

$ ffx trace list-providers
Trace providers:
- ktrace_provider

其他跟踪指南

如需有关在 Fuchsia 中使用轨迹的更多指南，请参阅 Fuchsia 轨迹指南。

附录

类别和类别组

ffx trace start 命令支持特殊语法，可让您更精确地控制启用或停用特定类别：

  • 尾随星号 (*) 会执行前缀匹配。

    例如，kernel* 会启用 kernel:meta, kernel:sched。

  • 使用正斜线 (/) 可将类别限制为特定跟踪提供程序。

    例如，archivist.cm/packet 仅为 archivist 轨迹提供程序启用数据包类别。

ffx trace start 还支持类别组，即以 # 前缀标记的预定义类别列表。例如，#chrome_nav（展开为 loading、net、netlog、navigation 和 browser）用于指定与资源加载和网页导航相关的所有事件，#default 代表一组默认类别。

运行 ffx trace start 时，可以同时指定类别组和类别。例如，以下命令会启用所有默认类别和 my_cat 类别：

$ ffx trace start --categories '#default,my_cat'

如需查看主机上类别组的完整列表，请运行以下命令：

ffx config get -s all trace.category_groups

您可以使用 ffx config set 命令设置自定义类别组。如果要为一组常用类别定义自定义类别组，请运行类似于以下内容的命令：

$ ffx config set trace.category_groups.audiovisual '["audio", "gfx"]'

上面的示例命令定义了一个名为 #audiovisual 的新自定义类别组。

Chrome 和 WebEngine 类别群组

Chrome 专用的类别组可以从 Chrome 和 WebEngine 中收集跟踪记录信息。

以下是 Chrome 类别组的列表：

  • #chrome_input：输入处理事件。
  • #chrome_ipc_flows：Mojo IPC 路由事件。
  • #chrome_js_exec：JavaScript (V8) 事件。
  • #chrome_nav：资源加载、网页导航和浏览器事件。
  • #chrome_task_sched：异步任务调度和调度事件。
  • #chrome_ui_render：Chrome 界面事件（浏览器用户体验、浏览器 widget、合成器和 GPU）。
  • #chrome_web_content_render：内容渲染事件（Blink、合成器和 GPU）。

所有 Chrome 类别组都包含 toplevel 和 toplevel.flow 类别，这些类别涵盖各种基本 Chrome 事件，例如异步任务调度。

指定类别时，您可以将 Chrome 类别与 Fuchsia 类别结合使用。例如，以下命令会收集 Chrome 内容呈现以及 Zircon 内核调度程序活动的轨迹数据：

$ ffx trace start --categories kernel:sched,#chrome_web_content_render

缓冲模式选项

--buffering-mode 标志可让您决定当缓冲区填满时会发生什么。

具体选项包括：

  • oneshot：向缓冲区写入数据，直到缓冲区满，然后忽略所有其他跟踪事件。（这是默认选项。）

  • circular：向缓冲区写入数据，直到缓冲区满为止，然后用新事件替换旧事件。

  • streaming：在跟踪事件到达时将其转发给跟踪管理器。

    streaming 选项会提供额外的缓冲区空间，而且由于会偶尔使用 IPC 将事件发送到轨迹管理器，因此可以牺牲一些开销。

以下命令会使用可用的最大缓冲区大小 (64 MB) 运行轨迹，并使用新事件覆盖旧事件：

$ ffx trace start --buffer-size 64 --buffering-mode circular

与交互模式类似，按 Enter 键可停止跟踪记录。

以下命令会在缓冲区中用新事件覆盖旧事件，并在事件发生时停止跟踪：

$ ffx trace start --buffer-size 64 --buffering-mode circular --trigger 'myexample:terminate'

为了让上述命令正常运行，您必须已设置要触发事件的跟踪代码。