檢查探索與託管

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

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

代管檢查資料

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

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

元件不必與其他服務聯繫，即可公開檢查資料。

元件通常不需要關心使用哪種方法，用戶端程式庫會抽象出特定的代管機制。幾乎所有實作方式最終都會使用 Tree。

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

fuchsia.inspect.Tree

fuchsia.inspect.Tree 支援 Inspect API 的所有功能，也是從元件公開 Inspect 資料的建議方式。

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

實作

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

Tree 通訊協定會將多個 Inspect VMOs 連結成「樹狀結構」。

在上圖中，名為「root」的樹狀結構會處理 fuchsia.inspect.Tree 下頂層服務連線的通訊協定 fuchsia.inspect.Tree。子樹狀結構可以使用通訊協定上的函式列舉及開啟。舉例來說，「child B」可能在開啟及讀取時才會出現在記憶體中。

協定會透過下列方式支援這項行為：

• GetContent

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

• ListChildNames

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

• OpenChild

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

fuchsia.inspect.deprecated.Inspect

Go 會使用這個已淘汰的介面，公開檢查資料。fuchsia.inspect.Tree 會公開「樹狀結構的樹狀結構」，但這個介面只會公開單一樹狀結構，其中的子樹狀結構可透過動態方式建立。

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

• VMO 格式支援低延遲快照，且不必與代管程式通訊。
• VMO 格式的快照在整個樹狀結構中始終保持一致。
• VMO 格式支援事後檢查，所有使用已淘汰介面的檢查資料都會隨著元件消失。
• Tree 通訊協定支援與已淘汰介面相同的動態功能。

讀取檢查資料

讀取檢查資料的主要方法有兩種：

1. iquery
2. Archivist

iquery

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

iquery的主要運作模式會採用檢查資料的選取器清單，並列印出其中包含的資訊。選取器由三個部分組成，並以 : 分隔：

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

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

iquery 包含兩個公用程式指令，可讓您瞭解可用的元件和可用的選取器：

• list：iquery 會列印所有可用的元件選取器，也就是所有 v2 別名和所有含有元件名稱的 v1 領域路徑。
• selectors：iquery 會在提供的 selector 位置下列印所有可用的 selector。

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

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

iquery show component_name

檔案管理員

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

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

根領域提供事件給 Archivist。因此，它會看到整個系統的事件。允許查看及訂閱的事件如下：

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

如要公開檢查功能，元件必須使用 fuchsia.inspect.InspectSink 通訊協定。元件通常會將 diagnostics 字典路由至自身，因此通常會如下所示：

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

檢查程式庫需要的資訊清單包含實用資訊，可簡化這項作業：

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

如果元件沒有傳送至 diagnostics 字典的路徑，且元件只傳送至通訊協定的路徑，那麼使用時通常會如下所示：

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

從 Archivist 讀取檢查結果

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