RFC-0003：Fuchsia 記錄指南

摘要

記錄廣泛用於整個 Fuchsia 的程式碼，但記錄的訊息嚴重程度不一致。這會降低記錄中資訊的價值。下文將針對不同記錄嚴重程度提出語意意義，並說明在各種環境中以特定嚴重程度記錄的影響。

動機和問題陳述

記錄是傳送診斷信號最常見的方式，可指出執行中軟體的內部狀態變化。這些資訊可用於偵測及修正軟體和產品中的錯誤。

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

我們希望透過提供記錄嚴重程度的通用指南，以及建立將後果附加至特定記錄使用方式的程序，創造良性循環，從記錄中產生更多診斷價值，同時提高訊號雜訊比。舉例來說，我們希望將 ERROR 記錄項目的頻率做為系統穩定性的其中一個指標。

實作

記錄嚴重性等級

Fuchsia 支援多個標準記錄嚴重程度：

FATAL

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

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

錯誤

這個記錄層級表示發生非預期的事件，但程式可以從中復原。記錄檔中出現 ERROR 記錄項目，表示程式行為不正確，需要修正。開發人員應盡量讓錯誤追蹤工具中的錯誤與 ERROR 記錄項目一一對應。換句話說，每個不重複的錯誤都應有 ERROR 記錄項目，且每個 ERROR 記錄項目都應有獨立的錯誤。開發人員應盡可能在程式碼中維持這種對應關係。請注意，錯誤可能不在發出記錄陳述式的程式碼中。錯誤可能位於其中一個呼叫端或其中一個依附元件。

這個記錄層級以上的記錄會做為系統穩定性指標的信號。此外，錯誤報告通常會包含這個記錄層級以上的記錄。這個記錄訊息會由團隊以外的人員使用，因此應提供足夠的脈絡，引導讀者找出問題的根本原因。

警告

這個記錄層級表示系統正常運作時發生非預期事件。這些意外事件可能是環境因素所致，因此系統本身無法控制。舉例來說，網路連線中斷可能會記錄為 WARNING，或是導致程式無法繼續執行的無效輸入內容可能會記錄為 WARNING。這個記錄層級可用於找出導致問題的根本原因 (通常是 ERROR 記錄項目)。這個記錄層級可突顯因上述非預期事件而採用的不常見程式碼路徑。

資訊

這通常是錯誤報告中最低的記錄檔層級。這表示程式中發生了值得注意的狀態變化。這個記錄層級會用來指出導致問題的環境 (通常是 ERROR 記錄項目)。與較高的記錄層級一樣，其他團隊會使用這些記錄進行診斷，因此脈絡非常重要。

應使用元件檢查回報長期狀態。如果這類條件沒有變更，就不應記錄。舉例來說，Inspect 資料可能包含「configs_found = false」或「config_count = 0」等旗標，而非以固定間隔記錄「[INFO] no configs found」。

偵錯

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

TRACE

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

記錄的影響

我們已建立選擇記錄嚴重性等級的指南，並提出幾種根據嚴重性自動處理記錄的方式。

記錄檔做為現場分析資料

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

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

cs --log-stats

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

記錄測試期間的 (非) 預期行為

軟體作者應該會想知道，軟體在測試期間於受控條件下記錄錯誤，但這種行為並非預期。因此，我們會在測試執行階段導入行為，如果測試領域內出現非預期的 ERROR 記錄，就會導致測試失敗。

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

安全性考量

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

• 元件架構可安全地識別記錄的來源，並精確到元件層級。在元件中，模組可能經過自我認證，因此信任程度無法與元件層級的識別資訊相同。

隱私權注意事項

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

說明文件

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

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

上述建議變更會建立獎勵和懲罰制度，鼓勵/阻止使用者以特定方式登入。目的是要從記錄檔中取得更多價值，方法是為重要記錄項目提供適當的高嚴重性，同時減少嚴重性過高的次要記錄項目數量。

我們認為這些獎勵可能會促使使用者做出不當行為，例如完全避免 ERROR 記錄項目 (即使在需要記錄的情況下)。我們相信，為了打造更優質的軟體，開發人員會根據提案的異動內容，做出負責任的決策。

我們會透過分析錯誤報告和偶爾與團隊成員進行訪談，監控開發人員的行為，藉此測試上述假設，並視需要修正課程。

既有技術和參考資料

Google 測試網誌提供記錄層級的基本指南。