RFC-0003：Fuchsia 日志记录指南

摘要

日志记录广泛用于整个 Fuchsia 代码中，但记录的消息的严重程度不一致。这会降低日志中信息的价值。下面，我们将针对不同的日志严重程度级别提出语义含义，并说明在各种环境中以特定严重程度记录日志的含义。

动机和问题陈述

日志是发送有关正在运行的软件内部状态发生变化的诊断信号的最常见方式。它们提供有价值的信息，可用于检测和纠正软件和产品中的故障。

从历史上看，日志包含自由文本消息以及枚举的严重程度值。严重程度值用于指示消息的重要性，从而区分信号与噪声。不过，Fuchsia 代码及其依赖项中严重程度级别的应用并不一致，导致日志难以用于手动问题排查和自动分析。

通过提供有关如何使用日志严重程度的通用准则，并创建将后果附加到某些日志使用方式的流程，我们希望创建一个良性循环，从而从日志中生成更多诊断价值，同时提高信噪比。例如，我们希望将 ERROR 日志条目的频率作为系统稳定性的一个代理指标。

实现

日志严重级别

Fuchsia 支持多种标准日志严重程度：

FATAL

这表示出现了无法恢复的错误，组件应在记录消息后不久自行终止。这通常表示系统中的核心不变量已被违反，继续操作可能会导致数据损坏或安全漏洞。

应谨慎使用此日志级别。此日志级别可能表示存在需要修复的硬件问题或软件 bug。由于给定的消息将是组件自我终止之前记录的最后一条消息，因此其内容应指明终止原因。

ERROR

此日志级别表示发生了程序可以从中恢复的不良事件。日志中出现 ERROR 日志条目表明程序行为不正确，需要修复。开发者应力求使 bug 跟踪器中的 bug 与 ERROR 日志条目一一对应。换句话说，对于每个唯一 bug，都应有一个 ERROR 日志条目；对于每个 ERROR 日志条目，都应有一个单独的 bug。开发者应尽可能在代码中尝试保持这种对应关系。请注意，bug 可能不在发出日志语句的代码中。该 bug 可能位于某个调用方或其某个依赖项中。

此日志级别及更高级别将作为系统稳定性指标的信号。此外，此日志级别及更高级别的日志通常会出现在 bug 报告中。 此日志消息将由引入该消息的团队以外的人员使用，因此应提供足够的上下文来引导读者找到问题的根本原因。

警告

此日志级别表示系统正常运行期间发生了意外事件。这些意外事件可能是环境因素造成的，因此不受系统本身的控制。例如，丢失的网络连接可能会记录为 WARNING，或者阻止程序继续运行的无效输入可能会记录为 WARNING。此日志级别可用于查找导致问题的根本原因（通常是 ERROR 日志条目）。此日志级别可用于突出显示由于上述意外事件而采取了不常见的代码路径。

INFO

这通常是 bug 报告中存在的最低日志级别。这表示程序中发生了值得注意的状态变化。此日志级别用于指示导致问题的上下文（通常是 ERROR 日志条目）。与更高级别的日志一样，这些日志将供其他团队用于诊断，因此上下文至关重要。

持久状态应使用组件检查进行报告。如果此类条件未发生变化，则不应记录。例如，Inspect 数据可能包含“configs_found = false”或“config_count = 0”标志，而不是以固定间隔记录“[INFO] no configs found”。

DEBUG

此日志级别通常用于工程环境，例如在测试期间或在提交队列机器人中重现问题时。严重程度为 DEBUG 及更低的日志通常不会收集在 bug 报告中，因此不应期望在 bug 报告中收到 DEBUG 及更低的日志。此日志级别通常比 INFO 更详细，有助于各个团队更好地了解他们正在开发的系统的状态。

TRACE

此日志级别通常由各个团队使用，也可能在提交队列和持续集成中使用。此日志级别通常用于指示多阶段流程中的某个阶段已完成。

记录日志的后果

在为选择日志严重程度级别建立指导原则后，我们提出了几种根据日志严重程度自动处理日志的方式。

日志作为现场分析

我们选择将 ERROR 日志条目的存在视为需要修复的软件 bug 的指示。可以放心地假设，软件作者会希望知道自己的软件正在其本地环境之外记录错误。因此，我们将统计按源组件实例细分的 ERROR 和 FATAL 日志条目的存在情况，通过 Cobalt 报告这些信息，并将这些计数器作为现场稳定性指标进行跟踪。

如需查看设备上的日志记录统计信息概览，请使用以下命令：

cs --log-stats

组件统计信息 (cs) 提供了一种日志统计信息模式，该模式会解析 Archivist 的检查树，以提供每个组件生成的日志的摘要视图。借助此视图，工程师可以了解其组件生成的日志类型，以及与其他组件相比，该组件生成各种日志的频率。

日志（作为测试中的预期/非预期行为）

可以放心地假设，软件作者会希望知道自己的软件在测试期间设置的受控条件下记录了错误，即使这种行为并非预期。因此，我们将在测试运行时引入一种行为，如果在测试领域内观察到意外的 ERROR 日志，则会导致测试失败。

上述测试运行时行为已实现、测试并记录在文档中。

安全注意事项

• 严重程度为 FATAL 的日志通常表示系统中的核心不变量已被违反，继续执行可能会导致数据损坏或安全漏洞。在这种情况下，终止是最安全的做法。

• 组件框架可以安全地将日志的来源识别到组件级别。在组件内，模块很可能经过自我证明，因此无法像组件级识别那样受到同等程度的信任。

隐私保护注意事项

任何日志记录分析都应避免泄露任何个人身份信息 (PII)。例如，我们不应在设备外指标中公开用户设备上的完整组件集，也不应公开可能包含任何 PII 的任何日志消息的完整文本。

文档

我们还打算将这些日志记录指南发布为 Fuchsia 开发指南。

缺点、替代方案和未知因素

上述建议的更改会创建一个激励和惩罚系统，以鼓励或阻止用户以特定方式登录。目的是从日志中获得更多价值 - 通过为重要日志条目提供适当的高严重程度来注意到它们，同时减少严重程度过高的不太重要的日志条目的数量。

我们认为，这些激励措施可能会促成不良行为，例如完全避免 ERROR 日志条目（即使在需要记录此类条目的情况下也是如此）。我们相信，对创建更优质软件的渴望会促使开发者在应对拟议的变更时做出负责任的决定。

我们将通过分析 bug 报告和偶尔与团队成员进行访谈来监控开发者行为，从而检验上述假设，并根据需要进行调整。

在先技术和参考资料

Google Testing Blog 针对日志记录级别提供了一些基本准则。