ffx trace
命令可以记录来自 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>
将 TRIGGER
替换为使用语法 alert:action
的操作,例如:
$ 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 查看器中打开该文件以直观呈现轨迹结果。
请执行以下操作:
- 在网络浏览器上访问 Perfetto 查看器网站。
- 点击导航栏上的 Open trace file。
- 从主机中选择
trace.fxt
文件。
对 FIDL 跟踪记录进行符号化处理
如果收集轨迹时包含 kernel:ipc
类别,则 .fxt
轨迹文件将包含与轨迹持续期间进行的 FIDL 调用相对应的多个通道消息事件。这些通道消息将仅包含与 FIDL 调用关联的序数,即所调用方法的 SHA-256 哈希。
Fuchsia build 目录包含名称以 .fidl.json
结尾的文件。这些文件包含将序数转换为相应的 FIDL 方法所需的信息,并在 Fuchsia build 期间生成。只要 Fuchsia 构建目录可用,这些文件就可用于将跟踪文件中的序数符号化为相应的 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
附录
类别和类别组
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 类别与紫红色类别组合在一起。例如,以下命令会同时收集 Chrome 内容呈现和 Zircon 内核调度程序 activity 的跟踪数据:
$ ffx trace start --categories kernel:sched,#chrome_web_content_render
缓冲模式选项
--buffering-mode
标志可让您决定当缓冲区填满时会发生什么情况。
具体选项包括:
oneshot
:写入缓冲区,直到其被填满,然后忽略所有其他跟踪事件。(这是默认选项。)circular
:写入缓冲区,直至其被填满,然后将旧事件替换为新事件。streaming
:当跟踪管理器到达时,进行前向跟踪事件。由于偶尔会使用 IPC 将事件发送到跟踪管理器,因此
streaming
选项会提供额外的缓冲区空间,但可以牺牲部分开销。
以下命令会运行具有最大可用缓冲区大小 (64 MB) 的跟踪记录,并使用新事件覆盖旧事件:
$ ffx trace start --buffer-size 64 --buffering-mode circular
与交互模式类似,按 Enter
键可停止跟踪。
以下命令会使用缓冲区中的新事件覆盖旧事件,并在事件发生时停止跟踪:
$ ffx trace start --buffer-size 64 --buffering-mode circular --trigger 'myexample:terminate'
为了让上述命令能够正常发挥作用,所跟踪的代码必须已设置为触发相应事件。