Fuchsia 元件檢查總覽

Fuchsia 中的元件可能會公開與 Inspect API 相符的結構化資訊。本文說明元件檢查的概念、介面、介面的 C++ 語言實作，以及用於與公開資訊的元件互動的面向使用者工具。

不確定該從何處開始嗎？

概念

元件可能會公開「節點」的樹狀結構，每個節點都有一組「屬性」。

圖：節點的樹狀結構

節點

節點是元件中匯出的實體，該元件可能有 0 以上的子項。每個節點都有名稱，而節點每個子項的名稱在子項之間的名稱不得重複。

圖：一個節點

資源

節點可以有任意數量的屬性。屬性具有字串鍵和值，可以是下列任一種類型：

數字類型

  • UintProperty：64 位元無正負號整數。
  • IntProperty - 64 位元帶正負號整數。
  • DoubleProperty：64 位元浮點值。
  • BoolProperty - 布林值。

字串類型

  • StringProperty - UTF-8 字串。
  • ByteVectorProperty - 位元組的向量。

陣列類型

  • UintArray、IntArray、DoubleArray - 對應數字類型的陣列。

直方圖類型

  • LinearUintHistogram，LinearIntHistogram，LinearDoubleHistogram

以固定大小值區儲存在陣列中的直方圖。

  • ExponentialUintHistogram，ExponentialIntHistogram，ExponentialDoubleHistogram

以指數形式儲存在陣列中的直方圖。

檢查檔案格式

檢查檔案格式是一種二進位格式，可在執行階段中有效率地插入、修改和刪除節點和屬性。讀者在不與寫入者溝通的情況下，為內容建立一致的快照。

檔案系統介面

在元件的傳出目錄中，頂層節點會以 VmoFiles 的形式顯示，結尾為副檔名 .inspect。元件是按照慣例，將主要或根樹狀結構公開為 out/diagnostics/root.inspect。

語言程式庫

C++

C++ 檢查程式庫針對檢查檔案格式提供完整的寫入和讀取支援。

寫入檢查資料的元件應避免讀取資料。讀取作業需要掃遍整個緩衝區，成本非常高。

Inspector 類別提供包裝函式，以便使用可加入一個根節點的新緩衝區建立新緩衝區。節點和屬性具有類型的包裝函式，可在其超出範圍時，自動刪除緩衝區中的基礎資料。

inspect_component 程式庫提供簡易的 ComponentInspector 單例模式介面，可協助您處理從元件公開單一階層的常見情況。

health 功能支援以健康狀態檢查工具已知的格式公開結構化健康資訊。

測試比對器程式庫提供 GMock 比對器，可驗證在測試中從檢查階層讀取的資料。

閱讀支援

讀取程式庫支援將檢查檔案剖析為階層。Hierarchys 包含 NodeValue 和 PropertyValues，分別是 Node 和 Property 的剖析版本。

Hierarchy 的 NodeValue 是由 node() 傳回，Hierarchy 則由 children() 傳迴向量中。GetByPath 函式支援依路徑讀取特定子項階層。

特定 NodeValue 的屬性可透過 properties() 存取子取得。您可以將對應的 PropertyValue 類型做為範本參數傳遞至 Contains<T>() 方法，藉此判斷屬性是否包含特定類型：

  // Returns true if the first property of the hierarchy's node is an INT value.
  if (hierarchy.node().properties()[0].Contains<IntPropertyValue>()) {
    // ...
  }

使用 Get<T>() 方法取得屬性：

  // Get the IntPropertyValue of the first property on the node.
  // Note: This causes a runtime exception if the property does not contain
  // the given type, crashing the program.
  hierarchy.node().properties()[0].Get<IntPropertyValue>();

此外，你也可以根據各種可能的格式類型切換：

  const auto& property = hierarchy.node().properties()[0];
  switch (property.format()) {
    case FormatType::INT:
      const auto& value = property.Get<IntPropertyValue>();
      /* ... */
      break;
    /* ... */
  }

陣列類型則可特別設定格式，包含直方圖。GetBuckets() 方法支援從 {Int,Uint,Double}ArrayValue 類型傳回直方圖值區的陣列。如果基礎陣列不是特殊格式的直方圖，則陣列將留空。

Rust

Rust Inspect 程式庫針對檢查檔案格式提供完整的寫入和讀取支援。

寫入檢查資料的元件應避免讀取資料。讀取作業需要掃遍整個緩衝區，成本非常高。

Inspector 類別提供包裝函式，以便使用可加入一個根節點的新緩衝區建立新緩衝區。節點和屬性具有類型的包裝函式，可在其超出範圍時，自動刪除緩衝區中的基礎資料。

元件模組支援簡單的 inspector 函式，用於處理從元件公開單一階層的常見用途。

health 模組支援以健康狀態檢查工具已知的格式公開結構化的健康資訊。

「測試」模組支援 assert_data_tree! 巨集，用於比對檢查資料以進行測試。

測試

驗證工具架構說明檢查語言程式庫的整合測試架構。

使用者空間工具

如要檢查元件的檢查階層，您可以使用 ffx inspect show 指令：

  • 列印所有檢查階層：

    ffx inspect show

  • 列印特定元件的檢查階層，例如 core/font_provider：

    ffx inspect show core/font_provider

或是執行 ffx target snapshot，產生含有系統診斷資訊的 ZIP 封存檔，其中包括檢查：

ffx target snapshot