作者：frankiegao123
來源：http://t.cn/EVrUWJf

日誌在應用程式中是非常非常重要的，好的日誌信息能有助於我們在程序出現 BUG 時能快速進行定位，並能找出其中的原因。

但是，很多介紹 AOP 的地方都採用日誌來作為介紹，實際上日誌要採用切面的話是極其不科學的！對於日誌來說，只是在方法開始、結束、異常時輸出一些什麼，那是絕對不夠的，這樣的日誌對於日誌分析沒有任何意義。如果在方法的開始和結束整個日誌，那方法中呢？如果方法中沒有日誌的話，那就完全失去了日誌的意義！如果應用出現問題要查找由什麼原因造成的，也沒有什麼作用。這樣的日誌還不如不用！

希望藉以本文能讓應用程式的開發人員能更加重視日誌，能在應用中輸出有意義的日誌。

日誌基本格式

日誌輸出主要在文件中，應包括以下內容：

• 時間
• 日誌級別主要使用
• 調用鏈標識（可選）
• 線程名稱
• 日誌記錄器名稱
• 日誌內容
• 異常堆棧（不一定有）

11:44:44.827 WARN [93ef3E0120160803114444-1.2] [main] [ClassPathXmlApplicationContext] Exception encountered during context initialization - cancelling refresh attempt

日誌時間

作為日誌產生的日期和時間，這個數據非常重要，一般精確到毫秒。由於一般按天滾動日誌文件，日期不需要放在這個時間中，使用 HH:mm:ss.SSS 格式即可。

日誌級別

日誌級別主要使用 DEBUG、INFO、WARN、ERROR。

DEBUG

DEUBG 級別的主要輸出調試性質的內容，該級別日誌主要用於在開發、測試階段輸出。該級別的日誌應儘可能地詳盡，便於在開發、測試階段出現問題或者異常時，對其進行分析。

INFO

INFO 級別的主要輸出提示性質的內容，該級別日誌主要用於生產環境的日誌輸出。該級別或更高級別的日誌不要出現在循環中，可以在循環開始或者結束後輸出循環的次數，以及一些其他重要的數據。

• 應用啟動時所加載的配置參數值（比如：連接參數、線程池參數、超時時間等，以及一些與環境相關的配置，或者是整個配置參數）
• 一些重要的依賴注入對象的類名
• 方法（服務方法）的輸入參數值、返回值，由於一些方法入參的值非常多，只在入口處輸出一次就可以了，在服務方法內部或者調用非服務方法時就不需要再輸出了
• 方法中重要的部分，比如：從資料庫中所獲取較為重要的數據，以及調用第三方接口的輸入參數值和接口返回值

INFO 級別日誌原則是在生產環境中，通過 INFO 和更高級別的日誌，可以了解系統的運行狀況，以及出現問題或者異常時，能快速地對問題進行定位，還原當時調用的上下文數據，能重現問題。

建議在項目完成後，在測試環境將日誌級別調成 INFO，然後通過 INFO 級別的信息看看是否能了解這個應用的運用情況，如果出現問題後是否這些日誌能否提供有用的排查問題的信息。

WARN

WARN 級別的主要輸出警告性質的內容，這些內容是可以預知且是有規劃的，比如，某個方法入參為空或者該參數的值不滿足運行該方法的條件時。在 WARN 級別的時應輸出較為詳盡的信息，以便於事後對日誌進行分析，不要直接寫成：

不好的日誌

log.warn( "name is null" );

除了輸出警告的原因之外，還需要將其他參數內容都輸出，以便於有更多的信息供為日誌分析的參考。

推薦的日誌

log.warn( "[{}] name is null, ignore the method, arg0: {}, arg1: {}" , methodName , arg0 , arg1 );

ERROR

ERROR 級別主要針對於一些不可預知的信息，諸如：錯誤、異常等，比如，在 catch 塊中抓獲的網絡通信、資料庫連接等異常，若異常對系統的整個流程影響不大，可以使用 WARN 級別日誌輸出。在輸出 ERROR 級別的日誌時，儘量多地輸出方法入參數、方法執行過程中產生的對象等數據，在帶有錯誤、異常對象的數據時，需要將該對象一併輸出：

推薦的日誌

log.error( "Invoking com.service.UserService cause error, username: {}" , username , e );

不要寫成（下面這種會將 e 作為日誌內容參數中的一個，效果與使用 e.toString() 一致，不會輸出異常堆棧）：

不好的日誌

log.error( "Invoking com.service.UserService cause error, username: {}, e: {}" , username , e );

不要在日誌中輸出下面這樣的日誌，在異常堆棧 e 中本身就會輸出 e.getMessage 的內容，沒必要在日誌行中輸出一遍，這樣的日誌對於問題的追蹤毫無意義！

不好的日誌

log.error( e.getMessage() , e );

調用鏈標識

在分布式應用中，用戶的一個請求會調用若干個服務完成，這些服務可能還是嵌套調用的，因此完成一個請求的日誌並不在一個應用的日誌文件，而是分散在不同伺服器上不同應用節點的日誌文件中。該標識是為了串聯一個請求在整個系統中的調用日誌。

調用鏈標識格式：

• 唯一字符串（trace ID）
• 調用層級（span ID）

調用鏈標識作為可選項，無該數據時只輸出 [] 即可。

線程名稱

輸出該日誌的線程名稱，一般在一個應用中一個同步請求由同一線程完成，輸出線程名稱可以在各個請求產生的日誌中進行分類，便於分清當前請求上下文的日誌。

日誌記錄器名稱

日誌記錄器名稱一般使用類名，日誌文件中可以輸出簡單的類名即可，看實際情況是否需要使用包名。主要用於看到日誌後到哪個類中去找這個日誌輸出，便於定位問題所在。

日誌內容

注意事項

禁用 System.out.println

src/main 的代碼中嚴禁使用 System.out.println 進行輸出，因為生產環境一般不會將標準輸出和錯誤輸出重定向到文件中去，如果代碼中使用該方式輸出日誌，可能會導致該輸出丟失。

變參替換日誌拼接

使用 slf4j 的 Logger 進行處理，使用其變參功能進行日誌輸出，不要在日誌中進行字符串的拼接，比如：

推薦的日誌

log.debug( "Load No.{} object, {}" , i , object );

不要寫成 log.debug ( "Load No." + i + " object, " + object ); 這是因為將日誌級別調至 INFO 或以上級別時，這樣會增加無畏的字符串拼接。

實現 toString()

需要輸出日誌的對象，應在其類中實現快速的 toString 方法，以便於在日誌輸出時僅輸出這個對象類名和 hashCode。該 toString 方法應該處理類中所有的欄位。toString 方法可以通過 IDE 的自動功能 toString 功能生成。toString 方法建議不要通過反射或者一些 toString 工具類生成，也不要直接使用 JSON 序列化工具轉為 JSON 字符串，這兩者均使用反射進行處理的，僅為了輸出日誌較為影響應用的性能。

預防空指針

不要在日誌中調用對象的方法獲取值，除非確保該對象肯定不為 null，否則很有可能會因為日誌的問題而導致應用產生空指針異常。

不好的日誌

log.debug( "Load student(id={}), name: {}" , id , student.getName() );

可以改為（當 student 為 null 時，這樣也不會產生空指針異常）：

推薦的日誌

log.debug( "Load student(id={}), student: {}" , id , student );

對於一些一定需要進行拼接字符串，或者需要耗費時間、浪費內存才能產生的日誌內容作為日誌輸出時，應使用 log.isXxxxxEnable() 進行判斷後再進行拼接處理，比如：

推薦的代碼

if ( log.isDebugEnable() ) {
 StringBuilder builder = new StringBuilder();
 for ( Student student : students ) {
 builder.append( "student: " ).append( student );
 }
 builder.append( "value: " ).append( JSON.toJSONString(object) );
 log.debug( "debug log example, detail: {}" , builder );
}

信息安全

切記不要 log 密碼及個人信息相關的內容！為了便於進行問題定位，以下是涉及敏感信息日誌輸出時最為寬鬆（明文顯示的數據只能更少，不能更多）的要求：

上述僅列取出部分數據的顯示要求，其他的顯示原則為通過掩碼後的數據無法得知原始數據。

實現了如上掩碼的工具類，參考：https://github.com/frankiegao123/mask-utils

異常堆棧

異常堆棧一般會出現在 ERROR 或者 WARN 級別的日誌中，異常堆棧含有方法調用鏈的系統，以及異常產生的根源。異常堆棧的日誌屬於上一行日誌的，在日誌收集時需要將其劃至上一行中。

日誌文件

日誌文件放置於固定的目錄中，按照一定的模板進行命名，推薦的日誌文件名稱：

• 當前正在寫入的日誌文件名：<應用名>[-<功能名>].log
• 已經滾入歷史的日誌文件名：<應用名>[-<功能名>].log.

日誌配置

輸出

根據不同的環境配置不同的日誌輸出方式：

• 本地調試可以將日誌輸出到控制台上
• 測試環境或者生產環境輸出到文件中，每天產生一個文件，如果日誌量龐大可以每個小時產生一個日誌文件
• 生產環境中的文件輸出，可以考慮使用異步文件輸出，該種方式日誌並不會馬上刷新到文件中去，會產生日誌延時，在停止應用時可能會導致一些還在內存中的日誌未能及時刷新到文件中去而產生丟失，如果對於應用的要求並不是非常高的話，可暫不考慮異步日誌

logback 日誌工具可以在日誌文件滾動後將前一文件進行壓縮，以減少磁碟空間占用，若使用 logback 對於日誌量龐大的應用建議開啟該功能。