分類程式碼研究室

協作者：cphoenix@

本程式碼研究室說明 Triage 公用程式：

• 用途
• 執行方式，包括指令列選項。
• 如何新增及測試設定規則來偵測 Fuchsia 的問題 快照

這份文件參照的來源檔案和範例如下：

• //examples/diagnostics/triage/snapshot/inspect.json.
• //examples/diagnostics/triage/rules.triage.
• //examples/diagnostics/triage/solution.

什麼是「分類」？

您可以運用「分類」功能掃描 Fuchsia 快照 (snapshot.zip 檔案)，找出預先定義的 條件。

Triage 系統可讓您輕鬆設定新的條件，使 可讓所有人享有實用的 Triage 服務

必要條件

在開始本程式碼研究室之前，請確認您已完成下列步驟：

• 開始使用。
• 使用 fx build 建構了 Fuchsia 版本。

透過指令列執行 Triage

• 如何執行分類：

fx triage

這個指令會使用 fx snapshot 下載新的 snapshot.zip 檔案 指令這個指令會執行位於原始碼中的預設規則 樹狀結構：

• //src/diagnostics/config/triage/*.triage

如要分析特定快照.zip 檔案，請使用 --data。

• 您最多只能指定一個 --data 引數。
• --data 的引數也可以是包含 解壓縮的快照。
• 如果您執行 fx triage 時未指定 --data 選項，系統會執行新的 fx snapshot並分析其檔案。

fx triage --data my/foo/snapshot.zip

如何使用特定設定檔或某個 Pod 中的所有 *.triage 檔案 目錄中使用 --config。

• 您可以使用多個 --config 引數。
• 如果使用 --config 引數，則不會預設規則 就會自動載入。

fx triage --config my/directory --config my/file.triage

新增分類規則

本程式碼研究室的其餘部分將說明如何在 Triage 中設定新行為。

總覽

Triage 將診斷資料的龐大量壓縮成實用資訊， 步驟如下：

1. 使用inspect.json 設定檔的 select 部分。
2. 進行運算和比較以產生新的值，如 設定檔的 eval 部分。
3. 根據設定檔 act 部分中的項目採取行動。
   1. 如果錯誤條件 (布林運算式) 為 true，就會警告。
   2. 向使用者顯示一個值。
4. 透過 test 中的項目，支援單元測試動作和運算 專區。

尋找程式碼研究室的範例檔案

前往原始碼樹狀結構中的 examples/diagnostics/triage 目錄。 下列指令是用來從該目錄執行：

fx triage --config . --data snapshot

使用未經修改的程式碼研究室檔案，在範例目錄中執行這個指令 會從預先提供的動作中列印一行：

Warning: 'always_triggered' in 'rules' detected 'Triage is running': 'always_true' was true

inspect.json

本程式碼研究室提供具有「檢查」資料的 inspect.json 檔案， 練習是可以預測的這個檔案位於 snapshot/inspect.json。

rules.triage

分類程式使用從一或多個 .triage 檔案載入的設定。 本程式碼研究室會使用範例目錄中的 rules.triage 檔案。

.triage 檔案使用 JSON5，寫入和讀取比 JSON 容易：

• 建議您在最後一個清單項目後面加上半形逗號。
• 大多數金鑰 (包括所有有效的分類名稱) 不需要包裝 引號。
• /* 多行 */ 和 // 可以使用單行註解。

新增「檢查」值的選取器

範例目錄中的 inspect.json 檔案表示幾個問題 與系統的連結您將設定分類系統來偵測 如要解決關聯問題，可用 Apriori 這類關聯規則學習技術和演算法

這個步驟會設定 Triage 從 inspect.json 檔案。

rules.triage 檔案包含名為 select 的鍵/值區段。每個鍵 (name) 可用於其他設定項目的主體。每個值都是一個選取器 字串。實際上，select 區段 (和 eval 區段) 中的每個項目 定義變數。

選取器字串是半形冒號分隔的字串，可用來指出檢查區中的位置 找出需要的值

select: {
    disk_total: "INSPECT:bootstrap/fshost:root/data_stats/stats:total_bytes",
    // "data_stat" is an intentional typo to fix later in the codelab.
    disk_used: "INSPECT:bootstrap/fshost:root/data_stat/stats:used_bytes",
}

檢查元件發布的資料會組織成採用 值 (屬性) 值。inspect.json 檔案是 樹狀結構，每個物件都有一個識別來源元件的路徑名稱。

選取器字串中 INSPECT: 與第二個冒號之間的部分 應與 inspect.json 檔案中的其中一個路徑名稱字串相符。

第二和第三個冒號之間的部分是 / 分隔的節點清單 。

最後一個冒號後方的部分即為屬性名稱。

上述選取器字串表示 moniker 與 字串 bootstrap/fshost，其檢查樹狀結構包含路徑 root/data_stat/stats。它也指出了來自used_bytes 該元件檢查樹狀結構中 root 節點的 stats 子節點。

將上述選取器放入「選取」Rules.triage 檔案的一部分。

產生選取器

以手動方式輸入選取器不容易出錯，因此可以使用 fx triage --select 輸出有效的選取器。

fx triage --data snapshot --select total_bytes
INSPECT:bootstrap/fshost:root/data_stats/stats:total_bytes

您可以使用多個 --select 參數。這個程式會產生 可能適合快照診斷資料的選擇器，然後篩選 (grep) 測試所有 --select 參數。

新增運算

從 inspect.json 檔案中選取值後，您需要執行一些邏輯。 也可以算是算術結果 以便瞭解這些值是否 值得檢舉的威脅

複製下列程式碼，並新增至 rules.triage 檔案的 eval 部分 來計算磁碟大小：

eval: {
    ....
    disk_percentage: "disk_used / disk_total",
}

eval 個項目使用一般中置數學運算式。請參閱詳細資料 一節。

新增動作

「表演」部分，請新增動作，在系統顯示警告時 而磁碟佔 98%使用以下指令行：

act: {
    ...
    disk_full: {
        type: "Warning",
        trigger: "disk_percentage > 0.98",
        print: "Disk reached 98% full",
    },
}

注意事項：

• 「觸發條件」會評估為布林值的運算式。這可能會 布林類型選取器或計算名稱，或任何適用的數學運算 運算式。
• 如要進一步瞭解比較方法，請參閱詳細資料一節。
• 如需其他支援的設定，請參閱設定參考資料 動作。

新增度量單位

act: {
    ...
    disk_display: {
        type: "Gauge",
        value: "disk_percentage",
        format: "percentage",
    }
}

測量結果一律顯示提供的值。

format 為選填欄位。「百分比」的值告訴輸出 formatter 的值必須是 0 到 1 之間的值，並以百分比顯示。

立即試用

下列指令將對本機設定檔執行 Triage。

fx triage --config . --data snapshot

您會看到類似下方的錯誤：

[ERROR] In config 'rules': No value found matching selector
bootstrap/fshost:root/data_stat/stats:used_bytes

選取器規則有錯字。分類找不到 評估規則事實上，正確的選取器是「data_stats」而非「data_stat」。 請在選取器規則中修正，然後再試一次。

fx triage --config . --data snapshot

發生什麼事了？沒事吧？但該如何得知是否有任何 inspect.json 檔案有問題，還是規則發生錯誤？

測試規則

您可以 (也應該！) 為動作新增測試。為每項測試指定值 以及這些值是否觸發規則

如要測試新增的規則，請將下列指令新增至test rules.triage 檔案：

test: {
    ....
    is_full: {
        yes: ["disk_full"],
        values: {
            disk_used: 98,
            disk_total: 100,
        }
    }
}

values 區段中的鍵應為 eval 或 select 的名稱 項目。提供的值會覆寫該項目的 選取或計算的部分

您也可以測試不應觸發動作的條件：

test: {
    ....
    not_full: {
        no: ["disk_full"],
        values: {
            disk_used: 97,
            disk_total: 100,
        }
    }
}

只要執行 Triage 即可進行測試。並在每次通過測試時，自動自我測試 此程序的第一步 是將程式碼簽入執行所有單元測試的存放區中

fx triage --config . --data snapshot

哎呀！這應該會顯示錯誤：

Test is_full failed: trigger 'disk_percentage > 0.98' of action disk_full returned Bool(false), expected true

修正規則

您希望在磁碟滿 98% 時觸發，但不確定功能為何 而您的測試找到問題。將動作中的 > 修改為 >=：

        trigger: "disk_percentage >= 0.98",

再次執行 Triage。錯誤應該消失，並會顯示一則警告 inspect.json 檔案實際上表示是完整磁碟。

Warning: 'disk_full' in 'rules' detected 'Disk is 98% full': 'disk98' was true

記錄檔掃描

您可以編寫運算式來測試一行記錄檔 (syslog.txt、 klog.txt、bootlog.txt) 與規則運算式進行比對。內容看起來會像這樣：

    eval: {
        syslog_has_not_found: "SyslogHas('ERROR.*not found')",
        ...
    }
    act: {
        something_not_found: {
            trigger: "SyslogHas('ERROR.*not found')",
            ...
        }
    }

支援的函式包括 SyslogHas()、KlogHas()、BootlogHas()。如果缺少記錄檔 (例如，某些快照不包含 bootlog.txt)，系統會將其視為 空白檔案

如要進行測試，您可以在測試中加入項目，如下所示：

test: {
    test_error: {
        yes: [error_scan],
        syslog: "ERROR: file Foo not found\nSecond line OK",
    }
}

annotations.json

快照中包含檔案 annotations.json，該檔案含有 包括建構、開發板和運作時間等

您可使用 Annotation() 函式搭配 單一字串參數，是檔案中 JSON 物件的鍵。適用對象 例如

eval: {
    using_chromebook: "Annotation('build.board') == 'chromebook-x64'",
}

使用多個設定檔

您可以新增任意數量的 Triage 設定檔，甚至使用變數 用於另一個檔案中定義的這些都有許多應用程式：

• 一個檔案用於存放磁碟相關變數和動作，另一個用於 網路相關變數和動作
• 用於定義產品專屬編號的檔案。
• 特定工程師或團隊專屬的檔案。

新增「product.triage」檔案包含下列項目：

{
    eval: {
        max_components: "4",
    },
}

注意事項：

• .triage 檔案可以省略空白部分。這個檔案不包含 「select」、「act」或「test」項目。
• 雖然 JSON 中的數值未加上引號，但 4 是數學運算式 字串，因此必須以引號括住。

將下列項目新增至 rules.triage 檔案：

select: {
    ...
    actual_components: "INSPECT:bootstrap/archivist:root/event_stats:components_started",
}

這麼做會擷取裝置正在使用的元件數量。

eval: {
    ...
    too_many_components: "actual_components > product::max_components",

也就是比較實際元件與理論上最高 產品。

最後，請新增動作：

act: {
    ...
    component_overflow: {
        type: "Warning",
        trigger: "too_many_components",
        print: "Too many components!",
    },
}

很抱歉，這部裝置嘗試使用過多元件，因此這則警告 「外加分類」執行。

在正式環境中，可以有多個「product.triage」檔案可能會 並在不同目錄中使用「 Triage」 「--config」指令列引數

測試和命名空間

測試只會使用發生測試的檔案中的指標，以及 測試提供的值。使用 命名空間值，例如「a::b」這些值必須由「a::b」提供項目 測試值

test: {
    component_max_ok: {
        no: [
            "component_overflow",
        ],
        values: {
            actual_components: 17,
            "product::max_components": 17,
        },
    },
},

詳細資料

名稱

名稱 (選取器、運算式、動作和測試，以及基準名稱) 可以是任何字母或底線，後面加上任意數量的 字母、數字或底線。

在後續版本中，以底線開頭的名稱可能具有特殊意義 分類。儘管如此，但還是建議你避免使用。

每個 .triage 檔案的名稱都會建立其命名空間。正在載入兩個 .triage 不允許名稱來自不同目錄的檔案。

數學運算式

• 變數可以是 64 位元浮點值、帶正負號 64 位元 int 或布林值。
• 算術運算式會使用 + - * / // 運算子，其中包含一般順序和 作業的優先順序
• 除法運算子 / 會產生浮點值。
• 除法運算子 // 會產生 int 值，進而截斷結果 朝 0 達成(請注意，此與 Python 3 不同 其中 // 會向下截斷)。
• + - * 會保留運算元的類型 (混合提升為浮點值)。
• 比較運算子為> >= < <= == !=
• 比較項目有布林值結果類型，可用來觸發動作。
• 您可以在單一 eval 規則中合併計算和比較項目。
• 您可以使用括號。
• 您可以使用 eval 和 select 項目的鍵名做為變數。
• 不一定要在任何地方，空格則允許在任何地方，但內部除外 filename::variable 命名空間變數。

預先定義的函式

Triage 提供可用於 eval 運算式的預先定義函式：

• Max(value1, value2, value3...) 會傳回最大的值，類型為 升級為浮點值
• Min(value1, value2, value3...) 會傳回最小值，類型為 升級為浮點值
• And(value1, value2, value3...) 會使用布林引數並傳回 邏輯運算子 AND 值
• Or(value1, value2, value3...) 會使用布林引數並傳回 邏輯運算子 OR。
• Not(value) 會使用一個布林引數，並傳回其邏輯「NOT」。
• SyslogHas(matcher)、KlogHas(matcher)、BootlogHas(matcher) 如果發生以下情況，則傳回 true 對應的記錄檔會包含行比對器 (即字串) 包含規則運算式
• Annotation(key) 會從 annotation.json 傳回對應的值 檔案。
• Option(value1, value2, value3...) 會傳回第一個實用的值，以便 支援選取器遷移和預設值：第一個非空白清單 非遺漏值 (如有)；或空白清單 (如果有的話)；或遺漏。
• 如果值是錯誤指標，Missing(value) 會傳回 true。
• Days()、Hours()、Minutes()、Seconds()、Millis()、Micros()、 和 Nanos() 計算與單調時間戳記比較的值。
• Now() 會傳回診斷資料之前的近似時間戳記 已建立。
• StringMatches(value, regex) 會將指定的規則運算式套用到指定的 如果有相符項目，則會傳回 true。規則運算式語法是 Rust 規則運算式 Crate 支援。

，瞭解如何調查及移除這項存取權。

功能程式設計

分類可以將函式套用至值的向量。向量的 "[expr, expr, expr...]"。有些選取器會傳回多元素向量。

Triage 提供 Map()、Fold()、Filter() 和 Count() 函式， 處理向量的 Fn() 定義函式或 lambda，分別用於地圖、摺疊和 要套用的篩選器，並使用 Apply() 將 Fn() 套用至引數。

詳情請參閱設定 fx 分類。

其他資訊

如要瞭解最新功能和選項，請參閱 fx triage。 持續精進！