RFC-0168：通过 InspectSink 公开检查

摘要

此 RFC 引入了 fuchsia.diagnostics.InspectSink 协议，以允许组件 来公开检查数据因此，当前机制（DirectoryReady 事件）现在可以 删除。

设计初衷

检查目前通过与常规组件框架不符的机制公开 功能路由。目前，组件在其传出命名空间中公开了 diagnostics 目录 框架。

作为发布事件的目标的一部分，DirectoryReady 事件在 RFC-121 中被标记为已弃用 功能。不过，我们还没有一个好的解决方案来说明组件是如何 用于公开检查数据。另外，Fucsia 上的 Flutter 希望摆脱对这些文件系统抽象的依赖，并简化它们的实现。 重新思考组件如何公开 Inspect 将有助于他们移除大量 提高运行时复杂性，并为开发者的工效学设计带来优势。

利益相关方

教员：leannogasawara@google.com

审核者：

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

已咨询：

• dworsham@google.com
• surajmalhotra@google.com
• zarvox@google.com

社交化：此 RFC 之前以 Google 文档文档的形式被社会 Diagnostics、Component Framework、Flutter 等。

设计

背景

不久前，归档管理员曾通过 /hub 注入 Inspect 数据。它的代码库是 作为 hub 上的目录观察者，可以开始跟踪 立即检查组件数据 出现了 out/diagnostics 目录（当时的名称有所不同）。这个 最终被移除，并通过事件（在 appmgr 和组件管理器中）完成。 此外，目前，读取 Inspect 数据的测试是通过直接从 /hub 读取来完成此操作。

归档管理员目前依赖 DirectoryReady 事件做两件事：

• 从组件（组件 expose /diagnostics to framework）提取检查数据。
• 将检查数据归因于源组件。

DirectoryReady 事件同时解决了这两个问题。不过，我们已经有 问题 (2) 问题为 CapabilityRequested，作者认为我们可以用常规方法解决 (1) 问题 协议（类似于 fuchsia.logger.LogSink）可带来更多优势。

解决归因不是此 RFC 的目标。这就是以后要移除 CapabilityRequested 事件，目前用于 LogSink 和 DebugData。

InspectSink

此 RFC 引入了 InspectSink 协议，允许归档管理员提取检查数据 。此协议的定义如下：

library fuchsia.diagnostics;

using zx;

@discoverable
protocol InspectSink {
    /// Publishes a handle to the `fuchsia.inspect.Tree` protocol that the server can use to read
    /// Inspect data, including lazy nodes.
    Publish(struct {
        tree fuchsia.inspect.Tree;
        root zx.handle:<VMO, zx.rights.BASIC | zx.rights.READ | zx.rights.MAP, optional>;
    });

    /// Publishes a read handle to the inspect VMO  that the component asynchronously updates.
    /// The server can read Inspect using the Inspect reader algorithm [1]. A component using this
    /// method to publish Inspect won't be able to expose lazy nodes.
    ///
    /// [1]: /docs/reference/platform-spec/diagnostics/inspect-vmo-format.md#reader_algorithm
    PublishVmo(struct {
        name string;
        root zx.handle:<VMO, zx.rights.BASIC | zx.rights.READ | zx.rights.MAP>;
    });
}

主要方法是 Publish，大多数组件都会使用它，因为 fuchsia.inspect.Tree 是 标准方法公开 Inspect。不过，我们提供了一种机制 只是一个检查 VMO。这样做有几个原因：

• 组件不一定要是服务器（没有理由运行异步循环，只是消耗 功能，而不提供任何内容）（如果不需要，但仍应能够 公开 Inspect。
• 在驱动程序改用 fuchsia.inspect.Tree（问题）之前，他们将 继续公开 VMO
• 在 Inspect Dart 库支持 fuchsia.inspect.Tree 之前，它需要继续公开 VMO。

与 fuchsia.logger.LogSink 一样，此协议将由归档管理员处理并转送 组件

与提供 out/diagnostics 目录相比，此协议具有多项优势：

1. 与标准组件协议路由保持一致：

   • 组件仅使用 fuchsia.inspect.InspectSink 协议，而不是 expose /diagnostics to framework，类似于组件目前导出日志和跟踪记录的方式。
   • 归档管理员可以通过 CapabilityRequested 接收与它的连接，并保持 归因。

2. 可以在启动组件异步循环之前提供检查数据。

   • 目录由 fuchsia.io.Directory 提供支持，大多数组件不会为其提供 out 目录中，直到开始异步循环。通过使用此协议，快照可以包含 检查尚未启动异步循环但已编写了 检查数据。

   • 这同样适用于 fuchsia.inspect.Tree 协议。组件的检查数据 快照中可用，直到组件开始提供此协议， 大多数情况下，直到组件开始其异步循环为止。通过使用上面提议的协议，我们 可以立即为归档管理员提供根 VMO（至少这一个 快照中）和 fuchsia.inspect.Tree 的句柄，以用于将来的请求。

3. 运行程序和文件系统实现不再出现问题。

   • 目前，我们在 appmgr 和组件管理器中已有代码， 组件未按时提供 out/diagnostics，Flutter runner 就是如此。 该运行程序先提供 out/ 目录，然后再填充该目录。理想情况下，我们只需使用 目录观察器，但并非所有 VFS 实现都实现了观察器（特别是我们的 VFS 实现（通过 Flutter 使用的 C++ SDK 实现），并且不能依赖未来的运行程序 使用完整的 fuchsia.io.Directory 实现。

这项更改可在后台完成，方法是将 inspect/client.shard.cml 更改为使用 而不是向框架公开诊断目录。文件 inspect/client.shard.cml 通过 SDK 提供，并用于公开 在任何位置检查。

此方案适用于 v2 组件。我们仍会处理 v1 的 out/diagnostics 用于确保兼容性的组件随着向 v2 的持续迁移，作者 认为花时间改变 v1 的运作方式是值得的。我们的目标是 因此迁移到 v2 的组件不需要更改检查方式的代码。

实现

系统会遵循标准的 LSC 流程。

具体步骤如下：

1. 在 Archivist 中实现新协议 InspectSink。
2. 使用 inspect/client.shard.cml 和路由 fuchsia.inspect.InspectSink 识别组件 给他们发来了一封信。现在，这就涉及到必须完整枚举所有 然而，我们有一个已社会化、 我们将在后续的 RFC 中介绍。
3. 更改 inspect/client.shard.cml 以将此协议与公开 /diagnostics 结合使用 目录移到框架中，从而实现软转换。
4. 支持连接到 InspectSink，而不是在检查中公开 diagnostics 目录 库。
5. 在组件管理器中移除 DirectoryReady 的实现，并将其从 所有组件和所有预构建组件都完成转换后的 fuchsia.sys2.Event 定义 已刷新届时，我们将依赖于 CTF 测试以及必须了解的支持期限 方法。

性能

性能应该会有积极的提升，因为我们不再需要遍历目录或 创建 DirectoryReady 事件，我们只需使用一个协议。

安全注意事项

此更改与组件框架安全属性保持一致，特别是 最小权限和分层隔离原则

隐私注意事项

隐私权方面没有任何变化。我们会继续对检查数据进行常规隐私保护 流水线。

测试

将通过以下方式测试此 RFC 的实现：

• 在连接到 InspectSink 的库中进行了单元测试。
• 在为 InspectSink 提供服务的 Archivist 中进行了单元测试和集成测试。
• CTF 测试，用于检测兼容性变化。

文档

“检查发现和托管”将更新。

我们的目标是从后台在编写 Inspector 的库中进行此项更改。但是，如果我们 当组件迁移到 v2 后，需要对代码进行更改，我们会在 请参阅迁移指南的“诊断”部分中

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

使用一个协议同时用于日志和检查

我们可以创建一个 DiagnosticsSink，让各组件在单个 位置。

• 优点：路由使用单个协议，而不是 2 个。
• 缺点：如果将来由于某种原因，我们需要以不同方式处理日志或进行检查，可能 与针对两种服务采用相同的协议相比，如果分别维护单独的协议， 。

我们认为，由于日志和检查的结果不同，因此该选择完全没有吸引力。 因此，最好分别进行路由

先验技术和参考资料

不适用