RFC-0003：Fuchsia 日志记录指南

摘要

日志记录在 Fuchsia 的代码中被广泛使用，但记录的消息的严重程度不一致。这会降低日志中信息的价值。下面，我们提出了不同日志严重级别的语义含义，以及在不同环境中以特定严重级别进行日志记录的影响。

动机和问题陈述

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

传统上，日志包含自由文本消息以及枚举的严重程度值。严重程度值可指示消息的重要性，从而区分信号和噪声。但是，在 Fuchsia 代码及其依赖项中应用严重级别的方式不一致，导致日志在手动问题排查和自动分析中都难以使用。

通过提供有关如何使用日志严重级别的常见准则，并创建将后果与特定日志使用方式相关联的流程，我们希望形成一个良性循环，从日志中生成更多诊断价值，同时提高信噪比。例如，我们希望将 ERROR 日志条目的频率作为系统稳定性的代理之一。

实现

日志严重级别

Fuchsia 支持多种标准日志严重级别：

严重

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

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

ERROR

此日志级别表示发生了程序可以恢复的意外事件。如果日志中出现 ERROR 日志条目，则表示程序行为不正确，需要进行修复。开发者应努力让 bug 跟踪器中的 bug 与 ERROR 日志条目之间保持一对一对应关系。换句话说，对于每个唯一的 bug，都应有一个 ERROR 日志条目，并且对于每个 ERROR 日志条目，都应有一个单独的 bug。开发者应尽可能在代码中保持这种对应关系。请注意，错误可能并不存在于发出日志语句的代码中。该 bug 可能存在于调用方之一或其依赖项之一中。

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

警告

此日志级别表示系统正常运行期间发生了意外事件。这些意外事件可能是环境因素造成的，因此超出了系统本身的控制范围。例如，网络连接中断可能会记录为“警告”，或者导致程序无法继续的无效输入可能会记录为“警告”。此日志级别可用于查找导致问题的根本原因（通常是 ERROR 日志条目）。此日志级别可用于突出表明，由于上述意外事件，系统采用了非常见的代码路径。

INFO

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

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

DEBUG

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

轨迹

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

日志记录的影响

在确定了选择日志严重级别的指南后，我们提出了几种根据日志严重程度自动处理日志的方法。

将日志用作现场分析

我们选择将存在 ERROR 日志条目视为需要修复的软件 bug 的标志。可以肯定地假设，软件作者会对其软件在本地环境之外记录错误的情况感兴趣。因此，我们将按来源组件实例统计 ERROR 和 FATAL 日志条目的存在情况，通过 Cobalt 报告这些条目，并将这些计数器作为现场稳定性指标进行跟踪。

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

cs --log-stats

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

将日志记录为受测应用的预期/非预期行为

我们可以肯定地假设，如果软件作者在测试期间设置了受控条件，而其软件在这些条件下记录了错误（而此类行为并非预期），那么作者会对此感兴趣。因此，我们将在测试运行时引入一种行为，如果在测试环境中观察到意外的 ERROR 日志，则会导致测试失败。

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

安全注意事项

• 使用严重级别为“FATAL”进行日志记录通常表示系统中存在核心不变性违规情况，继续操作可能会导致数据损坏或安全漏洞。在这种情况下，终止是最安全的做法。

• 组件框架可以安全地将日志的来源识别到组件级别。在组件中，模块可能会自行进行认证，因此可信度不如组件级别的标识。

隐私保护注意事项

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

文档

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

缺点、替代方案和未知情况

上述建议的更改会建立一套激励和惩罚机制，以鼓励用户通过特定方式登录。目的是从日志中获取更多价值 - 通过为重要日志条目设置适当高的严重级别来注意到它们，同时减少严重级别过高的不太重要的日志条目数量。

我们考虑了这些激励措施可能会促成不良行为（例如完全避免出现 ERROR 日志条目，即使在需要出现 ERROR 日志条目的情况下也是如此）的风险。我们认为，开发者会为了打造更好的软件而努力，并会在应对建议的更改时做出负责任的决策。

我们将通过分析 bug 报告和不定期与团队成员进行访谈来监控开发者行为，以验证上述假设，并根据需要调整方向。

在先技术和参考文档

Google Testing Blog 提供了一些关于日志记录级别的基本准则。