| RFC-0003：Fuchsia 記錄指南 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 使用記錄嚴重性的最佳做法。測試和現場指標中的記錄嚴重性。 |
| 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年/月) | 2020-06-03 |
| 審查日期 (年/月) | 2020-06-11 |
摘要
在 Fuchsia 的程式碼中大量使用 Logging，但訊息記錄的嚴重性不一致。這可減少記錄檔中的資訊值。下方我們提議瞭解不同記錄嚴重性等級的語意，以及各種環境中特定嚴重性的記錄影響。
激勵與問題陳述
記錄是傳送執行中軟體內部狀態變更的診斷信號最常見的方式。這類記錄提供寶貴資訊，可用於偵測及修正軟體和產品中的錯誤。
記錄內容過去包含任意文字訊息，以及列舉的嚴重性值。嚴重性值可以指出訊息的重要性，以便從雜訊中區分信號。然而，在 Fuchsia 程式碼及其依附元件中，嚴重性等級的應用方式皆不一致，導致記錄難以在手動疑難排解和自動化分析中使用。
透過提供如何使用記錄嚴重性的通用準則，並建立程序將結果附加至特定記錄檔方式，我們希望建立虛擬循環，從記錄中產生更多診斷值，同時改善訊號雜訊的比率。例如，我們希望 ERROR 記錄項目的頻率是系統穩定性的其中一個 Proxy。
實作
記錄嚴重性等級
Fuchsia 支援多種標準記錄嚴重性等級：
嚴重
這表示無法復原的錯誤，且元件應在記錄訊息後不久自動終止。這通常表示，系統的核心不變，可能進一步導致資料損毀或安全漏洞。
請謹慎使用這個記錄檔層級。此記錄層級可能表示需要修正的硬體問題或軟體錯誤。由於指定訊息會是元件自我終止前所記錄的最終訊息，因此當中的內容應指出終止原因。
錯誤
此記錄層級代表程式可以復原的不想要事件。ERROR 記錄項目的外觀代表著需要修正的程式行為錯誤。開發人員應盡力在錯誤追蹤工具中的錯誤與 ERROR 記錄項目之間一對一通訊。換句話說，每個不重複的錯誤都應有一個 ERROR 記錄項目，而每個 ERROR 記錄項目都應有一個不同的錯誤。開發人員應盡可能嘗試在程式碼中維持這樣關聯。請注意，錯誤可能不在發出記錄陳述式的程式碼中。錯誤可能位於其中一個呼叫端或其依附元件中。
這個記錄層級以上的資料將做為系統穩定性指標的信號依據。 此外，此記錄層級 (以上) 通常會顯示在錯誤報告中。介紹訊息的團隊以外的人員將會使用這個記錄訊息，因此該訊息應提供充分的背景資訊，協助讀者瞭解問題的根本原因。
警告
此記錄層級代表在系統正常操作的情況下發生非預期的事件。這些非預期的事件可能是環境事件，因此無法控制系統本身。舉例來說，中斷的網路連線可能會記錄為警告，或因輸入無效值而使程式無法繼續繼續記錄，可能會記錄為「警告」。此記錄層級可以用來找出造成問題的根本原因 (通常是 ERROR 記錄項目)。此記錄層級可以很清楚，因為上述非預期的事件而擷取不常見的程式碼路徑。
資訊
這通常是錯誤報告中的最低記錄層級。這表示程式中發生了重大的狀態變更。這個記錄層級會用來指出造成問題的情境 (通常是 ERROR 記錄項目)。與較高的記錄層級一樣，其他團隊將會使用這些記錄進行診斷，因此背景資訊非常重要。
請使用元件檢查功能回報長時間狀態。如果這類狀況沒有變動，就不應記錄。例如，系統不會以固定的時間間隔記錄「[INFO] no configs found」，而是包含標記「configs_found = false」或甚至是「config_count = 0」。
偵錯
這個記錄層級通常用於工程環境，例如在測試期間或在修訂版本佇列機器人重現問題時使用。嚴重性等級為「DEBUG」(偵錯) 以下的記錄通常不會收集在錯誤報告中，因此在錯誤報告中不會預期收到 DEBUG 和更低的記錄。這個記錄層級通常比 INFO 更詳盡，並可協助個別團隊進一步瞭解所開發的系統狀態。
追蹤
這個記錄層級一般會供個別團隊使用，也可能用於修訂佇列和持續整合中。此記錄層級通常用來表示多階段程序中的某個階段已完成。
記錄的後果
我們已製定記錄嚴重性等級的準則，建議您透過數種方式，根據記錄的嚴重性來自動處理記錄。
現場分析形式記錄
我們選擇將 ERROR 記錄項目視為有其需要修正的軟體錯誤的指標。我們可以放心假設，軟體作者會想知道其軟體會記錄本機環境以外的錯誤。因此，我們會計算按照來源元件執行個體細分的「錯誤」和「嚴重」記錄項目數量，透過 Cobalt 回報這些記錄項目，並將這些計數器視為現場穩定性指標來追蹤。
如要查看裝置上的記錄統計資料總覽，請使用下列指令：
cs --log-stats
元件統計資料 (cs) 提供記錄統計資料模式，可剖析 Archivist 的檢查樹狀結構，提供每個元件產生的記錄摘要檢視畫面。這個檢視畫面可讓工程師瞭解元件產生的記錄檔類型，以及相較於其他元件，產生各種記錄的頻率。
記錄為測試中的預期行為 (非預期行為)
放心假設軟體作者有興趣瞭解，當其軟體在測試期間設定的受控條件下記錄錯誤時，這屬於正常情況。因此，我們會在測試執行階段導入行為，如果在測試領域中觀察到非預期的 ERROR 記錄，測試會失敗。
上述的測試執行階段行為已經過實作、測試及記錄。
安全性考量
嚴重性達「FATAL」的記錄通常表示系統受到了系統中的一項核心不變，後續則可能導致資料損毀或安全漏洞。在此情況下，終止是最安全的行動。
元件架構可以安全地從元件層級識別記錄來源。在元件中，模組可能會進行自主測試，因此不可信任程度與元件層級識別相同。
隱私權考量
任何記錄分析都應避免揭露任何個人識別資訊 (PII)。例如，我們不應在使用者裝置端指標中公開使用者裝置上的完整元件組合，也不應在任何含有 PII 的記錄訊息中顯示完整文字。
說明文件
我們也打算將這些記錄指南發布為 Fuchsia 開發指南。
缺點、替代方案和未知
上述提議的變更建立了獎勵與不利誘因以特定方式記錄的系統。這麼做是為了從記錄檔中獲得更多值，您可以透過適當高嚴重性的方式查看重要的記錄項目，同時減少嚴重性過高的較不重要記錄項目數量。
我們考量這些獎勵激勵會造成不必要的行為的風險，例如完全避免 ERROR 記錄項目 (即使在有呼叫的條件下)。我們相信，打造更優質的軟體的動機將能促使開發人員做出負責任的決策，瞭解如何回應提議的變更。
我們會透過分析錯誤報告和不定期與團隊成員訪談，並在必要時完成結正，藉此監控開發人員的行為，以測試上述假設。
先前的圖片和參考資料
Google 測試網誌提供記錄層級的一些基本指南。