診斷選取器

總覽

Fuchsia 中的診斷平台包含多項服務。這些服務 (例如資料篩除、指標輪詢和錯誤狀態分析) 都需要描述其診斷資料的特定屬性。

我們已建立名為「Diagnostics Selectors」的特定領域語言 (DSL)，可用於描述元件公開的診斷屬性。選取器的設計目的是針對診斷架構採取行動，並在下列情況下使用：

  1. 診斷資料會以「資料層級結構」編碼，其中命名節點會代管子節點和命名診斷屬性。
  2. 診斷階層可歸因於透過其別名公開該資料的特定元件。

診斷選取器的語法如下：

<component_selector>:<hierarchy_path_selector>:<property_selector>

上述語法的三個部分可逐步為 Fuchsia 診斷資料來源建立索引：

  • component_selector：以產生器的別名指定診斷資料的產生器。
  • hierarchy_path_selector：指定透過資料階層 (由產生者公開) 到特定感興趣節點的路徑。
  • property_selector：指定在階層中指定的節點上，有興趣的特定屬性。

在診斷平台上建構的部分工具 (例如「分類」和「偵測」) 需要使用選取器來區分資料類型。這些工具會透過額外的語法擴充選取器 DSL，指定資料類型：

INSPECT|LOG|LIFECYCLE:<component_selector>:<hierarchy_path_selector>:<property_selector>

下文將詳細說明這些語法各個部分。

以檔案形式

留言

您可以將診斷選取器寫入平面目錄中的 cfg 檔案。在這些檔案中，您可以使用 // 編寫註解。例如：

// a comment
core/sessions/foo

core2/session:foo  // inline comment

元件選取器

語法

元件選取器定義的模式會描述元件拓撲中一或多個元件的路徑名稱。元件選取器是一組以正斜線 (/) 分隔的字串，用來說明從根元件到所需元件的路徑。

以下元件拓撲用於示範元件選取器語法：

以下是選取器的視覺化樹狀圖表示

考慮下列元件選取器，以便在這個拓撲中運作：

core/sessions/foo

這個元件選取器可明確識別相對於其祖系 core 的 foo 元件。

元件選擇器的每個區段 (以正斜線分隔的部分) 都會精確描述元件拓撲的一個「層級」。

元件選擇器區段只能包含元件路徑名稱中可接受的字元。每個元件選取器片段都是執行個體名稱或含有執行個體名稱的集合名稱，且允許使用的字元和長度受到限制。在集合名稱和例項名稱之間的冒號 : 必須使用反斜線 (\) 逸出。

萬用字元

元件選取器支援萬用字元，可比對元件選取器的單一「層級」。請考慮下列 component_selector，並套用至上述示例拓樸圖：

core/other_comp/*

這個選取器會比對系統中所有在名為 other_comp 的父項下執行的元件，而父項本身則在 core 下執行。以下是這些名稱：

  • core/other_comp/foo
  • core/other_comp/bar

萬用字元也可以用於元件選取器的單一「層級」做為字串完成規則運算式。請參考下列元件選取器，並與上述拓撲圖比較：

core/*_comp

這會比對系統中所有在名為 core 的父項下執行的元件，且這些元件的名稱以 _runner 結尾。包括以下別名：

  • core/some_comp
  • core/other_comp

元件選擇器可能會以遞迴萬用字元 ** 結尾，這會比對指定領域下的所有元件：

core/**

這會比對在 core 或 core 的任何子領域下執行的系統上，所有元件。

元件選取器 ** 本身會比對系統上的所有元件。

階層路徑選取器

語法

階層路徑選取器會定義模式，用來描述從結構化資料階層到一個或多個命名節點的路徑。這個子選取器的語法幾乎與元件選取器的語法相同，因為兩者都會透過命名節點的樹狀結構描述路徑。唯一的差異是可選的樹狀結構名稱篩選器，這會在下文中討論。

請參考以下診斷資料階層的 JSON 編碼。在本例中，階層來自「檢視」功能。

"root": {
    "reverser_service": {
        "connection-0x0": {
            "request_count": 1,
        },
        connection_validity: {
            "is_valid": true
        },
        "connection_count": 1,
        "connection_validity": "connection_xyz"

    },
    "version": "part1"
}

根據這個資料階層，請考慮使用下列階層路徑選取器：

root/reverser_service/connection-0x0

這個階層路徑選取器可明確描述從資料階層根目錄到資料階層中特定節點的路徑。

選取器的每個區段 (以正斜線分隔的部分) 都會描述資料階層的一個層級或節點。階層路徑選取器片段可包含任何字元，但如果片段需要包含星號 (*)、正斜線 (/)、反斜線 (\)、空格 (分頁符號 \t 或 ) 或冒號 (:)，則必須逸出這些字元。

請注意，階層路徑選取器 (而非元件選取器) 的獨特情況是，某個節點同時共用同名子項和屬性。請考慮下列選取器：

root/reverser_service/connection_validity

這個路徑階層選取器會描述從根目錄到 connection_validity 節點的路徑。這與 reverser_service 節點上的 connection_validity 屬性完全無關，您可以使用資源選取器：root/reverser_service:connection_validity 選取該屬性。

萬用字元

階層路徑選取器支援萬用字元，可與元件選取器的單一「層級」相符。以下範例會比對資料階層中的所有節點，這些節點是根目錄下節點 reverser_service 的子項：

root/reverser_service/*

萬用字元也可以用於元件選取器的單一「層級」做為字串完成規則運算式。以下範例會比對 reverse_service 下所有以 connection- 開頭的節點。

core/reverser_service/connection-*

在上例中，唯一符合的節點是 connection-0x0，但如果有更多連線節點，也會符合。

樹狀結構名稱篩選器

當元件發布多個 fucshia.inspect.Tree 通訊協定時，選取器語法可根據通訊協定中繼資料中的 name 值，篩選這些樹狀結構。

假設您在執行 ffx inspect show core/my_component 時，檢查階層如下所示：

core/my_component:
  metadata:
    name = root
    component_url = fuchsia-boot:///my_component#meta/my_component.cm
    timestamp = 70863435581892
  payload:
    root:
      connections:
        connections_closed = 7
core/my_component:
  metadata:
    name = second_tree
    component_url = fuchsia-boot:///my_component#meta/my_component.cm
    timestamp = 70863435581892
  payload:
    root:
      data:
        values = [0, 1, 2]

如果您知道要使用屬性 root/data:values，可以使用樹狀結構名稱篩選器，避免產生兩個樹狀結構快照的額外負擔，使用以下語法 (目前不包含屬性選取器部分)：

[name=second_tree]root/data

如果您不知道要選取哪個樹狀結構，或是確定要從所有樹狀結構中選取，可以使用這個階層選取器：

[...]root

這相當於列出所有名稱：

[name=root, name=second_tree]root

目前略過清單會視為等同於 [...]，但這是一個軟性轉換。如果您知道元件會匯出多個名稱不同的樹狀結構，請使用明確的語法。

如果元件在發布檢查時未指定名稱，則預設名稱為 root。這個錯誤會追蹤省略的名稱篩選器清單，使其等同於 [name=root]。

名稱篩選器清單中的值沒有字元限制，但必須轉義 *。如果名稱包含 [a-zA-Z0-9-_] 以外的值，則必須以引號括住名稱。在引號內的名稱中，內部引號必須加上反斜線。

名稱篩選器會區分大小寫。

資源選取器

語法

屬性選取器是所有子選取器中最簡單的選取器。它定義了用來比對單一字串的模式，該字串是診斷階層中的屬性名稱。診斷階層中的所有屬性都有字串名稱。省略資源選取器，實際上就是階層路徑選取器

如同先前的選取器區段，如果您想比對星號 (*)、正斜線 (/)、反斜線 (\)、空格 (分頁符號 \t 或 ) 或半形冒號 (:)，則必須使用反斜線 (\) 進行轉義。

萬用字元

萬用字元可用於比對整個資源字串，或用作字串完成 glob。

eg: abc will match any string with the exact name "abc".
eg: a\* will match any string with the exact name "a*".
eg: a\\* will match any that starts with exactly "a\".
eg: a* will match any string that starts with "a".
eg: a*b will match any string that starts with a and ends with b.
eg: a*b*c will match any string that starts with a and ends with c, with b in the middle.

完整選取器範例

以下選取器會從系統上任何 echo.cm 例項中選取資料，這些例項位於 realm1 底下的任何領域。擷取的資料會是 a/b/c 節點上的 active_connections 屬性。

realm1/*/echo:a/b/c:active_connections

以下選取器會從系統上任何 echo.cm 例項中選取檢查資料，這些例項位於直接位於 realm1 下的任何領域中。檢查資料會是 a/b/c/d 節點上的 memory_usage property。

realm1/echo:a/b/c/d:*