開發(fā)者必知的日志記錄最佳實(shí)踐

當(dāng)前位置：點(diǎn)晴教程→知識管理交流 →『技術(shù)文檔交流』

freeflydom

2025年3月10日 9:43 本文熱度 738

??對程序來說，良好的日志風(fēng)格能夠極大的降低排錯的成本，增強(qiáng)程序的健壯性與可運(yùn)維性，但大多數(shù)開發(fā)同學(xué)并沒有將日志的重要性提的和代碼本身一樣高，本文討論我個人記錄日志的一些最佳實(shí)踐

基本原則

將日志作為程序的第二個UI

??軟件的第一UI當(dāng)然是使用方或API調(diào)用方，而日志作為第二UI，用于開發(fā)、運(yùn)維、合作方進(jìn)行線上應(yīng)用狀態(tài)的檢測與問題排查。日志的質(zhì)量是代碼質(zhì)量的一部分。

寫日志時(shí)，考慮看日志的人無法訪問代碼

??通常來說，看日志的角色不僅僅是開發(fā)代碼的人員，包括線上值班人員、售后人員、其他合作方系統(tǒng)的人員，可能都需要依賴日志排查問題。今天的IT系統(tǒng)日志更容易收集后中心化，使得不同角色可以更容易訪問日志。對于API，尤其是涉及其他多個子系統(tǒng)調(diào)用的復(fù)雜API，良好的日志可以為調(diào)用方、線上值班提供豐富的問題排查依據(jù)，在代碼中打印日志時(shí)要考慮無法訪問代碼的角色。

日志的主要用戶是Human，次要用戶是機(jī)器，所以可讀性很重要

??可讀性包含的內(nèi)容很多，下面會解釋一些原則，但最基本的原則是縮進(jìn)、空格等需要讓閱讀者易于閱讀。同時(shí)日志格式也保證易于模式化解析（簡單的字符串匹配，而不是復(fù)雜的正則）

考慮日志的目的是什么

??日志的目的不僅僅是線上Debug，也可以是記錄性能或是收集后做數(shù)據(jù)分析，考慮日志在系統(tǒng)的目的，寫日志時(shí)具備一定針對性。

最佳實(shí)踐

為日志添加上下文

??非常General的日志是非常糟糕的，不僅無助于定位問題，更容易造成混淆。比如下面這個日志：

2021-11-30 16:44:52,725 [WARN] Connection failed!

無法定位是哪段代碼，連接什么失敗，也不知道失敗的參數(shù)是什么，更好的日志格式如下：

2021-11-30 16:44:52,725 [WARN][C97E2488-170A-4D01-8B90-BE562FD78342] Connection to XXX Service failed with message [msg=xxx, param1=xxx, param2=xxx]

類似問題還比如:

//don't do that
java.lang.IndexOutOfBoundsException
//do that
IndexOutOfBoundsException: index 25 is greater than list size 20.

對于日志，盡量避免太general的日志，記得我們的原則，知道我們的第二個UI的目標(biāo)受眾是誰，看日志的人大多數(shù)可能無法訪問代碼。

端到端的日志&并發(fā)線程日志問題

每個請求都需要有一個唯一標(biāo)識符與之對應(yīng)，通常是一個GUID，主要用于兩個用途

1.在不同系統(tǒng)或微服務(wù)間唯一標(biāo)識一個請求

2.同一個應(yīng)用內(nèi)不同并發(fā)線程唯一標(biāo)識一個請求

比如我們可以通過下面一個GUID追蹤的一個請求完整的過程

careyson@CareySonMac log % grep "C97E2488-170A-4D01-8B90-BE562FD78342" xxx.log
2021-11-30 16:44:52,725 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] XXX Start
2021-11-30 16:44:53,009 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Begin Instance Rule Check [source version=, target version=]
2021-11-30 16:44:53,010 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] rule check passed. [source version=, target version=]
2021-11-30 16:44:53,011 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Starting check  config
2021-11-30 16:44:53,078 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Check  config Complete
2021-11-30 16:44:53,079 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Starting get Source Custins info
.....

變量值與常量值分開

將變量值與常量值分開可以使得日志更容易閱讀，無論在代碼還是日志本身的搜索也會變的簡單，如果用工具抽取參數(shù)值也變的簡單，下面是一個示例:

// don't do that
ClientAgent.makeRequest()
log.info("Made request to {} on our application.", url)
 
// do that
ClientAgent.makeRequest()
log.info("Made request to XXX Service. [url={}]", url)

如果URL是一個很長的串，那么閱讀的體驗(yàn)將會非常糟糕。

區(qū)分Warn與Error

日志按照嚴(yán)重性同樣也會分級，業(yè)界標(biāo)準(zhǔn)使用最多的還是Info、Warn與Error。Info通常沒什么說的，程序符合預(yù)期正常工作，在過程中記錄相關(guān)信息，就是Info，Warn和Error值得提一下。

Warn意味著程序正常工作，但存在一些問題，這種問題通常在我們預(yù)期之內(nèi)。

Error意味著程序異常，且這種異常不在我們預(yù)期內(nèi)。

下面是一個程序中調(diào)用其他服務(wù)的簡單例子：

try{
    ClientAgent.makeRequest()
    log.info("Made request to XXX Service. [url={}]",url)
}catch(e:RDSException){
    log.warn("Request to XXX Service was rejected because parameter beyond some business boundary [url={}, param={}, result={}]",url,result)
}catch(e:Exception){
    log.error("Request to XXX Service failed. [url={}, exception={}]",url,exception)
}

如果可能，出錯時(shí)附上KB或錯誤代號

寫程序的人通常對程序所代表的業(yè)務(wù)有一定了解，但其他日志用戶可能并沒有背景知識以及業(yè)務(wù)限制，在有限的日志中通常很難說清楚，如果有對應(yīng)KB或幫助文檔，以及錯誤代號，可以附在日志中，幫助日志用戶快速了解背景。比如下面這個例子：

log.error("some error C5D1 happend due to bussiness limit, for more information, please see https://help.aliyun.com/product/26090.html")

避免記錄敏感信息

??日志并不會像數(shù)據(jù)庫那樣有高安全等級，也就是訪問日志的安全權(quán)限通常遠(yuǎn)遠(yuǎn)低于其他應(yīng)用，且今天的日志更多是上傳后中心化，更無法控制日志的擴(kuò)散范圍，因此對于敏感信息請不要記錄，包括密碼信息、Security Token信息、敏感身份信息等。

使用英文記錄日志

??英文記錄不僅僅是標(biāo)準(zhǔn)化和易于閱讀的問題，而是今天的IT系統(tǒng)，日志可能經(jīng)過多個系統(tǒng)中心化，這些系統(tǒng)只要有一個不支持UTF格式，就可能導(dǎo)致亂碼，使用英文可以盡量避免這些麻煩。

小結(jié)

??對于程序來說，代碼質(zhì)量除了代碼本身，還包括日志。將日志當(dāng)做程序的第二UI認(rèn)真對待，不僅能使得我們的程序調(diào)試與開發(fā)成本大幅下降，還能使得程序的運(yùn)維排錯更加簡潔，Bug更早發(fā)現(xiàn)。

?轉(zhuǎn)自https://www.cnblogs.com/CareySon/p/18757020/Logging_best_practice_for_developer

該文章在 2025/3/10 9:43:32 編輯過

關(guān)鍵字查詢

開發(fā)

日志

記錄

相關(guān)文章

正在查詢...

點(diǎn)晴ERP是一款針對中小制造業(yè)的專業(yè)生產(chǎn)管理軟件系統(tǒng),系統(tǒng)成熟度和易用性得到了國內(nèi)大量中小企業(yè)的青睞。

點(diǎn)晴PMS碼頭管理系統(tǒng)主要針對港口碼頭集裝箱與散貨日常運(yùn)作、調(diào)度、堆場、車隊(duì)、財(cái)務(wù)費(fèi)用、相關(guān)報(bào)表等業(yè)務(wù)管理，結(jié)合碼頭的業(yè)務(wù)特點(diǎn)，圍繞調(diào)度、堆場作業(yè)而開發(fā)的。集技術(shù)的先進(jìn)性、管理的有效性于一體，是物流碼頭及其他港口類企業(yè)的高效ERP管理信息系統(tǒng)。

點(diǎn)晴WMS倉儲管理系統(tǒng)提供了貨物產(chǎn)品管理,銷售管理,采購管理,倉儲管理,倉庫管理,保質(zhì)期管理,貨位管理,庫位管理,生產(chǎn)管理,WMS管理系統(tǒng),標(biāo)簽打印,條形碼,二維碼管理,批號管理軟件。

點(diǎn)晴免費(fèi)OA是一款軟件和通用服務(wù)都免費(fèi)，不限功能、不限時(shí)間、不限用戶的免費(fèi)OA協(xié)同辦公管理系統(tǒng)。

超碰人人人人人,亚洲AV午夜福利精品一区二区,亚洲欧美综合区丁香五月1区,日韩欧美亚洲系列