設定分類

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

總覽

透過 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_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}}}
                }
            ]
        }
    }