RFC-0003：Fuchsia 記錄指南

摘要

Logging 全面使用 Fuchsia 的程式碼，但記錄訊息的嚴重性不一致。這個 用於降低記錄檔中的資訊值。以下是建議的語意 各項記錄嚴重性等級的意義和記錄 特定程度的影響

動機與問題陳述

記錄檔是針對以下項目傳送診斷信號的最常見方式： 執行軟體的內部狀態他們提供有價值的資訊 用於偵測並修正軟體和產品中的錯誤。

記錄過去包含任意文字訊息，以及列舉的 嚴重性值。嚴重性值能指出 以便區分雜訊和雜訊不過應用程式 整個 Fuchsia 程式碼及其 導致記錄難以在手動 以及自動化分析和疑難排解

提供使用記錄嚴重性的通用指南，並藉由建立 會將結果附加在記錄檔的使用方法上，我們希望 建立良性循環，從記錄檔中產生更多診斷值 同時改善信號雜訊比舉例來說，我們希望 ERROR 記錄項目的頻率為對系統穩定性的其中一個 Proxy。

實作

記錄嚴重性等級

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

嚴重

這表示無法復原的錯誤，且元件應 記錄訊息後不久就會自行終止。這通常表示 違反系統的核心變體，並進一步行動 可能導致資料損毀或安全漏洞

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

錯誤

此記錄層級指出程式已發生不想要的事件。 並從中復原ERROR 記錄項目出現在記錄中，表示 需要修正的錯誤程式行為。開發人員應致力達成 錯誤追蹤程式中的錯誤與 ERROR 記錄中的錯誤之間存在一對一的關聯 項目。換句話說，每個不重複的錯誤都應有一個「ERROR」記錄項目。 每個 ERROR 記錄項目都會有個別的錯誤。開發人員 會盡可能在程式碼中維持這類通訊請注意， 錯誤可能不在發布記錄陳述式的程式碼中。錯誤可能位於以下其中一個項目： 或其中一個依附元件

此記錄等級以上將做為系統穩定性指標的信號。 此外，這個記錄層級和更高層級通常會顯示在錯誤報告中。 這個記錄訊息將供導入團隊以外的人員使用 因此應提供充分的背景資訊， 問題的根源

警告

這個記錄層級表示正常期間發生了未預期的事件 系統的作業。這些未預期的事件可能是環境， 因此不在系統本身控制的範圍內例如：網路遺失 連線可能會被記錄為 WARNING 或輸入無效，以阻止程式 繼續操作可能會記錄為 WARNING。這個記錄檔層級可用來 找出造成問題的根本原因 (通常是「錯誤」記錄項目)。這個 會為了取出不常見的程式碼路徑，將 執行上述非預期事件的結果

資訊

這通常是錯誤報告中顯示的最低記錄層級。這表示 值得注意的是程式發生了值得注意的狀態變更。這個記錄層級 用於指出引發問題的情境 (通常是 ERROR 記錄檔) 項目)。就像記錄層級較高一樣，這些記錄檔會由 而背景資料也很重要

如要回報長期狀態，則應使用 元件檢查。 這些條件沒有變更，就不應該記錄下來。例如： 而不是記錄「[INFO] no configs found」每隔一段時間，您的 可能包含旗標「configs_found = false」或甚至「config_count = 0」

偵錯

這個記錄層級通常用於工程環境，例如 進行測試，或在修訂佇列機器人重現問題時。嚴重性層級的記錄檔 低於 DEBUG 等級的錯誤報告通常不會收集到錯誤報告中，因此 而不是正常狀況。這個 記錄檔層級通常比 INFO 更完整，有助於個別團隊改善 瞭解開發系統的狀態

追蹤

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

記錄的後果

我們設有一套選擇記錄嚴重性等級的準則，我們建議 我們根據記錄嚴重性自動處理記錄檔

記錄內數據分析

我們選擇將出現「錯誤」記錄項目， 需要修正的軟體錯誤可以放心假設軟體的作者 建議您可以得知自家的軟體會記錄錯誤 本機環境。因此，我們會計算「錯誤」和「嚴重」的出現次數 按照來源元件執行個體細分的記錄項目，並透過 Cobalt 回報 並追蹤這些計數器，做為實地穩定性指標來追蹤。

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

cs --log-stats

元件統計資料 (cs) 提供的記錄統計資料模式，可剖析 Archivis 的檢查結果 樹狀結構，提供摘要檢視畫面，列出每個元件產生的記錄檔。這個檢視畫面 工程師可查看元件產生的記錄檔類型 產生各種記錄檔的頻率。

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

可以放心假設軟體作者想要知道 當軟體在測試期間設定的受控制條件下記錄錯誤， 避免出現這類行為因此我們會將行為 測試執行階段，也就是在發生非預期的 ERROR 記錄時，導致測試失敗 在測試領域內觀察到結果

上述的測試執行階段行為已實作、測試並 。

安全性考量

• 具有 FATAL 嚴重性的記錄通常代表 系統違反系統，如果進一步行動可能導致資料損毀， 安全漏洞。在這種情況下，終止是最安全的處置方式。

• 元件架構可以安全地識別元件的記錄檔來源 第二，自訂角色只能 套用至專案或機構在元件中，模組可能會經過自我認證，因此無法 信任與元件層級 ID 相同學位。

隱私權考量

任何記錄分析都應避免公開任何個人識別資訊 資訊 (PII)。舉例來說，我們不應公開完整的元件組合 透過使用者裝置取得的指標，或任何記錄訊息的完整文字資料 可能包含個人識別資訊

說明文件

我們計劃發布這些紀錄規範，做為 Fuchsia Development 的一份子 指南。

缺點、替代方案和未知

上述變更提案建立一套提供獎勵和權力的系統， 以某些方式登入。這麼做的目的是從記錄檔中取得更多價值，請注意 為重要記錄項目提供適當的高嚴重性 降低嚴重性過高的低重要性記錄項目數量。

我們認為這些獎勵可能會鼓吹不當行為，例如 避免完全避免 ERROR 記錄項目 (即使在呼叫該記錄項目的條件下)。 我們相信，只要有動力打造更優質的軟體，開發人員就會受到激勵 做出負責任的決策，決定他們如何對提議的變更做出回應。

我們將透過分析來監控開發人員行為，以測試上述假設 的錯誤報告、不定期與團隊成員訪談，以及答對 將物件的使用中版本還原為舊版 或依需要永久刪除封存版本

既有藝術品和參考資料

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