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

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

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

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

讲到这，我想你应该明白我想说的——应用系统日志打印确实非常重要，但日志打印规范将更为重要，它就像一把双刃剑，只有合理运用才能发挥其特有的作用及价值。

但在组织中，如果你想让你周围的人都能明白这个道理可并不容易，它需要一个漫长的传播过程，而在这个过程中，你不仅需要坚持不断地宣导来逐步增强他们的认知，还应借助必要的治理手段及工具平台进行辅助，只有利其所器，才能善其所事。

利器一：规范先行

在你想启动规范化日志打印前，建议先制定一份日志打印规范，它可能无法面面俱到，但没有关系，它的目的仅是为了先突显日志打印规范的重要性，并且让这件事情能够正式进入正轨。

如果组织中大部分都是 Java 应用，那么规范内容可以主要围绕 Java 应用来写，虽然无法覆盖所有开发语言，但其核心原则仍是可以借鉴的。另外，前期请务必不要将其复杂化，否则它将无法具备普适性，也无法被接受和传播。

Java 应用系统日志打印规范

Java 日志框架：

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

Java 日志规范：

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

规范二：【强制】禁止使用 Logback/Log4j2 等的 API，应使用 SLF4J 的 API。

规范三：【强制】在接口/方法的入口/出口处，打印请求及响应参数日志。

规范四：【强制】ERROR 级别日志需打印堆栈，而非 ERROR 级别日志则不需要。

规范五：【强制】禁止在代码循环体中直接打印非 DEBUG 级别的日志。

规范六：【强制】禁止日志打印内容中仅打印特殊字符或数字的情况。

规范七：【建议】日志内容中应包含关键特征类信息，例如：用户标识或流水号。

规范八：【建议】应采用异步打印模式，且打印时建议关闭打印位置信息。

规范九：【建议】日志打印若出现堵塞，建议至少丢弃 INFO 级别以上的日志。

规范十：【建议】每条日志在语义上可独立被理解，减少上下文关联理解。

Java 日志字段：

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

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

利器二：服务至上

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

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

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

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

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

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

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

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

利器三：度量为王

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

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

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

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

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

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

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

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

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

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

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

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

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

写在最后

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

一转眼，距离上一次文章发布已经快 5 个月了，上海突如其来的一场疫情打乱了我工作与生活的平衡状态。不过也正是在这段时间内，体验了未曾体验过的艰难和美好，疫情无情人有情，情在人间暖人心，期待疫情能够早日烟消云散，也希望生活能够尽快回到正轨。

期待同样追求技术的你，可以一起探讨与交流