系统性的思考一下项目日志的建设

本期内容概述

本文主要阐述并整理了在进行项目开发时关于日志记录方面的一些个人思考，其中也参考了诸如阿里巴巴开发手册等等的一些日志规范建议，但并没有完全的照搬照抄。

文末给出了一个集中日志展示分析平台的建设方案，希望能帮助到有需要的同学

日志的概述

日志的定义

日志是一种按照时间顺序存储记录的数据，它记录了什么时间发生了什么事情，提供精确的系统记录，根据日志信息可以定位到错误详情和根源。

日志是按照错误级别分级的，常见的错误级别有ERROR/ WARNING / INFO / DEBUG /TRACE 5种类型。通常我们会在项目里面定义一个日志打印级别，高于这个级别的错误日志会数据落盘

日志的价值

1.日志所记录的信息方便系统进行排错，告警，优化性能

2.用户行为的分析，帮助产品经理以及运营人员进行业务决策

3.排查异常访问，安全攻击，进行审计跟踪

项目日志规范

强制规范

应用中不可直接使用日志系统中的 API，而应依赖使用日志框架中的 API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一

1. JAVA项目使用SLF4J、Jakarta Commons Logging中的API

对日志输出进行分类,便于开发人员查看,也便于通过日志对系统进行及时监控

1. 当天应用日志，以“appName_logLevel.log”来保存
2. 过往日志格式为: appName_logLevel.log.{保存日期}，日期格式:yyyy-MM-dd
3. 应用中的扩展日志(如业务埋点、临时监控、访问日志等)命名方式为:appName_logType.log
4. 不同类型的日志可以输出不同的日志格式，如业务埋点日志可以直接输出JSON格式

在日志输出时，字符串变量之间的拼接使用占位符的方式

1. 因为 String 字符串的拼接会使用 StringBuilder 的 append()方式，有一定的性能损耗，使用占位符仅是替换动作，可以有效提升性能

生产环境禁止直接使用 System.out 或 System.err 输出日志或使用e.printStackTrace()打印异常堆栈

异常信息应该包括两类信息:案发现场信息和异常堆栈信息，如果不处理，那么通过关键字 throws 往上抛出。

1. 示例:logger.error("请求参数:{} ,异常信息:{}", 各类参数或者对象 toString(), e.getMessage(), e);

所有日志文件至少保存两周，因为有些异常具备以“周”为频次发生的特点

推荐规范

打印日志时仅打印出业务相关属性值或者调用其对象的 toString()方法

1. 日志打印时不建议直接用 JSON 工具将对象转换成 String,不过具体问题具体分析，并发访问量不高的情况下可以尝试使用

记录日志时请先进行思考:这些日志真的有人看吗，看到这条日志你能做什么，能不能给问题排查带来好处。

1. 大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。

一个项目尽量使用统一的语言(英文/中文)来描述日志信息

记录日志时机

系统启动初始化时加载的自定义配置信息

调用第三方服务的出参以及入参

1. HTTP调用的请求参数与响应参数
2. RPC框架调用请求参数与响应参数
3. MQ调用的请求参数与响应参数

后台定时任务的执行情况

程序异常

1. 在程序出现exception的时候，要么选择向上抛出异常，要么必须在catch块中打印异常堆栈信息

特殊的条件分支

1. 一些参数本不应该为空但是判断条件为空而执行的分支等，建议使用WARN级别日志输出

接口请求数据的入参以及出参

1. 包括但不限于系统中Controller层的请求入参以及响应出参

执行关键方法的入参以及出参

1. 包括但不限于系统中关键Service层的请求入参以及出参

执行关键方法的中间状态记录

1. 关键方法中间逻辑运行的状态记录

日志输出格式

强制输出

1. 时间戳
2. 执行线程
3. 日志级别
4. 执行类名
5. 执行类行号
6. 输出内容

推荐输出

1. traceId，轨迹Id，用于串联一次完整的请求执行路径
2. userId，用户Id，用于作业系统标识某位业务操作人员执行的请求

建立集中统一的日志收集分析展示平台

建设目的

1. 希望通过原始日志可以理解系统行为，建设具备性能分析，问题定位的能力的工具平台，在故障发生前，分析风险和系统瓶颈，在故障发生时，及时通知，快速定位解决问题，在故障发生后，有历史数据迅速复盘
2. 通过建设具备日志即时收集、分析、存储等能力的工具平台，用户可以快速高效地进行问题诊断、系统运维，追踪并记录请求在系统中的调用顺序，调用时间等一系列关键信息，帮助我们定位异常服务和发现性能瓶颈
3. 集中统一的日志收集分析展示平台是进行业务系统微服务化拆分的关键基础设施

建设方案

架构设计

1. Filebeat 轻量级的日志文件采集工具，用于采集文件所产生的日志
2. Kafka 消息中间件，不单单可以接收Filebeat采集的日志数据，也可以接收系统埋点 用户操作轨迹等数据，用于后续的业务分析统计汇总
3. logstash 接收kafka上面的日志数据后进行分析过滤，变更为结构化的数据进行输出
4. ElasticSearch 用于存储分析过滤后的数据，建立查询索引
5. Kibana 提供报表、图形化数据进行可视化展示 Web 界面，可以帮助汇总、分析和搜索重要数据日志