RFC-0003：Fuchsia 日志记录指南

摘要

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

动机和问题陈述

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

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

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

实现

日志严重级别

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

FATAL

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

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

ERROR

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

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

WARNING

此日志级别表示在系统的正常运行中发生了意外事件。这些意外事件可能是环境方面的，因此超出了系统本身的控制范围。例如，网络连接丢失可能会记录为 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 日志条目的存在视为需要修复的软件错误。可以安全地假设，软件作者会希望知道他们的软件正在其本地环境之外记录错误。因此，我们将按来源组件实例细分 ERROR 和 FATAL 日志条目的存在情况，通过 Cobalt 报告这些条目，并将这些计数器作为现场稳定性指标进行跟踪。

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

cs --log-stats

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

日志作为测试中的（意外）行为

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

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

安全注意事项

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

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

隐私注意事项

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

文档

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

缺点、替代方案和未知事项

上述拟议的更改创建了一个激励和惩罚系统，以特定方式进行日志记录。目的是从日志中获取更多价值 - 通过为重要日志条目提供适当的高严重级别来注意这些条目，同时减少严重级别过高的不太重要的日志条目的数量。

我们考虑了这些激励措施可能会促使出现不良行为的风险，例如完全避免 ERROR 日志条目（即使在需要的情况下也是如此）。 我们相信，创建更好的软件的动机将促使开发者在如何应对拟议的更改方面做出负责任的决定。

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

在先技术和参考文档

Google Testing Blog 提供了一些有关日志记录级别的基本指南。