檢查探索與託管

「檢查」是 Fuchsia 元件的強大診斷功能。

本文件詳細說明元件如何代管檢查資料，以及各種工具如何找到這些資料。

託管檢查資料

元件可能會以下列方式公開檢查資料：

• fuchsia.inspect.Tree (C++、Rust)
• VmoFile (飛鏢)
• fuchsia.inspect.deprecated.Inspect (Go)

元件無需連線至其他服務即可公開檢查資料。

元件通常不需考慮使用的方法，用戶端程式庫會抽出特定的託管機制。幾乎所有實作項目最終都會使用 Tree。

功能	fuchsia.inspect.Tree	VmoFile	fuchsia.inspect.deprecated.Inspect	說明
非延遲值	是	是	是	元件可能會記錄字串和整數等值。
延遲值	是	否	是	元件可能會在讀取時動態產生值。
可變動的樹狀結構	是	是	是	元件可能會修改儲存在輸出內容中的值。
檢討報告	是	是	否	元件記錄的值會在元件離開後使用。
低延遲快照	是	是	否	透過低延遲的做法，可以取得完整的資料數據匯報。
一致的快照	是*	是	否	樹狀結構的快照保證會在某個時間點呈現其狀態。

(*：每個樹狀結構的快照一致，但不保證能達成跨樹狀結構的一致性)

fuchsia.inspect.Tree

fuchsia.inspect.Tree 支援 Inspect API 的所有功能，建議您透過元件公開檢查資料。

元件會使用 fuchsia.inspect.InspectSink 通訊協定發布 fuchsia.inspect.Tree。

實作

fuchsia.inspect.Tree FIDL 檔案會定義由元件代管的通訊協定，以便公開其檢查資料。

Tree 通訊協定會在「樹狀結構」中連結多個「檢查 VMO」。

在上圖中，名為「root」的樹狀結構會針對 fuchsia.inspect.Tree 下代管的頂層服務處理通訊協定 fuchsia.inspect.Tree。子項樹狀結構可以透過通訊協定上的方法列舉並開啟子樹狀結構。舉例來說，在開啟及讀取之前，「子項 B」可能不存在於記憶體中。

通訊協定會以下列方式支援這項行為：

• GetContent

  這個方法會取得樹狀結構的內容，目前格式為「檢查 VMO」。按照慣例，在根樹狀結構上呼叫這個方法時，應傳回將持續以新資料更新的 VMO。用戶端不需要重新讀取樹狀結構的內容來讀取新的值。

• ListChildNames

  這個方法接受疊代器，該疊代器才能傳回樹狀結構的子項名稱。舉例來說，上圖中的樹狀結構在根樹狀結構上執行時會傳回「子項 A」和「子項 B」名稱。

• OpenChild

  這個方法會接受 fuchsia.inspect.Tree 的要求，要求繫結至指定名稱指定的樹狀結構。使用這個方法時，用戶端可以疊代在根疊代介面上公開的所有樹狀結構。

fuchsia.inspect.deprecated.Inspect

這個已淘汰的介面會由 Go 用來公開檢查資料。雖然 fuchsia.inspect.Tree 會提供「樹狀結構的樹狀結構」，但這個介面只會顯示可動態例項化子樹狀結構的單一樹狀結構。

這個介面已淘汰，並改用由檢查樹狀結構代管的 VMO 格式，原因如下：

• VMO 格式支援低延遲快照，不需要與託管程式通訊。
• 對於整個樹狀結構，VMO 格式快照一律保持一致。
• VMO 格式支援檢討報告，所有使用已淘汰介面的檢查資料都會因為元件而失效。
• Tree 通訊協定支援與已淘汰介面相同的動態功能。

讀取檢查資料

讀取「檢查」資料的主要方式主要是：

1. iquery
2. 建築師

iquery

iquery (檢查查詢) 是與檢查資料互動的 CLI。

iquery 的主要作業模式會取用用於檢查資料的選取器清單，然後輸出所含資訊。選取器包含三個部分，分別以 : 分隔：

1. 元件選取器：這是 v2 中的路徑名稱，或 v1 中的元件名稱加上元件名稱。
2. 節點路徑：檢查階層中節點的路徑。
3. 屬性路徑：屬性的名稱。

僅 iquery (1) 為必要欄位。如果只提供 (1)，例如 realm/component，iquery 會使用選取器 realm/component:* 擷取所有檢查資料。

iquery 包含兩個公用程式指令，以瞭解可用的元件以及可使用的選取器：

• list：iquery 會輸出所有可用的元件選取器，這是所有 v2 擴音器，以及所有具有元件名稱的 v1 領域路徑。
• selectors：iquery 會列印指定選擇器位置下的所有可用選取器。

這些模式可以一起使用，如下所示：

$ iquery show `iquery list | grep component_name`

另外，iquery 也允許列印特定位置的檢查資料。位置包含 .inspect 檔案路徑，或包含 fuchsia.inspect.Tree 的目錄路徑。iquery 包含公用程式指令，可列出包含檢查資料 (list-files) 的所有檔案。

iquery 的次要作業模式 (由 list-files 觸發) 會以遞迴方式識別來自指定目錄路徑的「檢查資料」位置。這兩種模式可以搭配使用，如下所示：

$ iquery list-files [component_moniker]
bootstrap/driver_manager
  class/display-coordinator/000.inspect
  ... additional output


$ iquery show --file 'class/display-coordinator/000.inspect'

在上述範例中，系統會執行 iquery list-files，以找出檢查位置清單。接著，系統會在其中一個輸出內容上執行 iquery，以遞迴方式列出相符位置的資料。你可以改寫：

$ fx iquery show --manifest component_name

阿基維斯特

由 Archivist 代管的 Fuchsia 診斷平台負責監控和匯總隨選檢查資料。

在元件管理員下執行時，可透過事件功能向封存區提供診斷資料。

架構由根領域提供事件。因此，它會發現整個系統的事件。允許查看及訂閱的事件如下：

• CapabilityRequested：當元件連線至 InspectSink 或 LogSink 時，會傳送至 Archivist，而非一般目錄連線。如此一來，Archivist 就知道連結到這些通訊協定的元件及其網址。

要公開 Inspect 的元件必須使用 fuchsia.inspect.InspectSink 通訊協定。這類程式碼通常如下所示：

{
    use: [
        {
            protocol: "fuchsia.inspect.InspectSink",
            from: "parent",
        },
    ],
}

其中提供實用的資訊清單，可簡化這個過程，而檢查程式庫必須提供這項功能：

{
    include: [
        "inspect/client.shard.cml",
    ]
}

從 Archivist 讀取檢查

Archivist 會託管 fuchsia.diagnostics.ArchiveAccessor，提供 StreamDiagnostics 方法，從執行中的元件取得檢查資料。