Fuchsia 中的元件可能會公開與 Inspect API 相符的結構化資訊。本文說明元件檢查的概念、介面、介面的 C++ 語言實作,以及用於與公開資訊的元件互動的面向使用者工具。
快速連結
不確定該從何處開始嗎?
- 快速入門導覽課程:元件檢查的入門指南。
ffx inspect
- 用於檢查元件的ffx
指令。- 程式碼研究室 - C++ 和 Rust 中的完整程式碼研究室。
健康狀態檢查 - 說明健康狀態檢查子系統。
概念
元件可能會公開「節點」的樹狀結構,每個節點都有一組「屬性」。
節點
節點是元件中匯出的實體,該元件可能有 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 比對器,可驗證在測試中從檢查階層讀取的資料。
閱讀支援
讀取程式庫支援將檢查檔案剖析為階層。Hierarchy
s 包含 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 模組支援以健康狀態檢查工具已知的格式公開結構化的健康資訊。
測試
驗證工具架構說明檢查語言程式庫的整合測試架構。
使用者空間工具
如要檢查元件的檢查階層,您可以使用 ffx inspect show
指令:
列印所有檢查階層:
ffx inspect show
列印特定元件的檢查階層,例如
core/font_provider
:ffx inspect show core/font_provider
或是執行 ffx target snapshot
,產生含有系統診斷資訊的 ZIP 封存檔,其中包括檢查:
ffx target snapshot