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 工具，以便傳遞 fuchsia.logger.LogSink 和 呼叫 cmc 時，這些選項中的 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 可轉送至所有 多個 Deployment 元件此外，它也會將 void 的 Inspect/LogSink 新增至 Archivist。
• root：系統會開啟這個選項，確保我們將 LogSink 從阿奇維特 (Archivist) 轉送至所有 他們的同層由於 bootstrap 是顯示這項能力的廣告，因此我們將新增優惠 Inspect/LogSink (void 到 bootstrap)。

我們希望藉由這種方式，讓 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。

這項功能將在元件管理服務安全性政策中受到管制，確保只有 「Root Archivist」和內嵌於測試中的 Archivist。

優點：

• 每個元件都可以在樹狀結構中的任何位置使用 InspectSink 和 LogSink。
• 與目前世界狀態相符，每個元件都可以公開檢查。
• DX 提升了，因為開發人員不必費時找出元件未記錄的原因 ，以得知他們是否在測試中缺少優惠。
• 能以靜態方式檢查能力的點使用情形。
• 除非元件明確使用此能力，否則所有元件的命名空間中都以「沒有」開頭。
• 涵蓋透過 fuchsia.component.Realm/CreateChild 建立的動態元件。

缺點：

• 沒有明確的父項/子項，也就是說，這不符合安全性原則 分層分離的系統
• 如要取代或模擬拓撲中的 LogSink/InspectSink，必須調整環境 因此需要變更安全性政策
• 不吃我自己的 Dogfood 測試，第三方開發人員都無法將環境用於任意 為什麼我們要解釋這些價值？

具備 LogSink 和 InspectSink 架構的功能

允許使用這些通訊協定 from: framework。阿奇維斯可以 否則 Archivis 和元件管理服務 提供這些功能

優點：

• 與上述替代工具相同的優點，及診斷通訊協定的詳細步驟 (InspectSink 和 LogSink) 會成為架構通訊協定，即使元件管理服務未提供此通訊協定也一樣。
• 省去了能力歸因的需求，因為歸因會在 因為每個元件都有自己獨特的一組架構功能

缺點：

• 其圖示與先前的替代版本相同。
• 元件管理服務工具未直接提供的架構所使用的通訊協定第一個例項 。
• 不清楚如何在測試中提供獨立記錄，但並未建構額外的機制 測試管理員使用這組憑證
• 為裝置層級的所有元件建立單一記錄目的地。

讓 cmc 自動向所有兒童提供LogSink

cmc 不會使用旗標來要求使用者將 OfferDecl 新增至 CML，而不是使用標記， 因此系統會自動套用每個子集合和子集合。

優點：

• 明確提供父項/子項，有助於模擬，並取代 拓撲等
• CML 沒有任何變更。

缺點：

• CMC 中能力的特殊處理方式。
• .cml 中宣告的元件和透過 建構的元件的行為不一致 Realm/CreateChild。

在 cmc 中提供選項以及 CML 的語法糖選項，可讓這項工作更具彈性，並提供 其他機制也能運用，不僅限於診斷作業

不執行任何動作並照常轉送

請開發人員手動為所有孩子提供 LogSink 和 InspectSink。

優點：

• 明確提供父項/子項，有助於模擬，並取代 拓撲等
• 至於 API 邊界，仍是父項和子項之間的當地疑慮，並非涉及 API 邊界 也不必擔心

缺點：

• 當前問題：在執行測試偵錯時，很容易錯過 LogSink 導致時間遺失的問題。
• 其他問題：容易錯過將 InspectSink 轉送至特定元件 (因為今天) 也會導致實地缺少診斷資訊。跟先前一樣 LogSink 的問題，因此現在我們採用兩種通訊協定，而非只有一個通訊協定。

這些通訊協定的使用率很高，因此我們認為在 cmc 和 CML 有助於降低遺漏路線的可能性。

其他建議

討論了其他想法，例如使用能力套件轉送 diagnostics 軟體包 包含通訊協定，或是以網域或能力來源形式改良環境。 系統捨棄這些要求，並捨棄這些 評估轉送 API 的計畫

既有藝術品和參考資料

無