在軟件工程和系統(tǒng)運(yùn)維中，日志系統(tǒng)的重要性不言而喻，尤其是在支付交易系統(tǒng)中，它對(duì)于監(jiān)控、故障排查和安全合規(guī)性起著至關(guān)重要的作用。本文將深入探討支付系統(tǒng)日志設(shè)計(jì)的最佳實(shí)踐，包括日志的核心作用、設(shè)計(jì)原則和常見(jiàn)誤區(qū)，以及如何構(gòu)建一個(gè)結(jié)構(gòu)清晰、易于監(jiān)控和問(wèn)題排查的日志系統(tǒng)。

曾經(jīng)在多家頭部互聯(lián)網(wǎng)公司的多個(gè)核心項(xiàng)目組，都有發(fā)現(xiàn)一些工作多年的資深工程師打印的日志也是亂七八糟的，無(wú)論對(duì)于監(jiān)控還是排查問(wèn)題都極為困難，最后沒(méi)辦法只好安排重新改造日志，費(fèi)時(shí)又費(fèi)力。所以聊聊這個(gè)話題。

本次主要講結(jié)構(gòu)清晰的日志在支付系統(tǒng)中的核心作用，設(shè)計(jì)日志規(guī)范需要遵守的一些基本原則，以及接口摘要日志、業(yè)務(wù)摘要日志、詳細(xì)日志、異常日志等常用日志設(shè)計(jì)的最佳實(shí)踐。

一、什么是日志

寫過(guò)代碼的同學(xué)一定再熟悉不過(guò)。日志本質(zhì)就是一種系統(tǒng)記錄文件，用于存儲(chǔ)發(fā)生在操作系統(tǒng)、應(yīng)用軟件、網(wǎng)絡(luò)和存儲(chǔ)設(shè)備上的事件，主要用于問(wèn)題診斷、審計(jì)和監(jiān)控。

比如PIC認(rèn)證時(shí)，就會(huì)審核日志系統(tǒng)。

不過(guò)我們最常用的仍然是用于查問(wèn)題和監(jiān)控告警。

二、日志對(duì)于支付系統(tǒng)運(yùn)行保障的重要性

日志的重要性相信不必多說(shuō)，沒(méi)有日志，系統(tǒng)上線后出問(wèn)題就等于抓瞎。

在支付系統(tǒng)中，日志不僅用于記錄交易詳情和系統(tǒng)狀態(tài)，還起到監(jiān)控和安全審計(jì)的作用。它們幫助我們實(shí)時(shí)監(jiān)控系統(tǒng)的健康狀態(tài)，快速排查線上的問(wèn)題。此外，在支付領(lǐng)域日志對(duì)于交易驗(yàn)證和法律合規(guī)性文檔記錄都是不可或缺的。

三、日志設(shè)計(jì)的常見(jiàn)誤區(qū)

很多工作多年的工程師根本沒(méi)有設(shè)計(jì)日志的概念，更別說(shuō)如何去設(shè)計(jì)良好的日志，完全是想到哪就打印到哪。

比如過(guò)度記錄。記錄大量無(wú)用信息，導(dǎo)致重要信息難以識(shí)別。每操作幾步就打印一次。

比如格式混亂。沒(méi)有統(tǒng)一的日志格式，監(jiān)控系統(tǒng)無(wú)法按規(guī)則進(jìn)行切分，給監(jiān)控告警、日志分析和問(wèn)題定位帶來(lái)困難。

還有忽視隱私和安全。也不管什么是敏感信息，是否要脫敏，直接toJsonString()，增加數(shù)據(jù)泄露風(fēng)險(xiǎn)。比如卡號(hào)，身份證號(hào)，手機(jī)號(hào)等都屬于敏感信息，不能直接打印到日志。

還有一個(gè)很常見(jiàn)的就是關(guān)鍵信息缺失。比如打印異常日志，只打印堆棧信息，沒(méi)有關(guān)鍵的業(yè)務(wù)數(shù)據(jù)信息。

四、設(shè)計(jì)清晰日志規(guī)范的基本原則

根據(jù)這么多年的實(shí)踐，設(shè)計(jì)一個(gè)清晰的日志系統(tǒng)最少應(yīng)遵循以下原則：

• 區(qū)分日志種類：接口摘要日志，業(yè)務(wù)摘要日志，詳細(xì)日志，異常日志等各自有自己的側(cè)重點(diǎn)，要區(qū)分打印，不全部打印在一個(gè)日志文件中。
• 結(jié)構(gòu)化日志：使用結(jié)構(gòu)化數(shù)據(jù)格式記錄，便于機(jī)器解析。這個(gè)尤其對(duì)監(jiān)控系統(tǒng)有用。
• 日志分級(jí)：合理設(shè)置日志級(jí)別（如DEBUG、INFO、WARN、ERROR），便于過(guò)濾和搜索。
• 標(biāo)準(zhǔn)化字段：標(biāo)準(zhǔn)化常用字段（如時(shí)間戳、日志級(jí)別、請(qǐng)求ID等），保持一致性。
• 上下文信息：確保日志含有足夠的上下文信息，方便定位問(wèn)題。尤其是詳細(xì)日志，一定要打印上下文信息。
• 脫敏處理：對(duì)于敏感數(shù)據(jù)，如手機(jī)號(hào)、卡號(hào)等，進(jìn)行適當(dāng)?shù)拿撁籼幚怼?/li>
• 分布式追蹤ID：引入分布式追蹤系統(tǒng)，為跨服務(wù)的請(qǐng)求分配唯一的追蹤ID。

五、最佳實(shí)踐

首先我們要明白日志是用來(lái)做什么的。只是先弄明白做事的目的，我們才能更好把事情做對(duì)。

在我看來(lái)，日志有兩個(gè)核心的作用：

1）監(jiān)控，診斷系統(tǒng)或業(yè)務(wù)是否存在問(wèn)題；

2）排查問(wèn)題。

對(duì)于監(jiān)控而言，我們需要知道幾個(gè)核心的數(shù)據(jù)：業(yè)務(wù)/接口的請(qǐng)求量、成功量、成功率、耗時(shí)，系統(tǒng)返回碼、業(yè)務(wù)返回碼，異常信息等。

對(duì)于排查問(wèn)題而言，我們需要有出入?yún)ⅰ⒅虚g處理數(shù)據(jù)的上下文，報(bào)錯(cuò)的上下文等。

接下來(lái)，基于上面的分析，我們就清楚我們應(yīng)該有幾種日志：

• 接口摘要日志。監(jiān)控接口的請(qǐng)求量、成功量、耗時(shí)、返回碼等。使用固定格式，需要打?。簳r(shí)間、接口名稱、結(jié)果（成功/失敗)、返回碼、耗時(shí)等基本信息就足夠。
• 業(yè)務(wù)摘要日志。監(jiān)控業(yè)務(wù)的請(qǐng)求量、成功量、核心業(yè)務(wù)信息、返回碼等。使用固定格式，需要打?。簳r(shí)間、業(yè)務(wù)類型、上一步狀態(tài)、當(dāng)前狀態(tài)、返回碼、核心業(yè)務(wù)信息（不同業(yè)務(wù)有不同的核心業(yè)務(wù)信息，比如流入，就有支付金額/退款金額，卡品牌，卡BIN等)。
• 詳細(xì)日志。用于排查問(wèn)題，不用于監(jiān)控。格式不固定。主要包括時(shí)間、接口、入?yún)?、出參，中間處理數(shù)據(jù)輸入，異常的堆棧信息等。
• 系統(tǒng)異常日志。同時(shí)用于監(jiān)控。格式固定。需要打?。簳r(shí)間、錯(cuò)誤碼、錯(cuò)誤信息、堆棧信息等。

補(bǔ)充一個(gè)典型的支付場(chǎng)景下的業(yè)務(wù)日志格式如下：

文件名：payment.biz.digest.log

格式規(guī)范：

[時(shí)間,分布式追蹤ID,環(huán)境標(biāo),壓測(cè)標(biāo),站點(diǎn)標(biāo),請(qǐng)求來(lái)源系統(tǒng),上游請(qǐng)求ID,上游支付ID,我方系統(tǒng)業(yè)務(wù)ID],[交易類型,交易幣種,交易金額,上一個(gè)狀態(tài),當(dāng)前狀態(tài)],[渠道名,收單國(guó)家,發(fā)卡行,卡品牌,風(fēng)控參數(shù)],[我方標(biāo)準(zhǔn)返回碼,我方標(biāo)準(zhǔn)返回碼描述,渠道返回碼,渠道返回碼描述]

日志示例：

[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],[-,-,-,-]

說(shuō)明：上面的日志使用[]進(jìn)行了塊分隔，第一個(gè)[]里面是基礎(chǔ)信息，第二個(gè)[]里面是交易信息，第三個(gè)[]里面是渠道信息，第四個(gè)[]里面是返回碼信息。

使用[]切割的好處是，如果后面要加字段，可以找到對(duì)應(yīng)的位置增加。不影響現(xiàn)有監(jiān)控。比如我要加個(gè)卡BIN，那就可以在風(fēng)控參數(shù)后面加，不影響返回碼監(jiān)控位置。

有幾點(diǎn)特別補(bǔ)充說(shuō)明：

1. 正常業(yè)務(wù)和系統(tǒng)異常需要拆分出來(lái)。NPE就是系統(tǒng)異常，余額不足就是一個(gè)預(yù)期內(nèi)的業(yè)務(wù)場(chǎng)景，不要打印到異常文件中。
2. 業(yè)務(wù)摘要信息需要根據(jù)業(yè)務(wù)不同，設(shè)計(jì)不同的業(yè)務(wù)摘要日志格式。比如支付、流出提現(xiàn)的交易，路由、渠道咨詢等，監(jiān)控訴求是不一樣的，所以需要單獨(dú)設(shè)計(jì)。拿路由舉例，需要監(jiān)控哪些渠道分流了多少，命中了哪個(gè)規(guī)則等，必然不能直接使用支付、退款的業(yè)務(wù)摘要日志格式。所以每出現(xiàn)一種新業(yè)務(wù)，就需要單獨(dú)設(shè)計(jì)一種業(yè)務(wù)日志。
3. 接口摘要日志，不要打印出入?yún)?。因?yàn)槌鋈雲(yún)⒂锌赡馨浅６鄶?shù)據(jù)，而接口我們只關(guān)注請(qǐng)求量、結(jié)果、耗時(shí)這些就夠了，如果想查出入?yún)?，就去詳?xì)日志里面查。
4. 系統(tǒng)異常日志一定要有單獨(dú)的日志文件。因?yàn)檎５南到y(tǒng)，絕大部分是業(yè)務(wù)上報(bào)錯(cuò)，比如風(fēng)控拒絕，而不應(yīng)該有很多NPE等系統(tǒng)異常。我們需要監(jiān)控異常日志的行數(shù)或特定錯(cuò)誤碼的頻率，比如每分鐘有X行或每分鐘有Y個(gè)特定錯(cuò)誤碼就需要告警出來(lái)。

六、結(jié)束語(yǔ)

一個(gè)良好設(shè)計(jì)的日志系統(tǒng)可以為監(jiān)控、告警和問(wèn)題排查提供強(qiáng)有力的支持，反之，對(duì)于線上問(wèn)題簡(jiǎn)直就是噩夢(mèng)。

今天主要講了日志格式規(guī)范的設(shè)計(jì)，對(duì)于log4j的配置什么的，網(wǎng)上已經(jīng)有很多公開資料，這里不再贅述。另外，分布式環(huán)境下面還有日志轉(zhuǎn)存、查詢等，也是一個(gè)很龐大的體系。

內(nèi)容已收錄到《圖解支付系統(tǒng)設(shè)計(jì)與實(shí)現(xiàn)》。