RFC-0003：Fuchsia 日志记录指南

摘要

日志记录在整个历程中广泛使用 Fuchsia 的代码，但消息记录严重级别不一致。这个 会削弱日志中信息的价值。我们在下面提议了 不同日志严重级别的含义，以及对 特定严重程度的工作负载

动机和问题陈述

日志是发送有关 运行的软件的内部状态。它们能提供宝贵的信息 用于检测和纠正软件和产品中的故障。

过去，日志包含自由文本消息以及枚举的 严重程度值。严重程度值可表明 可以区分信号和噪声。不过， 严重级别在整个 Fuchsia 代码中都存在不一致， 依赖项，从而导致日志难以手动使用 问题排查和自动分析。

提供有关如何使用日志严重性的通用准则， 对使用日志的特定方式附加不良后果的流程，我们希望 创造一种可从日志中发掘更多诊断价值的良性循环 同时提高信噪比。例如，我们希望 ERROR 日志条目的频率作为系统稳定性的代理之一。

实现

日志严重级别

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

严重

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

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

ERROR

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

此日志级别及更高级别将作为系统稳定性指标的信号。 此外，此日志级别及更高级别的日志通常会显示在 bug 报告中。 此日志消息将由引入 因此应提供充足的上下文，以指导 找出问题的根本原因

警告

此日志级别表示在正常情况下， 系统运维套件。这些意外事件可能是 因此超出了系统本身的控制范围。例如，网络断开 连接可能会记录为 WARNING 或无效输入，从而阻止 系统可能会将其记录为 WARNING。此日志级别可用于 查找导致问题的根本原因（通常为 ERROR 日志条目）。这个 日志级别可能有助于突出一个不常见的代码路径被当作 上述意外事件可能导致的后果。

INFO

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

应通过以下方式报告持久状态： 组件检查。 如果这些条件未发生变化，则不应记录它们。例如： 而不是记录“[INFO] 找不到配置”定期检查 数据可能包含标志“configs_found = false”甚至“config_count = 0”。

DEBUG

该日志级别通常用于工程环境，例如在 或是在提交队列机器人中重现问题时进行微调。严重级别的日志 bug 报告中通常不会收集 DEBUG 级别及更低级别的报告，因此 应该不会在 bug 报告中收到 DEBUG 和数量较少的日志。这个 日志级别通常比 INFO 更详细，并且能够更好地帮助各个团队 了解所开发的系统的状态。

跟踪

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

日志记录的后果

在确定日志严重级别选择准则后，我们 几种方式，根据日志的严重程度自动处理日志。

将日志作为现场分析

我们选择将 ERROR 日志条目的存在视为 需要修复的软件错误可以肯定的是，软件开发者 想知道其软件是否在外部记录错误 本地环境因此，我们将计为 ERROR 和 FATAL 的存在 按来源组件实例细分的日志条目，通过 Cobalt 报告这些条目， 并将这些计数器作为现场稳定性指标进行跟踪。

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

cs --log-stats

组件统计信息 (cs) 提供日志统计信息模式，用于解析档案管理员的检查 提供每个组件生成的日志的摘要视图。此视图 可让工程师了解其组件生成的日志类型 生成各种日志（相对于其他组件）的频率。

记录为被测的（非预期）行为

可以肯定的是，软件开发者一定有兴趣了解 他们的软件在测试期间设置的受控条件下记录错误， 。因此，我们将行为引入到 如果发生意外的 ERROR 日志，会导致测试失败的测试运行时 在测试领域内观察到的数据。

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

安全注意事项

• 严重级别为 FATAL 的日志记录通常表示 进一步违反，继续可能导致数据损坏或 安全漏洞。在这种情况下，终止是最安全的行动方案。

• 组件框架可以安全地向组件识别日志来源 。在组件内，模块很可能会自行测试，因此无法 与组件级识别的可信度相同。

隐私保护注意事项

任何日志记录分析都应避免泄露任何个人身份信息 信息 (PII)。例如，我们不应公开全部的组件， 设备外指标或任何日志消息的全文内容 可能包含任何个人身份信息

文档

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

缺点、替代方案和未知问题

上述提议的更改建立了一个激励和制约机制， 以特定方式记录日志。其目的是从日志中获得更多价值，请注意 适当地为重要日志条目指定高严重级别 减少严重级别过高但不太重要的日志条目的数量。

我们考虑了这些激励措施可能促进不当行为的风险， 完全避免 ERROR 日志条目（即使在需要该日志条目的条件下）。 我们相信，开发更优秀的软件将会推动开发者 以负责任地决定如何应对建议的更改。

我们将通过分析来监控开发者的行为，以检验上述假设 提供错误报告、不定期与团队成员进行访谈， 。

先验技术和参考资料

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