RFC-0168：透過 InspectSink 公開檢查

RFC-0168：透過 InspectSink 公開檢查
狀態已接受
區域
  • 診斷資料
  • 元件架構
說明

定義元件公開檢查作業的機制。
問題
變更
作者
審查人員
提交日期 (年/月)2022-05-17
審查日期 (年/月)2022-06-15

編輯此 RFC

編輯 RFC 中繼資料

摘要

這個 RFC 引進了 fuchsia.diagnostics.InspectSink 通訊協定，允許元件公開檢查資料。因此，現在可以移除目前的機制 (DirectoryReady 事件)。

提振精神

現今的檢查是透過與一般元件架構能力轉送不一致的機制公開。現在，元件會在傳出命名空間中公開 diagnostics 目錄至架構。

為了在 SDK 中發布事件功能的目標，在 RFC-121 中已將 DirectoryReady 事件標示為已淘汰。然而，我們目前尚未得到一個良好的解決方案，說明如果這個目錄不存在，元件將如何公開檢查資料。此外， Fuchsia 上的 Flutter 要求我們移除對這些檔案系統抽象化機制的依賴，並簡化實作方式。重新思考元件公開檢查的方式，可以改善執行階段的複雜性，並造就開發人員作業效率提升的好處。

相關人員

講師：leannogasawara@google.com

審查者：

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

顧問：

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

社交化：這項 RFC 先前是以 Google 文件文件的形式，用於診斷、元件架構、Flutter 及其他。

設計

背景

過去，架構師曾透過 /hub 擷取檢查資料。其程式碼集的結構是中樞上的目錄監控器，會在 out/diagnostics 目錄出現時，開始追蹤元件的檢查資料 (以往名稱不同)。系統最終會在 Appmgr 和元件管理員中，透過事件移除及完成這項作業。此外，有時讀取檢查資料的測試是從 /hub 讀取而來。

架構師目前依賴 DirectoryReady 事件來達成以下兩個目標：

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

DirectoryReady 事件會同時處理這兩個資料點。不過，我們已有 (2) 的 CapabilityRequested，且作者認為我們可以透過一般通訊協定 (與 fuchsia.logger.LogSink 類似) 處理 (1) 問題，藉此帶來其他優勢。

解決歸因並非此 RFC 的目標，在這之後，移除目前用於 LogSink 和 DebugData 的 CapabilityRequested 事件。

檢查接收器

這個 RFC 引進 InspectSink 通訊協定，可讓 Archivist 從元件擷取檢查資料。這個通訊協定的定義如下：

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 (問題) 前，這些驅動程式會繼續公開 VMO。
  • 在檢查 Dart 程式庫支援 fuchsia.inspect.Tree 之前，其需要繼續公開 VMO。

和 fuchsia.logger.LogSink 一樣，這個通訊協定將由 Archivist 提供，並轉送至元件。

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

  1. 遵循標準元件通訊協定轉送：

    • 元件使用通訊協定 fuchsia.inspect.InspectSink，而不使用 expose /diagnostics to framework，這與目前的元件匯出記錄和追蹤記錄的方式類似。
    • Archivis 可透過 CapabilityRequested 接收與自身的連線，藉此保有歸因資訊。

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

    • 目錄由 fuchsia.io.Directory 支援，而大多數元件會等到啟動非同步迴圈時才會提供 out 目錄。使用這個通訊協定時，快照可能包含尚未啟動非同步迴圈，但已寫入檢查資料的元件檢查資料。

    • fuchsia.inspect.Tree 通訊協定也是如此。元件的檢查資料必須等到元件開始提供這個通訊協定後，才會在快照中提供 (在大多數情況下，必須等到元件啟動非同步迴圈時才會執行該通訊協定)。使用上方提議的通訊協定，我們可以立即為 Archivist 提供根 VMO (至少將這個 VM 加入快照) 以及 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 提供，凡是公開檢查位置的元件都會使用這個檔案。

本提案適用於第 2 版元件。為提高相容性，我們仍會針對 v1 元件處理 out/diagnostics。隨著持續改用第 2 版，作者並不認為值得花時間改變 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 的程式庫中測試單元。
  • 在提供 InspectSink 的 Archivist 中測試並整合了單元。
  • CTF 測試，偵測相容性變更。

說明文件

更新檢查探索和託管設定。

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

缺點、替代方案和未知

記錄和檢查的單一通訊協定

我們可以設定 agnosticSink，讓元件能在單一位置連結檢查和記錄。

  • 優點：用來轉送單一通訊協定 (而非 2 個)。
  • 缺點：如果基於某些原因，日後我們需要以不同方式處理記錄或檢查作業，那麼比起為兩者使用相同的通訊協定維護不同的通訊協定，這麼做可能會比較容易。

我們認為這個替代做法讓這個替代方法非常無吸引力，因為記錄檔和檢查作業有所不同，因此建議您單獨轉送這些項目。

先前的圖片和參考資料

無