診斷選取器

總覽

Fuchsia 中的診斷平台含有多項服務。這些服務 (例如資料竊取、指標輪詢和錯誤狀態分析) 都需要說明診斷資料的特定屬性。

我們建立了網域專屬語言 (DSL)，也就是「診斷選取器」，能夠描述元件所公開的診斷屬性。選取器專為診斷結構定義而設計，適用於以下情況：

  1. 診斷資料在「資料階層」中編碼，其中命名的節點會代管子節點和已命名的診斷屬性。
  2. 診斷階層會將資料歸因於特定元件，而這些元件會由開發人員公開該資料。

診斷選取器包含下列高階語法：

<component_selector>:<hierarchy_path_selector>:<property_selector>

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

  • component_selector：請根據生產端的模擬器指定診斷資料的生產端。
  • hierarchy_path_selector：指定透過生產端 (生產端) 公開至特定興趣節點的資料階層路徑。
  • property_selector：為您在階層中指定的節點指定感興趣的特定屬性。

部分內建於診斷平台的工具 (例如「Triage」和「Detect」) 需要區分資料類型與其選取器。這些工具會使用額外的語法指定資料類型，擴充選取器 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

這個元件選取器會明確識別稱為 foo 的元件 (相對於其祖系 core)。

元件選取器的每個區段 (以正斜線分隔的區段) 分別描述了元件拓撲的一個「層級」。

元件選取器區段只能包含元件路徑名稱接受的字元。每個元件選取器區段都是執行個體名稱或集合名稱，其中包含執行個體名稱，其允許的字元和長度組合設有限制。集合名稱與執行個體名稱之間的冒號 : 必須以反斜線 (\) 逸出。

外卡

元件選取器支援萬用字元，可比對元件選取器的單一「層級」。請考慮套用至上述拓撲範例的以下 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，但如果存在更多連線節點，也會進行比對。

資源選取器

語法

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

和先前的選取器區隔一樣，若要與星號 (*)、正斜線 (/)、反斜線 (\)、空白字元 (分頁 \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

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

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