檢查探索與託管

Inspect 是 Fuchsia 元件的強大診斷功能。

本文將詳細說明元件如何託管檢查資料，以及各種工具如何探索這些資料。

託管檢查資料

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

• fuchsia.inspect.Tree (C++、Rust)
• VmoFile (Dart)

元件不需要與其他服務通訊，即可公開檢查資料。

元件通常不需要擔心使用哪種方法，用戶端程式庫會抽象化託管的特定機制。幾乎所有導入作業最終都會使用 Tree。

(*：每個樹狀結構的快照都一致，但不保證樹狀結構之間的一致性)

fuchsia.inspect.Tree

fuchsia.inspect.Tree 支援 Inspect API 的所有功能，建議您使用這個方法，從元件公開 Inspect 資料。

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

實作

fuchsia.inspect.Tree FIDL 檔案定義了元件託管的通訊協定，用於公開其 Inspect 資料。

Tree 通訊協定會將多個檢查 VMO 連結在一起，形成「樹狀結構的樹狀結構」。

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

通訊協定支援這項行為的方式如下：

• GetContent

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

• ListChildNames

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

• OpenChild

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

讀取檢查資料

解讀「檢查」資料的主要方式有兩種：

1. iquery
2. 檔案管理員

iquery

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

iquery 的主要作業模式會擷取檢查資料的選取器清單，並列印內含的資訊。選取器由三個部分組成，並以 : 分隔：

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

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

iquery 包含兩個公用程式指令，可瞭解有哪些可用元件和選取器：

• list：iquery 會列印所有可用的元件選取器，也就是所有第 2 版路徑名稱，以及所有第 1 版領域路徑和元件名稱。
• selectors：iquery 會列印指定選取器位置下所有可用的選取器。

這些模式可以搭配使用，如下所示：

iquery show component_name

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

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

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，以遞迴方式列出相符位置中的資料。您可以改寫為：

iquery show component_name

Archivist

Fuchsia 診斷平台由 Archivist 代管，負責監控及匯總 Inspect 資料。

在元件管理服務下執行時，診斷資料會透過事件功能提供給 Archivist。

根領域會向 Archivist 提供事件。因此，它會看到整個系統的事件。該外掛程式可查看及訂閱的事件如下：

• CapabilityRequested：當元件連線至 InspectSink 或 LogSink 時，系統會將此事件傳送至 Archivist，而非一般目錄連線。這樣一來，Archivist 就能知道連線至這些通訊協定的元件路徑名稱和網址。

如要公開 Inspect，元件必須使用 fuchsia.inspect.InspectSink 通訊協定。元件通常會轉送 diagnostics 字典，因此通常會如下所示：

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

有一個實用的資訊清單包含項目，可簡化這項作業，且為 Inspect 程式庫所需：

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

如果元件沒有轉送至 diagnostics 字典，且只有轉送至通訊協定，則使用方式通常如下：

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

從 Archivist 讀取檢查結果

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