RFC-0168：透過 InspectSink 公開檢查

摘要

這份 RFC 會介紹 fuchsia.diagnostics.InspectSink 通訊協定，讓元件可公開檢查資料。因此，您現在可以移除目前的機制 (DirectoryReady 事件)。

提振精神

目前，檢查功能是透過與一般元件架構能力轉送不相符的機制公開。目前，元件會將 diagnostics 目錄公開至框架的傳出命名空間。

DirectoryReady 事件已在 RFC-121 中標示為已淘汰，這是在 SDK 中發布事件功能的目標之一。不過，如果這個目錄不存在，我們目前還沒有適當的解決方案，讓元件能夠公開檢查資料。此外，Flutter on Fuchsia 希望移除對這些檔案系統抽象化的依賴，並簡化實作方式。重新思考元件如何公開檢查功能，可讓元件移除大量的執行階段複雜度，並為開發人員提供人體工學優勢。

相關人員

講師：leannogasawara@google.com

審查者：

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

諮詢：

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

傳播：這份 RFC 先前以 Google 文件文件形式，在 Diagnostics、元件架構、Flutter 和其他項目之間傳播。

設計

背景

早些時候，Archivist 曾透過 /hub 擷取檢查資料。其程式碼庫已在 Hub 中以目錄監視器的形式進行結構化，可在 out/diagnostics 目錄出現時開始追蹤元件的檢查資料 (當時的名稱不同)。這項功能最終已移除，並透過事件 (在 appmgr 和元件管理員中) 執行。此外，當時讀取檢查資料的測試會直接從 /hub 讀取。

Archivist 目前會使用 DirectoryReady 事件做兩件事：

• 從元件 (元件 expose /diagnostics to framework) 擷取檢查資料。
• 將檢查資料歸因於來源元件。

DirectoryReady 事件可解決這兩個問題。不過，我們已針對 (2) 提供 CapabilityRequested，作者認為我們可以透過一般通訊協定 (類似 fuchsia.logger.LogSink) 解決 (1)，帶來額外優勢。

解決歸因問題並非本 RFC 的目標。我們會在日後移除目前用於 LogSink 和 DebugData 的 CapabilityRequested 事件。

InspectSink

這份 RFC 會介紹 InspectSink 通訊協定，讓 Archivist 從元件擷取 Inspect 資料。此通訊協定定義如下：

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，因為這是公開檢查的標準方式。不過，我們提供一種機制，可讓元件只發布檢查 VMO。這項做法有以下幾個原因：

• 元件不必是伺服器 (沒有理由執行非同步迴圈，只需使用功能，不需提供任何內容)，但仍應能公開檢查功能。
• 在驅動程式遷移至 fuchsia.inspect.Tree (問題) 之前，仍會繼續公開 VMOs。
• 在 Inspect Dart 程式庫支援 fuchsia.inspect.Tree 之前，它需要繼續公開 VMOs。

就像 fuchsia.logger.LogSink 一樣，這個通訊協定會由 Archivist 提供，並且會路由至元件。

與提供 out/diagnostics 目錄相比，這個通訊協定有幾項優點：

1. 符合標準元件通訊協定轉送：

   • 元件只會使用 fuchsia.inspect.InspectSink 通訊協定，而不會執行 expose /diagnostics to framework，這與元件目前匯出記錄和追蹤記錄的方式類似。
   • 透過 CapabilityRequested 接收與之相關聯的資料，以便保留歸屬資訊。

2. 您可以在啟動元件非同步迴圈前，先提供檢查資料。

   • 目錄由 fuchsia.io.Directory 提供支援，且大多數元件在啟動非同步迴圈之前，不會提供 out 目錄。透過使用這個通訊協定，快照可以包含尚未啟動非同步迴圈，但已寫入檢查資料的元件檢查資料。

   • fuchsia.inspect.Tree 通訊協定也適用於這項規則。在快照中，只有在元件開始提供此通訊協定時，才會顯示元件的檢查資料，而大多數情況下，元件都必須先啟動非同步迴圈，才會開始提供這類通訊協定。透過上述建議的通訊協定，我們可以立即為 Archivist 提供根 VMO (至少這個會包含在快照中)，以及 fuchsia.inspect.Tree 的句柄，以便日後提出要求。

3. 不再發生執行工具和檔案系統實作問題。

   • 我們目前在 appmgr 和元件管理工具中加入程式碼，以便在元件未按時提供 out/diagnostics 的特殊情況下執行，這正是 Flutter 執行元件的情況。該執行元件會先提供 out/ 目錄，然後填入該目錄。理想情況下，我們只會使用目錄監控器，但並非所有 VFS 實作項目都已實作監控器 (特別是 Flutter 使用的 C++ SDK 中的 VFS 實作項目)，我們無法依賴日後的執行工具使用完整的 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 從 Archivist 路由至這些元件。這會導致以下問題：必須在 cml 定義中完整列舉所有這類元件。不過，我們已經提供解決方案，並會在後續 RFC 中說明。
3. 變更 inspect/client.shard.cml 以使用此通訊協定，並將 /diagnostics 目錄公開給架構，以便進行軟性轉換。
4. 支援連線至 InspectSink，而非在檢查程式庫中公開 diagnostics 目錄。
5. 移除元件管理工具中的 DirectoryReady 實作，並在所有元件完成轉換，且所有預先建構項目都已重新整理後，從 fuchsia.sys2.Event 定義中移除該實作。我們會依據 CTF 測試和支援時程，決定何時可完成這項作業。

成效

我們不再需要逐一檢查目錄或建立 DirectoryReady 事件，而是只依賴單一通訊協定，因此效能應會有所提升。

安全性考量

這項變更符合元件架構安全性屬性，特別是最低權限原則和階層隔離原則。

隱私權注意事項

隱私權方面沒有任何變動。檢查資料會繼續透過一般隱私權管道。

測試

我們會以以下方式測試這項 RFC 的實作方式：

• 在連結至 InspectSink 的程式庫中測試的單元。
• 在 Archivist 中進行單元測試和整合測試，以便為 InspectSink 提供服務。
• CTF 測試可偵測相容性變更。

說明文件

檢查探索和代管功能會更新。

目標是在寫入檢查的程式庫中，在幕後進行這項變更。不過，如果元件遷移至 v2 時需要變更程式碼，我們會在遷移指南的診斷部分反映這些變更。

缺點、替代方案和未知事項

單一通訊協定可用於記錄和檢查

我們可以使用 DiagnosticsSink，讓元件在同一個位置連結檢查和記錄。

• 優點：只需單一通訊協定即可轉送，而非 2 個。
• 缺點：如果我們需要在日後以不同方式處理記錄或檢查，與其為這兩者設立相同的通訊協定，不如維持個別的通訊協定，這樣可能會比較容易處理。

我們認為，由於記錄和檢查是不同的項目，因此這個做法不太吸引人，因此建議您將這兩者分開處理。

既有技術與參考資料

無