RFC-0003:Fuchsia 記錄指南

RFC-0003:Fuchsia 記錄指南
狀態已接受
區域
  • 一般
說明

使用記錄嚴重性等級的最佳做法。在測試和現場指標中應用記錄嚴重性。

Gerrit 變更
作者
審查人員
提交日期 (年-月-日)2020-06-03
審查日期 (年-月-日)2020-06-11

摘要

記錄功能廣泛用於 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 測試部落格提供一些關於記錄層級的基本指南。