打印日志是一门艺术，日志信息是开发人员排查线上问题最主要的手段之一，但规范打日志被开发同学经常所忽视。日志就像保险，平时正常的时候用不上，但是一旦出问题就都想看有没有保险可以用。一条良好的日志，是我们向外部证明的材料。

1. 概要

1.1 什么是日志？

日志，维基百科中对其的定义是一个或多个由服务器自动创建和维护的日志文件，其中包含其所执行活动的列表。

一个打印良好的日志文件可为开发人员提供精确的系统记录，可辅助开发人员定位到系统错误发生的详情及根源。在Java应用程序中，通常使用日志文件来记录应用程序运行过程中的重要逻辑参数及异常错误，辅之日志采集系统(ELK、DTM)构建系统监控体系。

1.2 为什么要记录日志？

上文中提到日志可以提供精准的系统记录方便根因分析，那为什么要记录日志，记录日志有哪些作用呢？

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

1.3 什么时候记录日志？

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

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

2. 基本规范

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级别异常

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

⍟ 常见的ERROR级别异常

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

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

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

2.3 常见日志格式

✪ 摘要日志

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

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