系统日志规范及最佳实践

打印调试：用日志来记录变量或者某一段逻辑，记录程序运行的流程，即程序运行了哪些代码，方便排查逻辑问题。
问题定位：程序出异常或者出故障时快速的定位问题，方便后期解决问题。因为线上生产环境无法 debug，在测试环境去模拟一套生产环境费时费力。所以依靠日志记录的信息定位问题，这点非常重要。
监控告警 & 用户行为审计：格式化后日志可以通过相关监控系统(AntMonitor)配置多维度的监控视图，让我们可以掌握系统运行情况或者记录用户的操作行为并对日志采集分析，用于建设业务大盘使用。

1.3 什么时候记录日志？

上文说了日志的重要性，那么什么时候需要记录日志。

代码初始化时或进入逻辑入口时：系统或者服务的启动参数。核心模块或者组件初始化过程中往往依赖一些关键配置，根据参数不同会提供不一样的服务。务必在这里记录 INFO 日志，打印出参数以及启动完成态服务表述。
编程语言提示异常：这类捕获的异常是系统告知开发人员需要加以关注的，是质量非常高的报错。应当适当记录日志，根据实际结合业务的情况使用 WARN 或者 ERROR 级别。
业务流程预期不符：项目代码中结果与期望不符时也是日志场景之一，简单来说所有流程分支都可以加入考虑。取决于开发人员判断能否容忍情形发生。常见的合适场景包括外部参数不正确，数据处理问题导致返回码不在合理范围内等等。
系统/业务核心逻辑的关键动作：系统中核心角色触发的业务动作是需要多加关注的，是衡量系统正常运行的重要指标，建议记录 INFO 级别日志。
第三方服务远程调用：微服务架构体系中有一个重要的点就是第三方永远不可信，对于第三方服务远程调用建议打印请求和响应的参数，方便在和各个终端定位问题，不会因为第三方服务日志的缺失变得手足无措。

二、基本规范

2.1 日志记录原则

隔离性：日志输出不能影响系统正常运行；
安全性：日志打印本身不能存在逻辑异常或漏洞，导致产生安全问题；
数据安全：不允许输出机密、敏感信息，如用户联系方式、身份证号码、token 等；
可监控分析：日志可以提供给监控进行监控，分析系统进行分析；
可定位排查：日志信息输出需有意义，需具有可读性，可供日常开发同学排查线上问题。

2.2 日志等级设置规范

在我们日常开发中有四种比较常见的日志打印等级，不同的等级适合在不同的时机下打印日志。

主要使用的有以下四个等级：

DEBUG

DEUBG 级别的主要输出调试性质的内容，该级别日志主要用于在开发、测试阶段输出。该级别的日志应尽可能地详尽，开发人员可以将各类详细信息记录到 DEBUG 里，起到调试的作用，包括参数信息，调试细节信息，返回值信息等等，便于在开发、测试阶段出现问题或者异常时，对其进行分析。

INFO

INFO 级别的主要记录系统关键信息，旨在保留系统正常工作期间关键运行指标，开发人员可以将初始化系统配置、业务状态变化信息，或者用户业务流程中的核心处理记录到 INFO 日志中，方便日常运维工作以及错误回溯时上下文场景复现。建议在项目完成后，在测试环境将日志级别调成 INFO，然后通过 INFO 级别的信息看看是否能了解这个应用的运用情况，如果出现问题后是否这些日志能否提供有用的排查问题的信息。

WARN

WARN 级别的主要输出警告性质的内容，这些内容是可以预知且是有规划的，比如，某个方法入参为空或者该参数的值不满足运行该方法的条件时。在 WARN 级别的时应输出较为详尽的信息，以便于事后对日志进行分析。

ERROR

ERROR 级别主要针对于一些不可预知的信息，诸如：错误、异常等，比如，在 catch 块中抓获的网络通信、数据库连接等异常，若异常对系统的整个流程影响不大，可以使用 WARN 级别日志输出。在输出 ERROR 级别的日志时，尽量多地输出方法入参数、方法执行过程中产生的对象等数据，在带有错误、异常对象的数据时，需要将该对象一并输出。

如何选择 WARN/ERROR

当方法或者功能出现非正常逻辑执行情况时，需要打印 WARN 或者 ERROR 级别日志，那如何区分出现异常时打印 WARN 级别还是 ERROR 级别呢，我们可以从以下两个方面进行分析：

常见的 WARN 级别异常

用户输入参数错误
非核心组件初始化失败
后端任务处理最终失败（如果有重试且重试成功，就不需要 WARN）
数据插入幂等

常见的 ERROR 级别异常

程序启动失败
核心组件初始化失败
连不上数据库
核心业务访问依赖的外部系统持续失败
OOM

不要滥用 ERROR 级别日志。一般来说在配置了告警的系统中，WARN 级别一般不会告警，ERROR 级别则会设置监控告警甚至电话报警，ERROR 级别日志的出现意味着系统中发生了非常严重的问题，必须有人立即处理。

错误的使用 ERROR 级别日志，不区分问题的重要程度，只要是问题就采用 ERROR 级别日志，这是极其不负责任的表现，因为大部分系统中的告警配置都是根据单位时间内 ERROR 级别日志出现的数量来定的，随意打 ERROR 日志将会造成极大的告警噪音，造成重要问题遗漏。

2.3 常见日志格式

摘要日志

摘要日志是格式化的标准日志文件，可用于监控系统进行监控配置和离线日志分析的日志，通常系统对外提供的服务以及集成的第三方服务都需要打印对应的服务摘要日志，摘要日志格式一般需包含以下几类关键信息：

调用时间
日志链路 id(traceId、rpcId)
线程名
接口名
方法名
调用耗时
调用是否成功(Y/N)
错误码
系统上下文信息(调用系统名、调用系统 ip、调用时间戳、是否压测(Y/N))

2022-12-12 06:05:05,129 [0b26053315407142451016402xxxxx 0.3 - /// - ] INFO [SofaBizProcessor-4-thread-333] - [(interfaceName,methodName,1ms,Y,SUCCESS)(appName,ip地址,时间戳,Y)

详细日志

详细日志是用于补充摘要日志中的一些业务参数的日志文件，用于问题排查。详细日志一般包含以下几类信息：

调用时间
日志链路 id(traceId、rpcId)
线程名
接口名
方法名
调用耗时
调用是否成功(Y/N)
系统上下文信息(调用系统名、调用系统 ip、调用时间戳、是否压测(Y/N))
请求入参
请求出参

2022-12-12 06:05:05,129 [0b26053315407142451016402xxxxx 0.3 - /// - ] INFO [SofaBizProcessor-4-thread-333] - [(interfaceName,methodName,1ms,Y,SUCCESS)(appName,ip地址,时间戳,Y)(参数1,参数2)(xxxx)