支付交易系統日誌設計最佳實踐

大家好，我是隱墨星辰，深耕境內 / 跨境支付架構設計十餘年。

曾經在多家頭部互聯網公司的多個核心項目組，都有發現一些工作多年的資深工程師打印的日誌也是亂七八糟的，無論對於監控還是排查問題都極爲困難，最後沒辦法只好安排重新改造日誌，費時又費力。所以聊聊這個話題。

本次主要講結構清晰的日誌在支付系統中的核心作用，設計日誌規範需要遵守的一些基本原則，以及接口摘要日誌、業務摘要日誌、詳細日誌、異常日誌等常用日誌設計的最佳實踐。

1. 什麼是日誌

寫過代碼的同學一定再熟悉不過。日誌本質就是一種系統記錄文件，用於存儲發生在操作系統、應用軟件、網絡和存儲設備上的事件，主要用於問題診斷、審計和監控。

比如 PIC 認證時，就會審覈日誌系統。

不過我們最常用的仍然是用於查問題和監控告警。

2. 日誌對於支付系統運行保障的重要性

日誌的重要性相信不必多說，沒有日誌，系統上線後出問題就等於抓瞎。

在支付系統中，日誌不僅用於記錄交易詳情和系統狀態，還起到監控和安全審計的作用。它們幫助我們實時監控系統的健康狀態，快速排查線上的問題。此外，在支付領域日誌對於交易驗證和法律合規性文檔記錄都是不可或缺的。

3. 日誌設計的常見誤區

很多工作多年的工程師根本沒有設計日誌的概念，更別說如何去設計良好的日誌，完全是想到哪就打印到哪。

比如過度記錄。記錄大量無用信息，導致重要信息難以識別。每操作幾步就打印一次。

比如格式混亂。沒有統一的日誌格式，監控系統無法按規則進行切分，給監控告警、日誌分析和問題定位帶來困難。

還有忽視隱私和安全。也不管什麼是敏感信息，是否要脫敏，直接 toJsonString()，增加數據泄露風險。比如卡號，身份證號，手機號等都屬於敏感信息，不能直接打印到日誌。

還有一個很常見的就是關鍵信息缺失。比如打印異常日誌，只打印堆棧信息，沒有關鍵的業務數據信息。

4. 設計清晰日誌規範的基本原則

根據這麼多年的實踐，設計一個清晰的日誌系統最少應遵循以下原則：

區分日誌種類：接口摘要日誌，業務摘要日誌，詳細日誌，異常日誌等各自有自己的側重點，要區分打印，不全部打印在一個日誌文件中。

結構化日誌：使用結構化數據格式記錄，便於機器解析。這個尤其對監控系統有用。

日誌分級：合理設置日誌級別（如 DEBUG、INFO、WARN、ERROR），便於過濾和搜索。

標準化字段：標準化常用字段（如時間戳、日誌級別、請求 ID 等），保持一致性。

上下文信息：確保日誌含有足夠的上下文信息，方便定位問題。尤其是詳細日誌，一定要打印上下文信息。

脫敏處理：對於敏感數據，如手機號、卡號等，進行適當的脫敏處理。

分佈式追蹤 ID：引入分佈式追蹤系統，爲跨服務的請求分配唯一的追蹤 ID。

5. 最佳實踐

首先我們要明白日誌是用來做什麼的。只是先弄明白做事的目的，我們才能更好把事情做對。

在我看來，日誌有兩個核心的作用：

1）監控，診斷系統或業務是否存在問題；

2）排查問題。

對於監控而言，我們需要知道幾個核心的數據：業務 / 接口的請求量、成功量、成功率、耗時，系統返回碼、業務返回碼，異常信息等。對於排查問題而言，我們需要有出入參、中間處理數據的上下文，報錯的上下文等。

接下來，基於上面的分析，我們就清楚我們應該有幾種日誌：

  1. 接口摘要日誌。監控接口的請求量、成功量、耗時、返回碼等。使用固定格式，需要打印：時間、接口名稱、結果（成功 / 失敗)、返回碼、耗時等基本信息就足夠。

  2. 業務摘要日誌。監控業務的請求量、成功量、核心業務信息、返回碼等。使用固定格式，需要打印：時間、業務類型、上一步狀態、當前狀態、返回碼、核心業務信息（不同業務有不同的核心業務信息，比如流入，就有支付金額 / 退款金額，卡品牌，卡 BIN 等)。

  3. 詳細日誌。用於排查問題，不用於監控。格式不固定。主要包括時間、接口、入參、出參，中間處理數據輸入，異常的堆棧信息等。

  4. 系統異常日誌。同時用於監控。格式固定。需要打印：時間、錯誤碼、錯誤信息、堆棧信息等。

補充一個典型的支付場景下的業務日誌格式如下：

文件名：payment.biz.digest.log

格式規範：

[時間, 分佈式追蹤 ID, 環境標, 壓測標, 站點標, 請求來源系統, 上游請求 ID, 上游支付 ID, 我方系統業務 ID],[交易類型, 交易幣種, 交易金額, 上一個狀態, 當前狀態],[渠道名, 收單國家, 髮卡行, 卡品牌, 風控參數],[我方標準返回碼, 我方標準返回碼描述, 渠道返回碼, 渠道返回碼描述]

日誌示例：

[2024-01-04 20:02:32.239,293242318382329329232,P,0,UK,payment,2024010401203223220001,2024010401203223220001,2024010401203223220003],[pay,USD,2392,INIT,PAYING],[WPG,US,CMB,VISA,2D],[-,-,-,-]

說明：上面的日誌使用 [] 進行了塊分隔，第一個 [] 裏面是基礎信息，第二個 [] 裏面是交易信息，第三個 [] 裏面是渠道信息，第四個 [] 裏面是返回碼信息。

使用 [] 切割的好處是，如果後面要加字段，可以找到對應的位置增加。不影響現有監控。比如我要加個卡 BIN，那就可以在風控參數後面加，不影響返回碼監控位置。

有幾點特別補充說明：

  1. 正常業務和系統異常需要拆分出來。NPE 就是系統異常，餘額不足就是一個預期內的業務場景，不要打印到異常文件中。

  2. 業務摘要信息需要根據業務不同，設計不同的業務摘要日誌格式。比如支付、流出提現的交易，路由、渠道諮詢等，監控訴求是不一樣的，所以需要單獨設計。拿路由舉例，需要監控哪些渠道分流了多少，命中了哪個規則等，必然不能直接使用支付、退款的業務摘要日誌格式。所以每出現一種新業務，就需要單獨設計一種業務日誌。

  3. 接口摘要日誌，不要打印出入參。因爲出入參有可能包含非常多數據，而接口我們只關注請求量、結果、耗時這些就夠了，如果想查出入參，就去詳細日誌裏面查。

  4. 系統異常日誌一定要有單獨的日誌文件。因爲正常的系統，絕大部分是業務上報錯，比如風控拒絕，而不應該有很多 NPE 等系統異常。我們需要監控異常日誌的行數或特定錯誤碼的頻率，比如每分鐘有 X 行或每分鐘有 Y 個特定錯誤碼就需要告警出來。

7. 結束語

一個良好設計的日誌系統可以爲監控、告警和問題排查提供強有力的支持，反之，對於線上問題簡直就是噩夢。

今天主要講了日誌格式規範的設計，對於 log4j 的配置什麼的，網上已經有很多公開資料，這裏不再贅述。另外，分佈式環境下面還有日誌轉存、查詢等，也是一個很龐大的體系。

深耕境內 / 跨境支付架構設計十餘年，歡迎關注並星標公衆號 “隱墨星辰”，和我一起深入解碼支付系統的方方面面。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/bRYahp0wgtpsrD1Y4IlvRw

猜你喜歡