本頁面由 Cloud Translation API 翻譯而成。

Fuchsia 元件檢查總覽

Fuchsia 中的元件可能會公開自身的結構化資訊，且符合 Inspect API。本文件將說明元件檢查、介面、介面的 C++ 語言實作方式，以及與公開資訊元件的元件互動的使用者端工具。

快速連結

不知道該從何處著手嗎？

快速入門：元件檢查的快速入門指南。
ffx inspect：用於檢查元件的 ffx 指令。
Codelab：完整的 C++ 和 Rust 程式碼研究室。
C++ 和 Rust 的 API 參考資料。
健康狀態檢查：說明健康狀態檢查子系統。

概念

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

圖：節點樹狀結構

節點

節點是元件中已匯出的實體，可能會有 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 比對器，用於驗證在測試中從 Inspect 階層讀取的資料。

閱讀輔助

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

node() 會傳回 Hierarchy 的 NodeValue，而 children() 會以向量傳回子 Hierarchy。GetByPath 函式支援依路徑讀取特定子項階層。

您可以透過 properties() 存取子存取特定 NodeValue 的屬性。您可以將對應的 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 檢查程式庫提供完整的寫入和讀取檢查檔案格式支援。

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

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

health 模組可讓您以健康檢查工具支援的格式，公開結構化健康資訊。

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

測試

「驗證器架構」一文說明瞭 Inspect 語言程式庫的整合測試架構。

使用者空間工具

ffx inspect

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

列印所有檢查階層：
```
ffx inspect show
```
列印特定元件 (例如 core/font_provider) 的檢查階層：
```
ffx inspect show core/font_provider
```

ffx inspect show 也會對輸入內容進行模糊比對。例如：

ffx inspect show archivist.cm

只要 bootstrap/archivist 是系統中網址結尾為 archivist.cm 的唯一公開檢查工具元件，就會列印 bootstrap/archivist 的所有檢查工具。

如果輸入內容無法明確指出個別元件，模糊比對功能就會失敗；在這種情況下，工具會列印與查詢相符的別名清單。

一般來說，這個指令接受以下項目：

元件路徑名稱，例如 core/network/netstack。如果只傳遞路徑名稱，則不需要轉義集合標記，但可視需要進行轉義。
模糊搜尋參數，對應至網址片段、資訊清單片段或路徑名稱片段。也就是說，bootstrap/archivist 的 ffx inspect show archivist.cm 會搭配資訊清單 archivist.cm。
元件選取器，例如 core/network/*。
完整的診斷選取器，例如 core/network/netstack:root/path/to/*:property。在完整選取器的情況下，必須執行轉義才能建立有效的選取器。

假設您有 bootstrap/driver-hosts:driver-host-337 元件。在需要特定屬性的情況下，以下是避免盡可能避免轉義的符合人體工學方法：

ffx inspect driver-host-337 --data root/stats:my_stat

ffx 目標快照

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

ffx target snapshot