作者陈俊·2022-07-25 09:42

软件架构设计师·某银行信用卡中心

应用系统日志打印规范实践之道

字数 4966阅读 2247评论 0赞 2

如果你是一名优秀的应用系统开发人员，想必应该非常清楚在应用系统运行期间，打印日志有多么重要。它不但能够记录应用系统运行情况及轨迹 ，还有助于提升故障排查及定位问题的效率，甚至还可以对其进行分析及监控， 洞察系统隐患，提前预警防范。

但并不是说只要打印尽可能多的日志，就能轻松获得这些能力。设想一下，如果你肆无忌惮地打印了一堆毫无价值的日志，那请问日志又何以能够来为你提供价值呢。由此可见，这里的 核心关键点并不在于日志的多少，而在于日志打印是否规范且合理 。

不规范合理的日志，不但无法发挥作用产生价值，还会增加故障定位难度、降低解决效率，以及额外增加日志存储成本，消耗应用系统性能。在极端情况下，甚至还会对应用系统造成致命性打击，引发应用系统瘫痪的可能。

讲到这，我想你应该明白我想说的—— 应用系统日志打印确实非常重要，但日志打印规范将更为重要，它就像一把双刃剑，只有合理运用才能发挥其特有的作用及价值。  但在组织中，如果你想让你周围的人都能明白这个道理可并不容易，它需要一个漫长的传播过程，而在这个过程中， 你不仅需要坚持不断地宣导来逐步增强他们的认知，还应借助必要的治理手段及工具平台进行辅助，只有利其所器，才能善其所事。

- - -

**利器一：规范先行**

在你想启动规范化日志打印前，建议先制定一份日志打印规范，它可能无法面面俱到，但没有关系， 它的目的仅是为了先突显日志打印规范的重要性，并且让这件事情能够正式进入正轨 。  如果组织中大部分都是Java应用，那么规范内容可以主要围绕Java应用来写，虽然无法覆盖所有开发语言，但其核心原则仍是可以借鉴的。另外，前期请务必不要将其复杂化 ，否则它将无法具备普适性，也无法被接受和传播。

**Java应用系统日志打印规范**

**Java日志框架：** 
常用的Java日志框架可选择Log4j/Logback/Log4j2等，但为了避免后续更换日志框架所带来的额外改造成本，建议将接口层和实现层进行分离， 将SLF4J作为接口层，将Log4j/Logback/Log4j2作为实现层，两者通过桥接的方式进行集成。

**Java日志规范：**

**规范一：** 【强制】级别只允许使用ERROR、WARN、INFO、DEBUG，定义如下：

|   |   |
| ------------ | ------------ |
| 级别 | 定义 |
| ERROR | 表示应用系统出现异常或故障，需要预警并及时解决，否则该功能将无法正常运行并提供服务能力。 |
| WARN | 表示应用系统出现不符合预期的现象，但服务并未受损，可根据实际情况选择性预警，解决时效要求不高，但需要额外关注。 |
| INFO | 表示用于记录系统运行过程或重要信息点，主要为故障定位、过程追溯、数据分析等提供辅助能力。 |
| DEBUG | 表示用于在测试或本地的非生产环境中使用，主要为了方便开发调试程序，而在生产环境中禁止使用。 |
**规范二：** 【强制】禁止使用 Logback/Log4j2 等的API，应使用SLF4J的API。   
**规范三：** 【强制】在 接口/ 方法的 入口/出口处， 打印 请求及 响应参数 日志 。   
**规范四：** 【强制】ERROR级别日志需打印堆栈，而非ERROR级别日志则不需要。 
**规范五：** 【强制】禁止在代码循环体中直接打印非DEBUG级别的日志。 
**规范六：** 【强制】禁止日志打印内容中仅打印特殊字符或数字的情况。 
**规范七：** 【建议】日志内容中应包含关键特征类信息，例如： 用户标识或流水号。 
**规范八：** 【建议】应采用异步打印模式，且打印时建议关闭打印位置信息。   
**规范九：** 【建议】日志打印若出现堵塞，建议至少丢弃INFO级别以上的日志。 
**规范十：** 【建议】每条日志在语义上可独立被理解，减少上下文关联理解。   
**Java日志字段：**

![](/home/attachment/202207/25/1210879_165871274361533.png)

**注：** 位置信息包括类(class)/文件(file)/行号(line)/方法(method)，若打印位置信息，则对性能有所影响。

**以上仅是一些规范参考，你可以根据组织中的实际情况来进行调整，** **但规** **范仅仅只是规范，有了它并不代表你已达成目标** **，只能说明你已为日志打印规范化这件事，迈出了第一步。**

**利器二：服务至上**

当制定完应用系统日志打印规范后， **请不要幻想有任何人会来自觉地遵守它** ，一是不知它的存在，二是他们无从下手，三是大家都挺“忙”的。我把它总结为 六字真言，分别是 **“不知”、“不会”、“不想”** 。

我曾见过组织中的有些规范，特别是技术规范，在制定完成后就会被长久地封存起来，没有人知道，也没有人想知道。所以， 要 落实好规范， 你还得构思一套战术才行。否则，那些无法落实的规范就和废纸毫无两样。

在很多人眼里，可能会将规范视为是一种约束，而又错误地将约束理解为贬义词，从而避而远之。这种误解的发生，其原因并不出在他们本身，而更多的出在那些制定规范的人身上。

有些规范制定者不但没有身在其中，甚至也没有去诠释规范所能带来的价值，而仅仅只是强行推行 那份冷冰冰的规范，请问此时谁会乐意在不知其所以然的情况下，无缘无故地背上这沉重的“负担”。

因此， **你** **必须得为这份规范赋予更多的“温度”，而主动服务可能会是一种比较好的“升温”方式** 。 但在行动前，切忌 不要站在他们的对立面 ，并请做好放低姿态的觉悟，你要让对方深刻的意识到你和他们是同一阵营的。

在发布规范后的初期，你可以尝试挑选几个日志打印情况最为糟糕的应用系统，扮演为“VIP私人助理”来与对方进一步传达规范内容及作用，并为他们逐一列举出当前存在的日志打印问题，以及这些问题会对系统造成哪些影响。

这种方式不但能够避免仅用文字传达所产生的理解偏差，及时有效地为对方 解答各种疑问，使他们能够更深一步地理解规范内容及作用，还能够让规范制定者 更进一步地了解对方的顾虑及困难， 并从同理心视角出发，为对方提供更好的建议及解决思路。

就这样 5个、10个、15个应用系统... ...在精力有限的前提下 逐步扩大辐射范围， 事实证明， 这种主动服务+循序渐进的方式对 提升规范的接受度将会有所帮助。 不过在过程中 **你仍然需要不断回看规范的合理性及适用性，并对规范作出**及时且有效的**调整** 。

- - -

**利器三：度量为王**

当规范逐渐被更多的人接受后，你的使命并没有完成，而真正的考验才刚刚开始。 一是接受并不代表整改，二是如何验证整改有效性 ，三是整改是否可持续性。如果这些问题都不在你的考虑范围内，那你可能会前功尽弃。

若想要解决以上这些问题 ，借助度量 或许 会是一个不错的选择 。管理大师德鲁克曾说过： **“没有度量，就没有管理”** ，它同样适用于规范的落实工作，你可以根据日志打印规范来制定一些度量指标，并配套研发相应的度量工具平台。

通过度量工具平台 “ 可视化”和“自助化”的 两种特性，让开发人员能够及时发现 日志打印规范的问题，还能够让他们自主验证日志打印规范整改后的效果， **从而让他们感受到一种“看得见”+“摸得着”的安全感** 。

其中，度量指标的设计将会尤其重要， **往往一个不合理的指标，会让整个事情朝着预想中的反方向发展** 。所以，在初期并不建议你设计过多的度量指标，并建议 从度量难度、影响程度、达成难度、可解释性四个方面进行综合性评估，以确定较为合理的指标。

如下是当时初期选择的8个指标 。

|   |   |
| ------------ | ------------ |
| 类别 | 指标 |
| 级别 | ERROR级别日志条数 |
| 级别 | WARN级别日志条数 |
| 级别 | ERROR级别日志占比 |
| 级别 | WARN级别日志占比 |
| 堆栈 | ERROR级别日志无堆栈条数 |
| 堆栈 | 非ERROR级别日志堆栈条数 |
| 堆栈 | ERROR级别日志无堆栈占比 |
| 堆栈 | 非ERROR级别日志堆栈占比 |

**注：** 以上仅列出指标，指标要求建议你可根据实际情况进行动态调整，但过高的指标要求会变得毫无意义。

可能会有人提出，对于规模较大且日志条数较多的应用系统，是否可放宽指标要求，这听上去好像蛮有道理的，但我却并不这么认为。 **规模越大意味着所承载的职责和能力也就越大，一旦发生故障影响面也就越大，所以反倒更应该达到指标要求** 。

这些指标虽然有一定的指导性，但似乎并不能满足开发人员的“胃口”，因为这些指标仍然无法直接暴露问题根源，也无法让他们可快速定位及明确优化方向。因此，你还得赋予指标一定的分析能力。

例如：订单系统单日ERROR级别日志888条（占日志总量0.05%），（TOP1）90%在com.OrderService的第88行。（TOP2）10%在com.PayService的第188行。

就这样，你可以逐步完善指标体系及配套的分析能力，但请在设计每一个指标时，遵循先进行系统现状摸排，再进行小范围试点运行，最后进行持续观测并调优，从而确保每一个指标的设计都具备一定的合理性和可解释性。

如下列出了 一些 指 标 ，仅供参考。

|   |   |
| ------------ | ------------ |
| 指标分类 | 指标（不达标说明） |
| 冗余 | 单笔事务日志中出现重复日志（重合度=100%且>1条） |
| 冗余 | 单笔事务日志中出现相似日志（重合度>80%且>5条） |
| 冗余 | 单日日志中出现重复日志（重合度=100%且占总量>1%） |
| ...... | ...... |
| 语义 | 单条日志中出现特殊符号（特殊符号占比=100%） |
| 语义 | 单条日志中出现特殊符号+数字（特殊符号+数字占比>80%） |
| 语义 | 单条日志中出现无法识别单词（无法识别单词占比>80%） |
| ...... | ...... |
| 质量 | 单日日志中ERROR级别条数（>10000或占总量>0.1%） |
| 质量 | 单日日志中WARN级别条数（>50000或占总量>0.5%） |
| 质量 | 单日日志中ERROR级别无堆栈条数（>10000或占总量>0.1%） |
| 质量 | 单日日志中非ERROR级别堆栈条数（>10000或占总量>0.1%） |
| 质量 | 单日日志中ERROR级别条数突增（突增次数>3次） |
| ...... | ...... |

除此之外，你还可以将不同应用系统的指标进行横向对比，并采用排行榜的形式在科技内部进行公开，它将会产生一种改变行为的驱动力，可以有效激发“想要赢”和“不想失败”的心理活动，这就好比某些产品也会采用排行榜的方式来激励用户一样 。

通过设计指标体系+研发度量平台+公开排行榜单这三个手段的组合，在一定程度上可以驱动开发人员持续性整改日志打印的问题。但万事无绝对，那些始终无动于衷的人依然会存在，不过请不要强行要求对方，毕竟有时候存在即合理。

- - -
**写在最后**

日志打印规范固然重要，但也请不要过分追捧，它的核心价值还是在于能够帮助开发人员更好地记录应用系统的“案发现场”，并可为应用系统提供可持续改进的“线索”。但请牢记， 日志打印规范虽不是万能的，但没有日志打印规范却是万万不能的。

日志打印日志应用系统

著作权归作者所有

如果觉得我的文章对您有用，请点赞。您的支持将鼓励我继续创作！

添加新评论0 条评论

Ctrl+Enter 发表

匿名评论

应用系统日志打印规范实践之道

添加新评论0 条评论

本文隶属于专栏

作者其他文章

相关文章

相关问题

相关资料