| RFC-0003：Fuchsia 日志记录准则 | |
|---|---|
| 状态 | 已接受 |
| 领域 |
|
| 说明 | 使用日志严重级别的最佳做法。日志严重性在测试和现场指标中的应用。 |
| Gerrit 更改 | |
| 作者 | |
| 审核人 |
|
| 提交日期（年-月-日） | 2020-06-03 |
| 审核日期（年-月-日） | 2020 年 6 月 11 日 |
总结
日志记录在整个 Fuchsia 的代码中被广泛使用，但记录的消息严重性不一致。这会降低日志信息的价值。下面，我们提议了不同日志严重级别的语义含义，以及在各种环境中特定严重级别日志记录的影响。
动机和问题陈述
日志是发送有关正在运行的软件内部状态变化的诊断信号的最常用方式。它们提供有价值的信息，可用于检测和纠正软件和产品中的故障。
过去，日志包含自由文本消息以及枚举的严重级别值。严重级别值指示消息的重要性，以将信号与噪声区分开来。但是，在整个 Fuchsia 代码及其依赖项中，严重级别的应用不一致，导致日志在手动问题排查和自动分析中难以使用。
通过提供有关如何使用日志严重性的常见准则，以及创建将结果附加到某些日志使用方式的流程，我们希望建立一个良性循环，从日志中获得更多诊断值，同时提高信噪比。例如，我们希望 ERROR 日志条目的频率成为系统稳定性的指标之一。
实现
日志严重级别
Fuchsia 支持多种标准日志严重级别：
严重
这表示发生了不可恢复的错误，组件在记录消息后不久就会自行终止。这通常表明违反了系统中的核心不变性，如果继续继续操作，可能会导致数据损坏或安全漏洞。
请谨慎使用此日志级别。此日志级别可能表明存在需要修复的硬件问题或软件 bug。由于给定的消息是组件自行终止之前记录的最后一条消息，因此其内容应指明终止的原因。
ERROR
此日志级别表示发生了意外事件，程序可以从中恢复。如果日志中出现 ERROR 日志条目，则表明有需要修复的不正确程序行为。开发者应努力使 bug 跟踪器中的 bug 与 ERROR 日志条目保持一对一的对应关系。换句话说，每个唯一的 bug 都应该有一个 ERROR 日志条目，而每个 ERROR 日志条目应该有一个单独的 bug。开发者应尽可能尝试在代码中维护这种对应关系。请注意，bug 可能不在发出日志语句的代码中。错误可能出现在其中一个调用方或它的某个依赖项中。
此日志级别及更高级别将充当系统稳定性指标的信号。此外，此日志级别及更高级别通常也会出现在 bug 报告中。此日志消息将由引入该消息的团队以外的人员使用，因此应提供足够的上下文来指导读取器找出问题的根本原因。
警告
此日志级别表示在系统正常运行期间发生了意外事件。这些意外事件可能是环境因素，因此不受系统本身的控制。例如，网络连接中断可能会记录为 WARNING 或无效输入，导致程序无法继续运行。此日志级别可用于查找导致问题的根本原因（通常是 ERROR 日志条目）。此日志级别可用于突显某个不常见的代码路径是由上述意外事件导致的。
INFO
这通常是 bug 报告中存在的最低日志级别。这表示程序中发生了值得注意的状态变化。此日志级别将用于指示导致问题的上下文（通常是 ERROR 日志条目）。与更高的日志级别一样，这些日志将供其他团队用于诊断，因此上下文至关重要。
应使用组件检查报告持久状态。如果此类情况未发生变化，则不应记录。例如，检查数据可以包含标志“configs_found = false”，甚至是“config_count = 0”，而不是以固定的时间间隔记录“[INFO] no configs found”。
DEBUG
此日志级别通常用于工程环境，例如测试期间或在提交队列机器人中重现问题时。bug 报告中通常不会收集严重级别为“DEBUG”或更低级别的日志，因此应该不会期望在 bug 报告中收到 DEBUG 和更低的日志。此日志级别通常比 INFO 更详细，并且有助于各个团队更好地了解他们正在开发的系统的状态。
跟踪
此日志级别通常由各个团队使用，可能用于提交队列和持续集成。此日志级别通常用于表示多阶段流程中的某个阶段已完成。
日志记录的后果
我们制定了有关选择日志严重级别的准则后，我们提出了几种根据日志严重性自动处理日志的方法。
将日志记录为现场分析
我们选择将 ERROR 日志条目的存在视为需要修复的软件 bug。可以肯定地说，软件作者会有兴趣了解其软件会在本地环境之外记录错误。因此，我们将统计是否存在 ERROR 和 FATAL 日志条目（按来源组件实例细分），通过 Cobalt 进行报告，并将这些计数器作为现场稳定性指标进行跟踪。
如需查看设备上的日志记录统计信息概览，请使用以下命令：
cs --log-stats
组件统计信息 (cs) 提供了一种日志统计信息模式，可解析 Archivist 的检查树，以提供每个组件生成的日志的摘要视图。通过该视图，工程师可以了解其组件生成的日志类型，以及相对于其他组件生成各种日志的频率。
记录为被测（非预期）行为
可以放心地假定，软件作者会有兴趣了解，他们的软件会在测试期间设置的受控条件下记录错误（如果不希望出现此类行为）。因此，我们将在测试运行时中引入一种行为，如果在测试领域中观察到意外的 ERROR 日志，该行为会导致测试失败。
上述测试运行时行为已实现、测试和记录。
安全注意事项
严重级别为“严重”的日志记录通常表示违反了系统中的核心不可变性，如果继续继续，可能会导致数据损坏或安全漏洞。在这种情况下，终止是最安全的做法。
组件框架可以安全地将日志来源识别到组件级别。在一个组件中，模块很可能经过自行测试，因此可信度不同于组件级标识。
隐私保护注意事项
任何日志记录分析都应避免泄露任何个人身份信息 (PII)。例如，我们不应在设备外指标中公开用户设备上的全套组件，也不应在可能包含任何个人身份信息 (PII) 的任何日志消息的全文中公开这些组件。
文档
我们还打算将这些日志记录指南作为 Fuchsia 开发指南发布。
缺点、替代方案和未知情况
上述提议的更改建立了一个激励机制和激励机制，以特定方式进行记录。目的是让日志发挥更大价值。请注意，为重要日志条目指定适当的高严重级别，同时减少严重级别过高的不太重要的日志条目的数量。
我们认为这些激励措施会导致不必要的行为，例如完全避免 ERROR 日志条目（即使在有此必要条件下）的风险。我们相信，开发更好软件的动机将推动开发者在如何应对提议的更改时做出负责任的决策。
我们将通过分析 bug 报告和不定期的团队成员访谈来监控开发者的行为，并根据需要更正课程，从而测试上述假设。
早期技术和参考资料
Google Testing 博客提供了一些有关日志记录级别的基本准则。