RFC-0003：Fuchsia 記錄指南

摘要

記錄功能廣泛用於 Fuchsia 程式碼，但記錄的訊息嚴重性不一致。這會降低記錄中資訊的價值。以下是不同記錄嚴重程度層級的語意意義，以及在不同環境中記錄特定嚴重程度的影響。

動機和問題陳述

記錄是傳送診斷信號的常見方式，可用於通知執行中軟體的內部狀態變更。這些資料可提供寶貴資訊，協助您偵測及修正軟體和產品的錯誤。

以往，記錄會包含自由文字訊息，以及列舉的嚴重性值。嚴重性值可指出訊息的重要性，並區分信號和雜訊。不過，Fuchsia 程式碼及其依附元件的嚴重性層級應用方式不一致，導致記錄難以在手動疑難排解和自動分析中使用。

我們希望透過提供常見的使用記錄嚴重性方式指南，以及建立與特定記錄使用方式相關的後果程序，創造良性循環，讓記錄產生更多診斷價值，同時改善信號雜訊比。舉例來說，我們希望「ERROR」記錄項目的頻率能成為系統穩定性的其中一個代理指標。

實作

記錄嚴重性等級

Fuchsia 支援多種標準記錄嚴重性等級：

嚴重

這表示發生無法復原的錯誤，且元件應在記錄訊息後立即自行終止。這通常表示系統中的核心不變量已遭到違反，如果繼續執行，可能會導致資料毀損或安全性漏洞。

請謹慎使用這個記錄層級。這個記錄層級可能表示需要修正的硬體問題或軟體錯誤。由於指定的訊息會是元件自行終止前記錄的最後一則訊息，因此其內容應會指出終止原因。

錯誤

這個記錄層級表示發生了非預期事件，但程式可以從中復原。如果記錄中出現「ERROR」記錄項目，表示程式行為不正確，需要進行修正。開發人員應盡力讓 Bug Tracker 中的錯誤與 ERROR 記錄項目之間保持一對一的對應關係。換句話說，每個獨特的錯誤都應有一個錯誤記錄項目，而每個錯誤記錄項目都應有個別的錯誤。開發人員應盡可能在程式碼中維持這項對應關係。請注意，錯誤可能不在發出記錄陳述式的程式碼中。錯誤可能發生在其中一個呼叫端或其依附元件。

這個記錄層級和更高層級會做為系統穩定性指標的信號。此外，這個記錄層級以上的記錄通常會出現在錯誤報告中。這則記錄訊息會供導入訊息的團隊以外的人員使用，因此應提供足夠的背景資訊，引導讀者找出問題的根本原因。

警告

這個記錄層級表示系統在正常運作期間發生非預期事件。這些意外事件可能與環境有關，因此不在系統本身的控制範圍內。舉例來說，網路連線中斷可能會記錄為「警告」，而導致程式無法繼續執行的無效輸入內容可能會記錄為「警告」。這個記錄層級可用於找出導致問題的根本原因 (通常是 ERROR 記錄項目)。這個記錄層級可用於強調，由於上述非預期事件，系統採用了非一般程式碼路徑。

資訊

這是錯誤報告中通常會出現的最低記錄檔級別。這表示程式中發生了值得注意的狀態變更。這個記錄層級會用來指出導致問題的背景資訊 (通常是 ERROR 記錄項目)。與較高記錄層級一樣，其他團隊會使用這些記錄進行診斷，因此提供背景資訊至關重要。

應使用元件檢查功能回報持續時間較長的狀態。如果這些條件沒有變更，則不應記錄。舉例來說，檢查資料可以包含標記「configs_found = false」，甚至「config_count = 0」，而非以固定間隔記錄「[INFO] no configs found」。

偵錯

這個記錄層級通常用於工程環境，例如在測試期間或在提交佇列機器人中重現問題時。嚴重性層級為 DEBUG 以下的記錄通常不會收集到錯誤報告中，因此請勿預期在錯誤報告中收到 DEBUG 以下的記錄。這個記錄層級通常比 INFO 更詳細，有助於個別團隊更瞭解他們正在開發的系統狀態。

TRACE

這個記錄層級通常會由個別團隊使用，也許會用於提交佇列和持續整合。這個記錄層級通常用來指出多階段程序中的某個階段已完成。

記錄的後果

我們已建立選擇記錄嚴重性等級的規範，並建議幾種方法，讓系統自動根據記錄嚴重性處理記錄。

記錄檔做為現場數據分析

我們選擇將出現 ERROR 記錄項目視為需要修正的軟體錯誤。我們可以合理推斷，軟體作者會想知道自己的軟體是否在本機環境之外記錄錯誤。因此，我們會計算出錯誤和嚴重記錄項目的存在情形，並按來源元件執行個體細分，透過 Cobalt 回報，並追蹤這些計數器做為現場穩定度指標。

如要查看裝置上的記錄統計資料總覽，請使用下列指令：

cs --log-stats

元件統計資料 (cs) 提供記錄統計資料模式，可剖析 Archivist 的檢查樹狀結構，提供每個元件產生的記錄摘要檢視畫面。這個檢視畫面可讓工程師查看元件產生的記錄類型，以及相對於其他元件產生各種記錄的頻率。

在測試期間記錄預期或非預期的行為

我們可以合理假設，如果軟體作者在測試期間設定受控條件，而軟體在這種情況下記錄錯誤，作者會對此感到興趣，因為這不是預期的行為。因此，我們會在測試執行階段中引入行為，如果在測試領域中觀察到非預期的錯誤記錄，就會導致測試失敗。

上述的測試執行階段行為已實作、測試及記錄。

安全性考量

• 以「FATAL」嚴重性記錄資料通常表示系統中的核心不變量已遭到違反，如果繼續執行，可能會導致資料毀損或安全性漏洞。在這種情況下，終止帳戶是最安全的做法。

• 元件架構可安全地將記錄來源識別為元件層級。在元件中，模組可能會進行自我認證，因此無法像元件層級的識別一樣受到信任。

隱私權考量

任何記錄分析都應避免揭露任何個人識別資訊 (PII)。舉例來說，我們不應在裝置外指標中公開使用者裝置上的完整元件組合，也不應揭露任何可能包含任何 PII 的記錄訊息完整文字。

說明文件

我們也打算將這些記錄規範發布為 Fuchsia 開發指南。

缺點、替代方案和未知事項

上述建議的變更可建立一套系統，針對特定登入方式提供獎勵和懲罰。目的是從記錄中獲得更多價值：為重要記錄項目指定適當的嚴重性，同時減少嚴重性過高的不重要記錄項目數量。

我們認為這些誘因可能會導致不必要的行為，例如完全避免產生 ERROR 記錄項目 (即使是在需要產生記錄項目的情況下)。我們相信，開發人員為了打造更優質的軟體，會在面對建議的異動時做出負責任的決策。

我們會透過分析錯誤報告和不定期與團隊成員進行訪談，監控開發人員的行為，並視需要調整上述假設。

既有技術與參考資料

Google 測試部落格提供一些關於記錄層級的基本指南。