日誌規範建設

一、日誌

1、日誌的作用

日誌記錄用戶操作、系統運行狀態，好的日誌系統可以幫助研發和運維：

• 掌握線上服務運行狀態；
• 快速定位線上問題；
• 發現系統瓶頸；
• 服務報警；
• 挖掘數據價值；
• ……

2、日誌級別

基本級別（由低到高）：

• DEBUG：The DEBUG Level designates fine-grained informational events that are most useful to debug an application.
• INFO：The INFO level designates informational messages that highlight the progress of the application at coarse-grained level.
• WARN：The WARN level designates potentially harmful situations.
• ERROR：The ERROR level designates error events that might still allow the application to continue running.
• FATAL：The FATAL level designates very severe error events that will presumably lead the application to abort.

二、日誌系統的約定

// servername/2019120917.debug.log
[2019-12-09 19:35:20.0920][server.go:52][DEBUG]traceid=TraceID|spanid=SpandID|K1=V1|K2=V2|....|CostTime=56ms
-----------時間戳--------------代碼--行數-日誌級別--TaceID--SpanID---KV……

1、日誌名字：同一個服務的每個級別日誌打印到對應的文件中，可以選擇按天/小時分割，示例如下：

• 2019120917.debug.log
• 2019120917.info.log
• 2019120917.warn.log
• 2019120917.error.log
• 2019120917.fatal.log

2、時間戳：日誌記錄產生的時間

• 日誌文件名大概定位日誌記錄產生時段；
• 每行日誌內時間字段需要十分精確：
  • 目前看再不規範的日誌系統最起碼都打了這個字段；

2、代碼文件及行數

• 定位問題、發現系統瓶頸等；

3、日誌級別

• 如果不同級別的日誌打印到不同文件中，這裏也可以不打印該字段；

4、TraceId & SpanId：traceid表示所屬的調用鏈，spanid表示本次rpc

• TraceId：全鏈路追蹤，貫穿整個調用鏈傳遞，從而可以通過traceid一次性取出所有相關日誌
  • 動作發起方生成 traceId，中間處理服務使用並記錄該 traceId；
  • 一個完整的請求在各服務處理的 traceId理論是同一個；
• SpanId：代表一次rpc調用（一次rpc調用的兩頭分別關聯了1個client和1個server），spanid生成規則體現了調用的層級與時序
  • 反正服務調用的層級和時序；
  • client端的span應該伴隨request的生成而生成，伴隨response的收到而釋放（寫到日誌中）；server端的span應該伴隨request的收到而生成，伴隨response的發出而釋放（寫到日誌中）;

5、annotation：日誌正文

• kv格式具有自解釋性，便於日誌採集、分析；
• 字段之間採用統一的分隔符；

6、耗時

• 總耗時、具體某一函數處理耗時；
• 對於client來說，要記錄request的發出時間和response的收到時間，之間的耗時相減可以得到；
• 對於server來說，要記錄request的收到時間和response的發出時間，之間的耗時相減可以得到；

7、其他注意事項

• 編碼：理論上日誌都是明文信息，應儘量避免二進制等其他格式的出現，在無法避免的情況下應該採用base64或者其他轉碼；
• IP、Port等信息如果需要也可以加上；

三、日誌系統的實現

1、封裝日誌庫 → 通信框架、應用層框架支持日誌庫 → 服務打印日誌

日誌系統的建設不是某一個服務做到就可以的，尤其在分佈系統環境、全鏈路問題跟蹤。

四、參考資料

1、Google論文（翻譯）：http://bigbully.github.io/Dapper-translation/

     Google論文（原文）：https://static.googleusercontent.com/media/research.google.com/zh-CN//archive/papers/dapper-2010-1.pdf

2、分佈式調用跟蹤系統調研：https://www.jianshu.com/p/e02972487e00