篩選器會根據設定檔分析診斷資料。
總覽
透過 Triage,任何人都能輕鬆新增新方法,針對非正常情況分析 fx snapshot
資料。
根據預設,系統會從 //src/diagnostics/config/triage/*.triage
讀取設定檔。只要在該處新增設定檔即可。
設定檔語法為 JSON5。
每個設定檔都會指定四種設定:選取器和評估 (統稱為「指標」)、動作和測試。
- 選取器會載入評估和動作所需的值。
- Evals 會計算 Evals 和 Actions 要使用的值。
- 動作會決定如何針對特定指定值採取行動。
- 測試包含範例資料,可驗證指定的動作是否正確觸發。
每個 Select、Eval、Test 和 Action 都有名稱。因此,設定檔的結構如下:
{
"select": {
"select1": "type:component:node/path:property",
"select2": "type:component:node/path:property"
},
"eval": {
"name1": "select1+select2",
"name2": "select1 - select2"
},
"act": {
"action1": { .... },
"action2": { .... }
},
"test": {
"test1": { .... },
"test2": { .... }
}
}
名稱和命名空間
Select、Eval、Action、Test 和設定檔名稱由一個小寫英文字母或底線字元組成,後面接零個或多個英數字元或底線字元。因此,「abc123」和「_abc_123」是有效名稱,但「123abc」、「a.b.c」和「abc-123」則無效。特別注意,檔案名稱不得包含半形句號,但 .triage
副檔名除外。
一個檔案中的評估、測試和動作,可以參照另一個檔案中的選取器、評估和動作。檔案基礎名稱會用來做為命名空間。::
用做分隔符。舉例來說,如果載入檔案 foo.triage
,且其中包含名為 bar
的 Metrics,則任何設定檔都可能會參照 foo::bar
。
您可以在指標、測試和動作之間重複使用名稱,但在 Select 和 Eval 之間則不行。
使用者定義的名稱開頭必須為小寫英文字母。語言提供的函式開頭為大寫字母。
注意:目前的計畫版本不保證會強制執行這些限制。
選擇器
選取器使用 Selector 格式。第一個 :
前面的文字會從 inspect.json
檔案中選取元件名稱。以 .
分隔的中間部分會指定檢查節點名稱,形成通往第二個 :
後方命名的屬性路徑。
計算方式
Eval 字串是具有一般運算子優先順序的內嵌數學運算式。
) 可用於指定值。
算術運算子包括 +
-
*
/
//
/?
//?
。/
是浮點除法,//
是整數除法。含有 ?
的除法運算子會在除以 0 時傳回 Problem::Ignore。
函式包含函式名稱、半形逗號分隔的運算式清單和半形括號。提供的函式包括:
- 布林值
And(1+ args)
Or(1+ args)
Not(1 arg)
- 如果值是
Missing
類型錯誤指示,Missing(value)
會傳回 true。 - 如果值是任何類型的錯誤,
Problem(value)
會傳回 true。 True()
會傳回 trueFalse()
會傳回 false
- 數字
Min(1+ args)
Max(1+ args)
Abs(1 arg)
- 功能
Fn([name1, name2, ...], expression)
Map(function, vector1, vector2, ...)
Fold(function, vector, optional_start_value)
Filter(function, vector)
Apply(function, [arg1, arg2, ...])
CountProperties(vector)
會計算向量中的屬性數量。CountChildren(vector)
會計算向量中的子項 (節點) 數量。
- 時間
Days()
、Hours()
、Minutes()
、Seconds()
、Millis()
、Micros()
和Nanos()
會計算值,以便與單調時間戳記進行比較。Now()
會傳回診斷資料建立時的近似時間戳記。
- 其他
Option(value1, value2, value3...)
會傳回第一個實用值,以支援選取器遷移作業和預設值:第一個非空白清單、非遺漏值 (如果有);如果提供空白清單,則傳回空白清單;或傳回遺漏值。Annotation(string)
會從 annotations.json 檔案 (如有) 擷取對應的鍵。- 如果 syslog、核心記錄或先前啟動記錄包含與規則運算式相符的一行,
SyslogHas(regex)
、KlogHas(regex)
、BootlogHas(regex)
會傳回true
。 StringMatches(value, regex)
會將指定的規則運算式套用至指定的值,如果相符,則傳回 true。規則運算式語法是 Rust 規則運算式 crate 支援的語法。
指標類型會遵循從檢查檔案讀取的類型。目前,UInt 會在讀取時轉換為 Int。對混合 Int 和 Float 執行的作業會將結果提升為 Float。
布林運算子為 >
<
>=
<=
==
!=
。相等性測試 ==
和 !=
會比較數字、布林值、字串和向量。>
<
>=
<=
只會比較數字。
空格可用於任何位置,但建議在內嵌運算子周圍使用。
指標名稱 (包括命名空間名稱) 不需要特別分隔。
函式式程式設計和向量
每個選取器實際上都會傳回向量,但系統會自動展開單一項目向量,以便進行算術和布林運算。檢查不含萬用字元的選擇器會傳回一個項目的向量,除非 inspect.json 中出現相同的路徑名稱。
含有萬用字元的選取器、bootstrap/driver_manager
和 core/network/netstack
的選取器,以及 (最終) 記錄中的選取器,可能會在向量中傳回多個項目。為了處理這類值,Triage 提供下列函式:
- Fn(參數、運算式) - 例如
Fn([a, b], a+b)
- Map(function, vector1, vector2...)
- Fold(函式, 向量) 或 Fold(函式, 向量, 起始值)
- Filter(函式, 向量)
- Count(向量)
值向量會以 [ expr, expr, expr ]
寫入。
如果 Map 的 values
引數不是向量,其值會套用至每個迭代。如果所有 values
都不是向量,或是未提供 values
,系統會傳回空向量。如果向量 values
的長度不同,則最短的向量會決定結果長度,而系統不會使用剩餘的值。
Count() 不會檢查向量 values
中的項目類型。非向量 values
的 Count() 會傳回「Missing」。
如果 Fn 運算式是「eval」運算式的完整內容,則該運算式的名稱可用於 Map、Fold 或 Filter 的首個引數。
如果函式引數的位數不正確,傳遞至該函式的函式會傳回 Missing。如果函式評估失敗 (例如因類型不正確),則傳遞至該函式的函式可能會傳回部分值:
- Map 會傳回向量,其中部分元素可能會遺失。
- 折疊會傳回「缺少」。
- 篩選器會預期其篩選器函式會傳回布林值 true 或 false。如果該函式傳回其他值 (包括遺漏值),Filter 會在結果清單的該位置新增遺漏值。
動作
每個動作都會決定如何顯示特定選取器的資訊。目前有兩種動作:「警告」和「量表」。您可以為 type
欄位提供適當的值,藉此指定動作。
警告類型
Warning
是用於在符合布林值條件時發出快訊的動作。
Warning
支援下列欄位:
trigger
是必填欄位,用於指定提供布林值的指標名稱。print
為必填欄位,用於指定在發生警告時要輸出的字串。tag
是選填欄位,可將標記與此動作建立關聯。file_bug
是選用的字串欄位,可指定要提交的錯誤和提交位置。分類作業不會直接回報錯誤;這個欄位只是通知消費者 (人類使用者或自動化管道)。可以是 Issue Tracker 元件 (例如「Fuchsia > Internationalization (i18n)」),或是消費者瞭解的其他 Issue Tracker 參照。
"actions": {
"disk_usage_high": {
"type": "Warning", "trigger": "disk_used / disk_total > 0.95", "print": "Disk usage is high!"
}
}
量表類型
Gauge
是啟用 Triage 時特定值的快照。Gauge
支援下列欄位:
value
是必填欄位,可指定要顯示的值。format
是選用欄位,可指定量測儀值的格式規則。
格式
format
欄位可讓使用者控制量表值的顯示方式。如果未提供這個欄位,或提供無效的值,系統會照原樣顯示值。format
支援以下值:
percentage
:以百分比值的形式列印浮點值。
"actions": {
"disk_usage": {
"type": "Gauge", "value": "disk_used / disk_total", "format": "percentage"
}
}
測試
每個測試都會指定下列項目:
- 以
inspect
做為索引的資料 - 在指定資料下應觸發的動作清單,以
yes
做為索引 - 在給定資料下,不應觸發的動作清單,以
no
做為索引
樣本資料的格式與 inspect.json 檔案相同:地圖陣列,其中每個地圖都包含 path
和 contents
欄位。
"tests": {
"test1": {
"yes": ["action1", "action2"],
"no": ["action3"],
"inspect": [
{
"path": "global_data",
"contents": {"root": {"stats":
{"total_bytes": 10, "used_bytes": 9}}}
}
]
}
}