RFC-0171：改进了诊断路由

摘要

此提案旨在提供 cmc 和 CML 中的实用程序，以简化树中各处的诊断协议（fuchsia.logger.LogSink 和 fuchsia.diagnostics.InspectSink）的路由，并减少缺少日志或检查数据的 DX 痛点。虽然本文档侧重于检查和日志记录，但它也有助于提高大多数组件可能希望可用的其他协议（如 fuchsia.tracing.provider.Registry）的可用性。

设计初衷

使用日志的 DX 痛点在于，组件需要在各处路由 fuchsia.logger.LogSink：在生产组件、测试、RealmBuilder 路由等中。日志是我们期望几乎每个组件和测试都使用的 Fuchsia 体验的核心部分。

RFC-0168 建议使用协议 fuchsia.inspect.InspectSink，该协议 允许组件发布检查，从而带来一些改进并减少技术债务。与 fuchsia.logger.LogSink 一样，我们希望所有（或至少大多数）组件都使用检查插桩。如今，每个组件都可以 expose /diagnostics to framework，这允许每个组件公开检查并使其可供 Archivist 使用。通过转向协议，我们必须确保所有组件都能继续公开检查数据，这对于开发者调试其组件在运行时执行的操作非常有价值。

这是非人体工学且容易出错的，因为我们需要更新所有 CML，以手动将此协议路由到当前正在写入检查的所有组件。LogSink 也存在同样的问题，尤其是在测试中，很容易忘记将 LogSink 路由到被测组件，从而导致日志丢失并浪费开发者时间。

组件管理器利用组件的 LogSink 打印归因于该组件的路由错误。这改进了 DX，因为开发者可以快速发现路由错误。但是，如果 LogSink 未正确路由，这些错误最终会出现在归因于组件管理器的全局 syslog 中，并且开发者在查看自己的组件日志时更容易错过这些错误。

本文档尝试通过在 cmc 和 CML 中引入实用程序来简化将这两个协议路由到每个组件的过程，从而改善这种情况。

组件框架计划审核路由 API，并构思使模型更加一致且用户友好的方法。这将需要几个季度的时间，因此最好采用增量方法，使用现有基元并对其进行扩展。

利益相关方

教员： leannogasawara@google.com

审核人：

• crjohns@google.com
• geb@google.com
• hjfreyer@google.com
• shayba@google.com
• zarvox@google.com

咨询对象：

• bryanhenry@google.com
• cgonyeo@google.com
• jmatt@google.com
• thatguy@google.com

社交化： 此设计以 Google 文档的形式进行社交化，这是一个决策文档，其中详细讨论了列出的替代方案，以及利益相关方之间的会议和对话。

设计

为了让开发者在当前组件功能路由系统下更轻松地避免错过日志和检查，遵循最小权限原则和分层隔离，并能够继续公开检查，我们将开发以下内容：

• cmc 必需的提供项检查器。
• 能够在 CML 中向所有子项和集合提供功能。
• 用于诊断的新 CML 分片。
• RealmBuilder 会自动向所有组件提供诊断功能。

cmc 必需的提供项和用途

cmc 将获得一个命令行选项 --must-offer-protocol，其中包含一个协议名称列表，它将验证以下语句是否为真：

对于清单中声明的每个子项和集合，对于必需协议列表中定义的每个协议，都存在来自某个来源的 OfferDecl。

此外，cmc 将获得一个等效的命令行选项 --must-use-protocol，该选项将检查等效项，但适用于 UseDecl。

GN 和 Bazel 工具将更新，以便在调用 cmc 时，在这些选项中传递 fuchsia.logger.LogSink 和 fuchsia.diagnostics.InspectSink。

无论如何为清单调用 cmc，如果开发者希望完全停用此检查，都可以将以下内容添加到其 CML 文件中（这是 CML 中引入的新语法）：

{
    disable: {
        must_use_protocol: [ "fuchsia.logger.LogSink", "fuchsia.diagnostics.InspectSink" ],
        must_offer_protocol: [ "fuchsia.logger.LogSink", "fuchsia.diagnostics.InspectSink" ],
    }
}

如果开发者不希望将 LogSink 或 InspectSink 路由到其某些子项，可以自由选择以下任一方式：

• 使用可选功能路由：将协议from: "void"路由到他们想要关闭单个提供项的 子项/集合。
• 手动从他们所需的来源路由协议。

这些功能来源的 bootstrap 和 root 领域需要一些特殊处理：

• bootstrap：将启用此选项，以确保 LogSink 路由到 bootstrap 中的所有组件。此外，它还会添加从 void 到 Archivist 的提供项 Inspect/LogSink。
• root：将启用此选项，以确保我们将 LogSink 从 Archivist 路由到其所有同级项。由于 bootstrap 是公开此功能的组件，因此我们将添加从 void 到 bootstrap 的提供项 Inspect/LogSink。

通过这样做，我们希望 Fuchsia 上的每位开发者都不太可能错误地错过日志或检查数据。

zarvox@ 为本部分构建了一个原型（和关系链）。

允许在 CML 中向所有子项和集合提供功能

为了改进 路由到所有子项 的 DX，我们将在 CML 中引入语法糖，以允许将功能路由到“所有子项和集合”。

此语法糖可按如下方式使用：

offer: [
    {
        protocol: "fuchsia.logger.LogSink",
        from: "parent",
        to: "all",
    }
]

编译包含该语法的 CML 文件时，将生成 N 个 OfferDecl，其中 N 是组件拥有的集合和子项的总数。

目标为 all 的 OfferDecl 将在 cmc 中进行门控，以便仅用于上一部分中介绍的新可选参数中定义的协议。

CML 分片

将创建以下分片：

// syslog/use.shard.cml
{
    use: [
        { protocol: "fuchsia.logger.LogSink" },
    ],
}

// syslog/offer.shard.cml
offer: [
    {
        protocol: "fuchsia.logger.LogSink",
        from: "parent",
        to: "all"
    }
]

// inspect/use.shard.cml
{
    use: [
        { protocol: "fuchsia.diagnostics.InspectSink" },
    ],
}

// inspect/offer.shard.cml
offer: [
    {
        protocol: "fuchsia.diagnostics.InspectSink",
        from: "parent",
        to: "all"
    }
]

将更新以下现有分片：

• syslog/client.shard.cml：包括 syslog/use.shard.cml 和 syslog/offer.shard.cml。
• inspect/client.shard.cml：包括 inspect/use.shard.cml 和 inspect/offer.shard.cml。

仅执行路由而不执行任何程序的逻辑组件可以使用 offer.shard.cml。需要使用这些协议但需要配置要路由到其子项的内容的组件可以使用 use.shard.cml。其余组件可以使用标准且方便的 client.shard.cml。

如果组件没有子项或集合，但仍使用 client.shard.cml（因为它使用的是协议），则分片中的 offer to all 语句将不起作用，因为它只是语法糖，如前所述，它只会扩展到 OfferDecl。

为方便起见，我们将提供一个 diagnostics/client.shard.cml，其中包含两个 client.shard.cml 文件。

RealmBuilder 更新以支持 offer to all

为了方便将诊断协议路由到所有被测组件，RealmBuilder 将收到一些更新，以允许将协议路由到所有子项和集合：

• 自动向所有子项和集合提供 LogSink 和 InspectSink。在 Rust 中，它可能如下所示：

  builder
      .add_route(
          Route::new()
              .capability(Capability::protocol_by_name("fuchsia.diagnostics.InspectSink"))
              .from(Ref::parent())
              .to(Ref::all()),
      )
      .await?;
  

• 由于我们预计所有测试都希望这样做，除非在一些小众场景中，否则 RealmBuilder 会自动将这些协议路由到所有组件。这可能看起来与 cmc 和 CML 中采用的方法不一致，但 RealmBuilder API 在某些方面已经偏离，以提供更方便的工作流，更好地适应测试。鉴于我们预计 99% 的时间我们会将这些协议路由到测试组件，因此我们将教 RealmBuilder 自动执行此操作，并提供一种关闭它的方法：

  let builder = RealmBuilder::new().await?;
  …
  let instance = builder
      .route_logs_to_all(false)     // defaults to true
      .route_inspect_to_all(false)
      .build()
      .await;
  

实现

1. 更新 cmc 以支持 CML 中的新标志和 offer to all。
2. 添加包含 offer LogSink to all 的 syslog/offer.shard.cml。
3. 更新树中的 cmc 用法以使用新标志，并更新可能缺少路由的现有 CML。GN 和 Bazel SDK 将更新，但在 OOT CML 迁移为具有完整提供项集之前，必需协议集将默认为 []。
4. 更新树外的 cmc 用法以使用新标志，并更新可能缺少路由的现有 CML（利用提供项分片）。
5. 更新 GN 和 Bazel SDK 以要求诊断协议。
6. 从 syslog/client.shard.cml 中包含 syslog/offer.shard.cml。
7. 推出后，重构使用提供项分片但不再需要的 OOT 清单，因为它是通过客户端分片包含的。

性能

cmc 将执行一些额外的工作，但预计不会对编译时间产生任何重大影响。

安全注意事项

此更改符合组件框架安全属性，特别是最小权限原则和分层隔离原则。

隐私注意事项

无隐私影响。

测试

将对新的 cmc 功能进行单元测试。

文档

将更新 cmc 以包含新选项，并将更新 CML 以 描述新的 offer to all 功能。

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

在 Environment 中使用 debug_capabilities

这是考虑的主要替代方案。在此替代方案下，我们将扩展 fuchsia.sys2.Environment，使其具有 diagnostics_capabilities，就像 debug_capabilities 一样，或者将 debug_capabilities 转换为 diagnostics_capabilities，或者仅将 debug_capabilities 用于诊断协议，使其可供树中任何组件使用 from: diagnostics 或 from: debug。

此功能将在组件管理器安全政策中进行门控，以确保它仅由根 Archivist 和嵌入在测试中的 Archivist 使用。

优点：

• 每个组件都可以从树中的任何位置使用 InspectSink 和 LogSink。
• 与当前世界状态一致，每个组件都可以公开检查。
• 改进了 DX，因为开发者无需花费时间弄清楚为什么他们的组件没有记录日志，从而发现他们在测试中缺少产品。
• 可以静态检查功能的点对点使用情况。
• 除非明确使用该功能，否则所有组件在其命名空间中都以“无”开头。
• 涵盖通过 fuchsia.component.Realm/CreateChild 创建的动态组件。

缺点：

• 不再有明确的父子提供项，这意味着，这与分层隔离的安全原则不一致。
• 替换或模拟拓扑中的 LogSink/InspectSink 需要调整环境，这需要更改安全政策。
• 我们没有使用自己的产品 - 第三方开发者无法将环境用于其协议的任意用途，为什么我们能？

将 LogSink 和 InspectSink 设为框架功能

允许这些协议从 from: framework 使用。Archivist 可以将这些功能公开给框架，也可以在 Archivist 和组件管理器之间签订合同来提供这些功能。

优点：

• 与上一个替代方案中的优点相同，但诊断协议（InspectSink 和 LogSink）即使不是由组件管理器提供，也会成为框架协议。
• 无需进行功能归因，因为归因将直接在框架中进行，因为每个组件都有自己唯一的一组框架功能。

缺点：

• 与上一个替代方案中的缺点相同。
• 从框架使用的协议的第一个实例，该协议不是由组件管理器直接提供的：本身。
• 不清楚如何在测试中提供隔离日志，而无需构建供测试管理器使用的额外机制。
• 为所有组件（设备范围内）建立单个日志目标。

让 cmc 自动向所有子项提供 LogSink

cmc 不会使用要求用户向其 CML 添加 OfferDecl 的标志，而是会自动为每个子项和集合执行此操作。

优点：

• 明确的父子提供项，有助于模拟、替换拓扑中的协议等。
• CML 中没有变化。

缺点：

• CMC 中功能的特殊处理。
• 在 .cml 中声明的组件和通过 Realm/CreateChild 构建的组件的行为不一致。

在 cmc 中提供选项并在 CML 中提供语法糖，使其更灵活，并提供一种机制，其他人可以利用该机制，不仅用于诊断。

不执行任何操作，照常路由

让开发者手动向其所有子项提供 LogSink 和 InspectSink。

优点：

• 明确的父子提供项，有助于模拟、替换拓扑中的协议等。
• API 边界仍然是父项和子项之间的本地问题，而不是涉及其他方的问题。

缺点：

• 当前问题：很容易错过路由 LogSink，从而导致调试测试时浪费时间。
• 其他问题：很容易错过将 InspectSink 路由到某些组件（鉴于如今每个人都可以公开它），从而导致在现场缺少诊断。这与 LogSink 的问题相同，因此现在我们在两个协议中都有这个问题，而不是只有一个。

鉴于这些协议的使用范围如此广泛，我们认为在 cmc 和 CML 中添加其他选项有助于降低错过路由的可能性。

其他想法

我们还讨论了其他想法，例如使用 capability bundle 来路由包含这两个 protocol 的 diagnostics bundle，或者以 domain 或 capability source 的形式改进环境。鉴于计划审核路由 API，这些想法被弃用，取而代之的是使用现有机制和 API 的近期解决方案。

在先技术和参考文档

不适用