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

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

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

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

与交互式跟踪记录类似，您可以在 并将它设置为在一段时间后停止。

如需使用计时器启动后台跟踪记录，请运行以下命令：

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 文件后，打开该文件 来直观呈现轨迹结果。

请执行以下操作：

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

对 FIDL 跟踪记录进行符号化处理

如果收集的跟踪记录包含 kernel:ipc 类别，则 .fxt 跟踪文件将包含一些与 FIDL 对应的通道消息事件 跟踪期间进行的调用。这些频道消息只会 包含与 FIDL 调用相关联的序数，该序号是 所调用的方法。

Fuchsia build 目录包含名称以 .fidl.json 结尾的文件。 这些文件包含将序数转换为 相应的 FIDL 方法，并在 Fuchsia 构建期间生成。只要 有 Fuchsia 构建目录可用时，这些文件可用于用符号表示 跟踪文件中的序数映射到相应的 FIDL 方法

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

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

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

ir-path 参数可用于提供要用于特定 IR 文件 符号化。这允许使用提供的 IR 文件，即使没有 Fuchsia build 目录也是如此。

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

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 界面事件（浏览器用户体验、浏览器） 微件、合成器和 GPU）。
  • #chrome_web_content_render：内容呈现事件（Blink、 合成器和 GPU）。

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

指定类别时，您可以将 Chrome 类别与 紫红色类别。例如，下面的命令会收集轨迹数据 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'

为使上述命令正常运行，必须已设置跟踪记录的代码 来触发事件。