設定分類

篩選器會根據設定檔分析診斷資料。

總覽

透過 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() 會傳回 true
    • False() 會傳回 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_managercore/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 檔案相同:地圖陣列,其中每個地圖都包含 pathcontents 欄位。

    "tests": {
        "test1": {
            "yes": ["action1", "action2"],
            "no": ["action3"],
            "inspect": [
                {
                    "path": "global_data",
                    "contents": {"root": {"stats":
                        {"total_bytes": 10, "used_bytes": 9}}}
                }
            ]
        }
    }