ffx log
是 ffx
中内置的一种日志查看实用程序。本指南介绍了如何配置和使用 ffx log
来查看 Fuchsia 设备上的日志。
如需启动日志查看器,请运行以下命令:
ffx log
此命令会输出当前日志内容,并使连接保持打开状态,以流式传输新的日志条目。如需输出日志的当前内容并退出,请使用 dump
:
ffx log dump
主动式日志记录
运行 ffx
命令后,ffx
守护程序会在后台持续运行。该守护程序会主动发现 Fuchsia 设备,并在这些设备变为可连接时与其连接。
启用主动日志记录功能后,ffx
守护程序会在目标设备连接后立即开始在后台读取日志。这些日志会缓存在主机上,但不超过配置的空间限制。达到空间上限后,日志将“轮替”:删除最旧的日志,为最新的日志腾出空间。
这意味着,当您使用 ffx log
查看日志时,日志实际上是从主机上的缓存中读取的,而不是直接从目标设备读取。一般来说,这应该不会给日志查看器增加任何明显的延迟,除非在极少数情况下设备生成的日志量非常大。
功能
由于日志缓存在宿主机上,因此您可以查看从目标设备缓存的、来自设备之前启动的日志。例如,如果设备崩溃,那么如果这些日志及时缓存,您可能就可以查看崩溃前那一刻的日志。
您可以使用 ffx log dump
查看上一个会话的日志。例如,如需查看设备上次启动的日志,请运行以下命令:
ffx --target <NODENAME> log dump ~1
~1
标识相对于您要查看的最新会话的会话,其中 0
专用于该目标设备的当前活动会话(无论当前活动会话是否存在)。您可以使用 ~2
、~3
等查看早期的启动过程。
配置
以下是与主动式日志缓存相关的 3 项配置设置:
proactive_log.max_sessions_per_target
:要在主机上保持缓存的最大启动会话数量。默认值为 5(即在重新启动 6 次后,系统会删除最早启动会话的日志)。proactive_log.max_session_size_bytes
:要为每个会话缓存的字节数上限。默认值为 100 MB(即磁盘中有 100 MB 的日志后,该会话中最早的日志块就会被删除)proactive_log.max_log_size_bytes
:单个日志分块中使用的字节数上限。您通常不需要更改此设置。默认值为 1MB。
符号化
从设备读取日志时(在将它们写入主机日志缓存之前),系统会在后台对日志进行符号化解析。不过,这种后台处理意味着,symbolizer
主机工具中的配置错误或使用符号索引可能会导致日志无法进行符号化解析,而不会显示任何警告。设置 symbolizer
工具时遇到的错误会记录到 ffx
守护程序日志中。
使用 Fuchsia 源代码结账设置的用户无需执行任何额外配置;符号化操作会自动进行,如在 fx log
中一样。未使用 Fuchsia 源检出设置的用户需要配置适合其开发环境的符号索引。
ffx log
命令会尝试检测 symbolizer
工具中的常见错误配置,但无法检测到所有错误。如果您的日志未进行符号化处理,请提交 bug。
配置符号生成器
有两个与符号化相关的配置参数:
proactive_log.symbolize.enabled
:切换是否尝试符号化。默认值为true
。proactive_log.symbolize.extra_args
:直接传递给symbolizer
主机工具的额外参数的原始字符串。例如,这可用于配置远程符号服务器。默认值为""
。
过滤日志
ffx log
命令提供了一些其他选项,用于过滤从目标设备捕获的日志。您可以根据时间戳、组件、标记或日志级别对日志应用过滤条件。
ffx log --filter hello-world --severity error
如需查看过滤选项的完整列表,请参阅参考文档。
日志垃圾过滤器
您可以从 ffx log
命令的输出中过滤垃圾邮件条目。如需过滤日志,您可以在 ffx
配置中的 log_cmd.spam_filepath
键下定义垃圾内容定义文件的路径,或将其定义为 ffx log
命令 --spam-list-path /path/to/spam/file.json
的标志。如需了解详情,请参阅参考文档。
这样,您就可以定义自己的垃圾内容定义,以过滤掉在开发过程中可能无用的日志。
JSON 架构
日志垃圾内容定义文件以 JSON 格式存储。本部分介绍用于序列化数据的 JSON 架构。
键 | 值类型 | 说明 |
---|---|---|
logSpam | LogSpamEntry 的列表 | 垃圾日志条目列表 |
以下示例展示了空白的日志垃圾定义:
{
"logSpam": []
}
LogSpamEntry
键 | 值类型 | 说明 |
---|---|---|
文件(可选) | 字符串 | 日志垃圾的源文件路径 |
行(可选) | 数字(64 位) | 日志垃圾内容的来源行号 |
payloadRegex(可选) | 字符串 | 与日志垃圾内容的内容匹配的 Rust Regex 字符串 |
以下示例表示一个示例 LogSpamEntry
:
{
"file": "path/to/log_source.cc",
"line": 95,
"payloadRegex": "Disconnected\\.*",
}
在以下任一情况下,LogSpamEntry
均被视为有效(其他组合会被忽略)
“file” | “line” | “payloadRegex” | 行为 |
---|---|---|---|
✓ | ✓ | ✓ | 如果日志的来源与“file”和“line”匹配,且其内容与“payloadRegex”匹配,则将日志标识为垃圾内容 |
✓ | ✓ | ✗ | 如果日志的来源与“file”和“line”匹配,就会将日志标识为垃圾内容 |
✗ | ✗ | ✓ | 如果日志没有来源信息且内容与“payloadRegex”匹配,则将其标识为垃圾内容 |
日志设置
日志过滤条件会修改 ffx log
显示所捕获日志的方式,但不会影响目标设备上组件发出的日志条目。使用 --select
选项发送请求,以在日志记录会话期间配置特定组件的日志设置。这会调整应用于与所提供的用于记录日志的组件选择器匹配的任何组件的日志级别。
ffx log --select component-selector#log-level
您可以使用此参数暂时启用严重级别低于组件配置的最低严重级别的日志(例如 DEBUG
或 TRACE
日志),或禁止来自组件的噪声日志以提高性能。
以下示例为 core/audio
组件启用了调试日志,并禁止所有日志消息(网络组件中的错误除外):
$ ffx log --select core/audio#DEBUG --select core/network/**#ERROR