設定分類

Triage 會根據設定檔分析「診斷」資料。

總覽

分類可讓所有人輕鬆新增方法來分析 fx snapshot 資料，因應異常狀況。

根據預設，系統會從 //src/diagnostics/config/triage/*.triage 讀取設定檔。只要新增設定檔即可。

設定檔語法為 JSON5。

每個設定檔都會指定四種設定：選取器和 Eval (統稱為「指標」)、動作和測試。

  • 選取器會載入值供 Evals 和動作使用。
  • 評估功能會計算用於評估及動作的值。
  • 動作會決定如何對特定指定值採取行動。
  • 測試包含範例資料，以便驗證指定的動作觸發條件是否正確。

每項「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": { .... }
    }
}

名稱和命名空間

選取、Eval、動作、測試和設定檔名稱由一個小寫-alphabetic-或底線字元組成，後接零或多個英數字元或底線字元。因此，「abc123」和「_abc_123」都是有效的名稱，但「123abc」、「a.b.c」和「abc-123」則無效。請特別注意，檔案名稱不得包含半形句號，但 .triage 副檔名除外。

在同一個檔案中的評估、測試和動作可以參照另一個檔案中的選取器、評估和動作。檔案 Basename 會做為命名空間使用。:: 則做為分隔符。舉例來說，如果載入 foo.triage 檔案且包含名為 bar 的指標，則任何設定檔都可能參照 foo::bar。

指標、測試和動作之間可重複使用名稱，但無法在「Select」和「Eval」之間重複使用。

使用者定義的名稱開頭必須是小寫英文字母。語言提供的函式是以大寫字母開頭。

注意：目前的程式版本不保證會強制執行這些限制。

選擇器

選取器使用選取器格式。第一個 : 之前的文字會從 inspect.json 檔案中選取元件名稱。中間以 . 分隔的中間部分會指定「檢查節點」名稱，該路徑會以第二個 : 命名的屬性。

計算方式

等值字串是數學運算式不固定，且有一般運算子的優先順序。

()。

算術運算子為 + - * / // /? //?。/ 為浮點除數；// 為獨立區域。含有 ? 的除法運算子傳回問題：：在除法中忽略 0。

函式是函式名稱「'(', 逗號分隔運算式清單, ')'」。 提供的函式包括：

  • 布林值
    • 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, ...])
    • Count(vector)
  • 時間
    • Days()、Hours()、Minutes()、Seconds()、Millis()、Micros() 和 Nanos() 會計算值以與單調時間戳記進行比較。
    • Now() 會傳回診斷資料建立時的約略時間戳記。
  • 其他
    • Option(value1, value2, value3...) 會傳回第一個實用的值，以便支援選取器遷移作業和預設值：第一個非空白清單、非遺漏值 (如有)；或者提供空白清單 (如有)。
    • Annotation(string) 會從註解.json 檔案中擷取對應金鑰 (如果有的話)。
    • 如果 syslog、核心記錄或之前啟動記錄包含與規則運算式相符的行，SyslogHas(regex)、KlogHas(regex)、BootlogHas(regex) 會傳回 true。
    • StringMatches(value, regex) 會將特定規則運算式套用至指定值，如有相符項目，則傳回 true。規則運算式語法受 Rust 規則運算式 Crate 支援。

指標類型會遵循從檢查檔案讀取的類型。目前 UInt 會在讀取時轉換為 Int。在混合 Int 和 Float 上執行的作業會將結果升級為 Float。

布林作業為 > < >= <= == !=。等式測試 == 和 != 會比較數字、布林值、字串和向量。> < >= <= 只能比較數字。

您可以選擇是否要在任意位置加上空白字元，但建議在中置運算子前後加上空格。

指標名稱 (包括命名空間名稱) 不需要特別分隔。

功能程式設計和向量

每個選取器都會傳迴向量，但為了進行計算和布林計算，系統會自動將單一項目向量解除包裝。除非在 check.json 中多次出現同一位路徑名稱，否則檢查不含萬用字元的選取器會傳回單一項目向量。

具有萬用字元的選取器、bootstrap/driver_manager 和 core/network/netstack 的選取器，以及 (最終) 記錄中的選取器，可能會傳迴向量中的多個項目。為處理這類值，Triage 提供下列函式：

  • Fn(參數, 運算式) - 例如 Fn([a, b], a+b)
  • Map(函式, 向量 1, 向量 2...)
  • Fold(函式, 向量) 或 Fold(函式, 向量, start_value)
  • Filter(函式, 向量)
  • 計數(向量)

值的向量會寫入 [ expr, expr, expr ]。

如果傳送至地圖的 values 引數不是向量，系統會將其值套用至每個疊代。如果所有 values 都不是向量，或未提供 values，系統會傳回空白向量。如果向量 values 的長度不同，最短長度會決定結果長度，系統就不會使用剩餘的值。

Count() 不會檢查向量 values 中的項目類型。非向量 values 的 Count() 會傳回遺漏。

如果 Fn 運算式是整個「eval」運算式，則該運算式的名稱可以做為對應、折疊或篩選的第一個引數使用。

如果函式的引數有錯誤的引數，則傳遞該函式並傳回「 Missing」(缺少) 的函式。如果函式的評估失敗，例如因類型不適當，被傳遞的函式可能會傳回部分值：

  • 地圖會傳迴向量，並有可能遺漏部分元素。
  • 缺少折疊退貨裝置。
  • 篩選器會預期其篩選器函式會傳回布林值 true 或 false。如果該函式傳回任何其他結果 (包括「遺漏」)，篩選器會在結果清單的該時間點新增缺少的值。

動作

每項動作都可決定如何顯示特定選取器的資訊。目前有「警告」和「規範」兩種動作類型。藉由為 type 欄位提供適當的值來指定動作。

警告類型

Warning 是一種動作，用於在符合佈林條件時觸發快訊。

Warning 支援下列欄位：

  • trigger 為必填欄位，用於指定提供布林值的指標名稱。
  • print 是必填欄位，指定在發出警告時要輸出的字串。
  • tag 是選填欄位，可將代碼與這個動作建立關聯。
  • file_bug 是選填的字串欄位，會指定應回報錯誤和處理位置。分類不會直接回報錯誤；這個欄位只會通知消費者 (真人使用者或自動化管道)。這可以是 Issue Tracker 元件 (例如「Fuchsia > Internationalization (i18n)」)，或是消費者理解的其他問題追蹤工具的參照。
    "actions": {
        "disk_usage_high": {
            "type": "Warning", "trigger": "disk_used / disk_total > 0.95", "print": "Disk usage is high!"
        }
    }

度量類型

Gauge 是叫用「分類」時特定值的快照。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}}}
                }
            ]
        }
    }