392 lines
19 KiB
Plaintext
392 lines
19 KiB
Plaintext
应用日志规范（Java)
|
||
1.技术要求
|
||
1.1记录原则
|
||
1.【强制】隔离性：日志输出不应影响系统正常运行；
|
||
2.【强制】安全性：日志打印本身不应存在逻辑异常或漏洞，导致产生安全问题；
|
||
3.【强制】数据安全：不应输出机密、敏感信息，如用户联系方式、身份证号码、token等，应保证日志的完整性、
|
||
可审计性；
|
||
4.【强制】可监控分析：日志应提供给监控进行监控，分析系统进行分析；
|
||
5．【强制】可定位排查：日志信息输出应有意义，应具有可读性，可供开发人员排查线上问题。
|
||
1.2日志级别
|
||
在我们日常开发中有四种比较常见的日志打印等级，不同的等级适合在不同的时机下打印日志。
|
||
主要使用的有以下四个等级：
|
||
1.DEBUG
|
||
DEUBG级别应主要输出调试性质的内容，该级别日志应用于并发、测试阶段输出。该级别的日志应尽可能地详尽
|
||
开发人员可以将各类详细信息记录到DEBUG里，起到调试的作用，包括参数信息，调试细节信息，返回值信息等
|
||
等，便于在开发、测试阶段出现问题或者异常时，对其进行分析。
|
||
2. INFO
|
||
INFO级别的主要记录系统关键信息，旨在保留系统正常工作期间关键运行指标，开发人员可以将初始化系统配置，
|
||
业务状态变化信息，或者用户业务流程中的核心处理记录到INFO日志中，方便日常运维工作以及错误回溯时上下文
|
||
场景复现。应在项目完成后，在测试环境将日志级别调成INFO，然后通过INFO级别的信息看看是否能了解这个应用
|
||
的运用情况，如果出现问题后是否这些日志能否提供有用的排查问题的信息。
|
||
3.WARN
|
||
WARN级别的主要输出警告性质的内容，这些内容是可预知且是有规划的，比如，某个方法入参为空或者该参数的值
|
||
不满足运行该方法的条件时。在WARN级别的时应输出较为详尽的信息，以便于事后对日志进行分析。
|
||
注：常见的WARN级别异常
|
||
·用户输入参数错误
|
||
·非核心组件初始化失败
|
||
·后端任务处理最终失败（如果有重试且重试成功，就不需要WARN）
|
||
·数据插入幂等
|
||
4.ERROR
|
||
ERROR级别主要针对于一些不可预知的信息，诸如：错误、异常等，比如，在catch块中抓获的网络通信、数据库连
|
||
接等异常，若异常对系统的整个流程影响不大，可使用WARN级别日志输出。在输出ERROR级别的日志时，应尽量多
|
||
地输出方法入参数、方法执行过程中产生的对象等数据，在带有错误、异常对象的数据时，应将该对象一并输出。
|
||
注：常见的ERROR级别异常
|
||
·程序启动失败
|
||
·核心组件初始化失败
|
||
·连不上数据库
|
||
·核心业务访问依赖的外部系统持续失败
|
||
Woo·
|
||
不应滥用ERROR级别日志。一般来说在配置了告警的系统中，WARN级别一般不会告警，ERROR级别则会设置监控
|
||
告警甚至电话报警，ERROR级别日志的出现意味着系统中发生了非常严重的问题，应有人立即处理。
|
||
错误的使用ERROR级别日志，不区分问题的重要程度，只要是问题就采用ERROR级别日志，这是极其不负责任的表
|
||
现，因为大部分系统中的告警配置都是根据单位时间内ERROR级别日志出现的数量来定的，随意打ERROR日志会造
|
||
成极大的告警噪音，造成重要问题遗漏。
|
||
1.3日志格式
|
||
1.3.1后端日志格式
|
||
后端日志可以保存或输出到文件，远程服务器，控制台及数据库等，日志输出包含以下要素：
|
||
·时间戳：2024-01-29T15：30：45，789
|
||
·日志链路id(traceld、rpcld）（可选）0b26053315407142451016402xxxxx0.3－///-
|
||
·日志级别：DEBUG，INFO，WARN，ERROR，FATAL
|
||
·线程名：SofaBizProcessor-4-thread-333，main
|
||
·类名或Logger名称：com.example.MyClass
|
||
·方法名与行号（可选）：·myMethod（L45）
|
||
·调用耗时（可选）1ms
|
||
·调用是否成功(Y/N）(可选)
|
||
·状态码（可选）SUCCESS
|
||
·系统上下文信息（调用系统名、调用系统ip、调用时间戳、是否压测（Y/N)）（可选）appName，ip地址，时间戳，Y
|
||
·请求入参（可选）参数1
|
||
·请求出参（可选）参数1
|
||
·日志消息内容："Thisis alog message"，"No URLs will be polled as dynamic
|
||
configurationsources"
|
||
日志自定义输出格式如下：
|
||
[SofaBizProcessor-4-thread-333] {com.example.MyClass}-L22-[(1ms,Y,SUCCESS)(appName,ip
|
||
地址，时间戳，Y)（参数1,参数2)]-NoURLswillbe polled asdynamicconfiguration sources
|
||
[ob26053315407142451016402xXXxx0.3-///-]是traceld；[INF0]是日志级别；
|
||
[SofaBizProcessor-4-thread-333]是线程名；{com.example.MyClass}是类名；L22是行号；No
|
||
URLswillbepolledasdynamicconfigurationsources是实际的日志消息，具体的业务相关日志打
|
||
印形式可以根据业务实际情况自定义。
|
||
日志标准输出格式如下：
|
||
1 2024-01-29 15:30:45,789 [INF0] [main]{com.example.MyClass} ]-No URLs will be polled
|
||
as dynamicconfigurationsources
|
||
注：移动端日志遵循后端日志格式。
|
||
1.3.2前端日志格式
|
||
因素：
|
||
1.时间戳：在日志条目的开头添加一个时间戳，以便跟踪事件发生的时间。
|
||
2.日志级别：指定日志条目的级别（例如，错误、警告、信息、调试等），以便根据需要进行筛选和过滤。
|
||
3.源代码位置：在日志条目中包含源代码的位置信息（例如，文件名、行号等），以便快速定位问题。
|
||
4.消息内容：提供有关事件或错误的详细信息，包括任何相关的上下文或错误消息。
|
||
5.自定义字段：根据需要添加具他自定义字段，例如用户ID、会话ID、浏览器信息等。
|
||
以下是一个简单的前端日志格式示例：
|
||
1[2023-03-15 14:32:01] INF0: main.js:123 -User logged in successfully.
|
||
[2023-03-15 14:32:15] ERR0R: user.js:45-Failed to fetch user data. Error: Network
|
||
Error.码
|
||
在这个示例中，每条日志条目都包含时间戳、日志级别、源代码位置以及消息内容。此外，还可以根据需要添加其他
|
||
自定义字段，例如用户ID、会话ID等。
|
||
需要注意的是，前端日志格式应该根据项目的具体需求和规范进行定制，以便更好地满足项目的需求。同时，还需要
|
||
考虑日志的存储、传输和展示等方面的问题，以确保日志的可用性和可维护性。
|
||
1.4日志存储
|
||
应及时清理和管理日志，以避免过大的日志文件或存储空间的浪费。及时地分析日志，以便发现潜在的问题或改进系
|
||
统性能。
|
||
志文件的重要程度、文件大小以及磁盘空间自行调整，6个月内至少清理一次过期的或无用的日志数据，此外，还可
|
||
以对日志进行监控，收到磁盘报警时，对1个月之前的数据可以进行删除或者转储。
|
||
1.5日志安全
|
||
1.5.1保护范围
|
||
日志记录中包含的某些内容出于隐私保护、数据安全和法规遵从的要求，不应直接以原始形式显示。以下是一些需要
|
||
进行处理的内容类型：
|
||
1.法律法规不充许的信息
|
||
·《个人信息保护法》涉及的敏感信息：《个保法》第二十八条敏感个人信息是一旦泄露或者非法使用，容易导致
|
||
自然人的人格尊严受到侵害或者人身、财产安全受到危害的个人信息，包括生物识别、宗教信仰、特定身份、医
|
||
疗健康、金融账户、行踪轨迹等信息，以及不满十四周岁未成年人的个人信息。根据法规，个人可识别信息如身
|
||
份证号码、电话号码、住址、电子邮件地址等必须严格保护，未经同意不得非法收集、使用或披露。同时，个人
|
||
敏感数据如健康状况、医疗记录、生物识别信息等高度私密，处理时需特别谨慎，确保合法合规。
|
||
2.石油集团保密要求
|
||
·包括但不限于涉密技术资料、勘探数据、生产数据、商业合作细节等信息，信息系统日志中应避免直接记录这些
|
||
内容，并对所有操作进行严格的审计和安全控制，确保日志的安全存储、访问权限控制以及必要时的数据脱敏。
|
||
3.涉及的商业秘密信息
|
||
·在日志中，商业秘密信息可能以各种形式体现，例如研发数据、客户名单、内部策略、未公开的产品设计和技术
|
||
方案等。
|
||
4.业务定义敏感信息
|
||
·金融交易信息：银行卡号、支付卡数据（CVV码、有效期等）是金融行业严控的信息，必须采取加密或具他安全
|
||
措施妥善处理和存储。
|
||
致企业竞争优势受损或违反合同约定的信息。
|
||
5.可能有助于攻击者利用的敏感数据
|
||
·用户的会话lD（如果需要跟踪会话相关的事件，可以考虑用Hash值代替）
|
||
·会话ID与Hash值：为了防止会话劫持，原始会话ID不应在日志中明文记录，可以考虑采用哈希值代替，但要确保
|
||
该哈希不能被反向解析为原始会话标识。
|
||
此建议不在日志中详细记录或仅记录到主版本级别。
|
||
·散列值：如果散列为敏感数据的散列，例如密码散列，在记录日志时应当谨慎，避免将过于详细的散列值存入日
|
||
志，特别是对于易破解的弱散列算法。
|
||
式去标识化。
|
||
·数据库连接字符串与密钥：包含数据库凭据的连接字符串、加密密钥和其他主密钥绝对不能出现在日志中，这些
|
||
信息一旦泄露可能导致数据大规模泄露或系统完全失控。
|
||
1.5.2脱敏方法
|
||
不应在日志中明文记录敏感信息数据，必要时对这些数据进行脱敏处理。对敏感的日志信息进行加密，以保护数据安
|
||
全。确保在存储和传输过程中对敏感信息进行加密，以防止未授权的访问和泄露。
|
||
需要脱敏的信息见”保护范围“部分。
|
||
注：在进行日志脱敏时，会根据不同的敏感级别采用不同的脱敏策略，包括替换、遮盖、截断、哈希加密等方法，以
|
||
保护这些信息不被泄露，同时确保日志能够满足必要的业务分析和故障排查要求
|
||
具体方式包括但不限于：
|
||
·移除（Remove）：直接从日志条目中删除敏感字段。
|
||
·分类与分级处理：根据数据的敏感程度进行分类，并针对不同类别实施不同的脱敏策略，例如部分脱敏或完全替
|
||
换。
|
||
·脱敏（Masking)：替换敏感字段为星号、占位符或其他非敏感字符，如将电话号部分数字脱敏为“******
|
||
1234”。
|
||
·净化（Sanitizing)：对敏感数据进行格式化或规范化，确保不泄露实际意义，例如使用哈希函数处理用户身份信
|
||
息。
|
||
·Hash化：对于需要保持唯一性的数据，比如用户名或电子邮件地址，可以采用不可逆的哈希算法进行处理，用于
|
||
审计目的但不能反向还原出原始数据。
|
||
实施上述措施有助于企业在满足日志分析和故障排查需求的同时，最大限度地降低数据泄露风险，并符合《网络安全
|
||
注：在使用日志框架如logback、Log4j等时，可以配置相应的插件或者自定义拦截器来实现自动化脱敏功能。
|
||
1.5.3安全措施
|
||
日志数据安全是确保系统在生成、传输、存储日志时，保护敏感信息不被未经授权的访问、泄露、篡改或丢失的重要
|
||
环节。以下是维护日志数据安全的一些关键措施：
|
||
1.日志数据传输加密：
|
||
·在传输过程中，可使用SSL/TLS等安全协议加密SYSLOG或具他形式的日志数据流。
|
||
2.访问控制：
|
||
·实施严格的访问控制策略，只有授权人员才能查看和操作日志数据，
|
||
3.敏感信息处理：
|
||
·对于包含敏感信息的日志条目，执行脱敏处理，如替换或模糊化密码、个人识别信息（PII)、信用卡号等敏感内
|
||
容。
|
||
4.标准化与合规：
|
||
·确保日志格式和实践符合行业标准和法规要求，比如《网络安全法》和《网络安全等级保护基本要求》对于数据
|
||
处理的规定。
|
||
5.备份与恢复：
|
||
·定期备份日志，并保证备份数据的安全性，同时设计有效的灾难恢复方案。
|
||
通过上述措施，可从多个维度保障日志数据的安全性，同时也为数据分析、故障排查、安全审计及合规性检查提供了
|
||
有力支持。
|
||
1.6Java最佳实践
|
||
1.【推荐】日志语言应使用英文
|
||
注：应在打印日志时输出英文，防止中文编码与终端不一致导致打印出现乱码的情况，对故障定位和排查存在一定的
|
||
干扰。如果日志中的错误信息用英文描述不清楚可使用中文描述，否则容易产生歧义。国际化团队或海外部署的服务
|
||
器由于字符集问题，uing用英文来注释和描述日志错误信息。
|
||
2.【推荐】日志打印时不宜直接用JSON工具将对象转换成String
|
||
反例：
|
||
1 public void doSth(){
|
||
2
|
||
log.info("do sth and print log，data={}"，JsoN.toJsoNstring(data));
|
||
3
|
||
//业务逻辑
|
||
4
|
||
51
|
||
注：
|
||
·fastison等序列化组件是通过调用对象的get方法将对象进行序列化，如果对象里某些get方法被覆写，存在抛出异
|
||
常的情况，则可能会因为打印日志而影响正常业务流程的执行。
|
||
打日志过程中对一些对象的序列化过程也是比较耗性能的。首先序列化过程本身时一个计算密集型过程，浪费
|
||
cpu。其次这个过程会产生很多中间对象，对内存也不友好。
|
||
正例：
|
||
可以使用对象的toString(（）方法打印对象信息，如果代码中没有对toString（有定制化逻辑的话，可以使用apache的
|
||
ToStringBulider工具。
|
||
1public void doSth(){
|
||
2
|
||
log.info("do sth and print log, data={}", data.toString());
|
||
3
|
||
log.info("do sth and print log， data=[}"， ToStringBuilder.reflectionToString(data，T
|
||
4
|
||
3.
|
||
【强制】不应打印无意义（无业务上下文、无关联日志链路id）的日志
|
||
反例：
|
||
不带任何业务信息的日志，对排查故障毫无意义。
|
||
1public void doSth(）{
|
||
2
|
||
log.info("do sth and print log");
|
||
3
|
||
//业务逻辑
|
||
4
|
||
5}
|
||
对于无异常分支的代码打印日志，一般流程下，异常分支都会打日志，如果没有出现异常，那就正常执行了。
|
||
1public void doSth(）{
|
||
2
|
||
doIt1();
|
||
3
|
||
log.info("do sth 1l1");
|
||
4
|
||
doIt2();
|
||
5
|
||
log.info("do sth 222");
|
||
6}
|
||
正例：
|
||
·日志应带相关的业务信息，有利于排查问题快速定位到原因。
|
||
1public void doSth(）{
|
||
2
|
||
log.info("do sth and print log， id=[}"，id);
|
||
3
|
||
//业务逻辑
|
||
4
|
||
+
|
||
【强制】不应在循环中打印非DEBUG级别的日志
|
||
反例：
|
||
1 public void doSth(){
|
||
2
|
||
for(String s:strList){
|
||
3
|
||
log.info("do sth and print log: {}"，s);
|
||
4
|
||
//业务逻辑
|
||
5
|
||
6
|
||
7
|
||
5.【推荐】在核心业务逻辑中遇到if..else等条件，每个分支首行都应打印日志
|
||
在编写核心业务逻辑代码时，如遇到if..else...或者switch这样的条件，可以在分支的首行就打印日志，这样排查问题
|
||
时，就可以通过日志，确定进入了哪个分支，代码逻辑更清晰，也更方便排查问题。
|
||
正例：
|
||
1 public void doSth(){
|
||
2
|
||
if(user.isVip()){
|
||
3
|
||
log.info（"该用户是会员，Id：[}，开始处理会员逻辑",user，getUserId（））；
|
||
4
|
||
//会员逻辑
|
||
5
|
||
}else{
|
||
6
|
||
log.info（"该用户是非会员，Id：[}，开始处理非会员逻辑",user，getUserId（））
|
||
//非会员逻辑
|
||
9}
|
||
6.【推荐】宜打印必要的参数，不宜整个对象打印
|
||
反例：
|
||
1 public void doSth(）{
|
||
2
|
||
log.info("print log，data={}"，data.toString(）);
|
||
3
|
||
//业务逻辑
|
||
4
|
||
5}
|
||
注：首先分析下自己是否必须把所有对象里的字段打印出来？如果对象中有50个字段，但只需其中两个参数就可以定
|
||
位具体的原因，那么全量打印字段将浪费内容空间且因为字段过多，影响根因排查。
|
||
正例：
|
||
1 public void doSth(){
|
||
2
|
||
log.info("print log，id={}，type={}"，data.getId()，data.getType());
|
||
3
|
||
//业务逻辑
|
||
4
|
||
5}
|
||
注：使用这个种方法需及时防止npe，并考虑是否核心场景，核心场景建议还是打全，避免漏打、少打影响线上问题
|
||
定位&排查。
|
||
7.【强制】在接口/方法的入口/出口处，打印请求及响应参数日志。
|
||
8
|
||
【推荐】日志内容中不应仅打印特殊字符或数字。
|
||
9.
|
||
【推荐】日志内容中应包含关键特征类信息，例如：用户标识或流水号。
|
||
10.
|
||
【强制】日志单行大小应不超过200K
|
||
11．【强制】打印日志的代码不应失败，阻断流程！
|
||
一定要确保不会因为日志打印语句抛出异常造成业务流程中断，如下所示，shop为null的会导致抛出NPE。
|
||
1public void doSth(){
|
||
2
|
||
log.info("do sth and print log: [}"，shop.getId());
|
||
3
|
||
//业务逻辑
|
||
4
|
||
5}
|
||
12.【强制】不应使用System.out.println(输出日志
|
||
反例：
|
||
1public void doSth(){
|
||
2
|
||
System.out.println("doSth...");
|
||
3
|
||
//业务逻辑
|
||
4
|
||
5}
|
||
注：通过分析System.out.println源码可知，System.out.println是一个同步方法，在高并发的情况下，大量执行
|
||
println方法会严重影响性能。
|
||
1 public void println(String x){
|
||
2
|
||
synchronized （this）[
|
||
3
|
||
print(x) ;
|
||
4
|
||
newLine();
|
||
5
|
||
6
|
||
不能实现日志按等级输出。具体来说就是不能和日志框架一样，有debug，info，error等级别的控制。
|
||
System.out、System.error打印的日志并没有打印在日志文件中，而是直接打印在终端，无法对日志进行收集。
|
||
正例：
|
||
在日常开发或者调试的过程中，应使用标准日志记录系统log4j2或者logback（但不应直接使用其中的APl)，异步的进
|
||
行日志统一收集。
|
||
1 public void doSth(){
|
||
2
|
||
log.info("doSth...") ;
|
||
3
|
||
//业务逻辑
|
||
13.【强制】对于debug/info级别的日志输出，应进行日志级别的开关判断
|
||
反例：
|
||
1 public void doSth(){
|
||
2
|
||
String name = "xxx";
|
||
3
|
||
logger.debug("print debug log"+ name);
|
||
4
|
||
logger.info("print infolog"+ name);
|
||
5
|
||
//业务逻辑
|
||
6
|
||
7}
|
||
注：
|
||
如果配置的日志级别是warn的话，上述日志不会打印，但是会执行字符串拼接操作，如果name是对象，还会执行
|
||
toString（方法，浪费了系统资源，执行了上述操作，最终日志却没有打印，因此建议加日志开关判断。
|
||
正例：
|
||
在debug、info级别日志打印前加上对应级别的日志开关判断，通常可以将开关判断逻辑包装在日志工具类中，统一
|
||
实现。
|
||
1 public void doSth(){
|
||
2
|
||
if(logger.isDebugEnabled()）{
|
||
3
|
||
logger.debug("print debug log {}"，name);
|
||
4
|
||
5
|
||
if(logger.isInfoEnabled()）{
|
||
6
|
||
logger.info("print info log [}"，name;
|
||
7
|
||
}
|
||
8
|
||
//业务逻辑
|
||
9
|
||
10}
|
||
14.
|
||
【强制】打印异常日志应要输出全部错误信息
|
||
反例：
|
||
没有打印异常e，无法定位出现什么类型的异常
|
||
1 public void doSth(){
|
||
2
|
||
tryf
|
||
3
|
||
//业务逻辑
|
||
4
|
||
5
|
||
}catch（Exception e）{
|
||
6
|
||
log.error("execute failed");
|
||
7
|
||
8}
|
||
没有记录详细的堆栈异常信息，只记录错误基本描述信息，不利于排查问题。
|
||
1 public void doSth(){
|
||
2
|
||
tryf
|
||
3
|
||
//业务逻辑
|
||
4
|
||
5
|
||
}catch (Exception e){
|
||
6
|
||
log.error("execute failed",e.getMessage());
|
||
7
|
||
8
|
||
正例：
|
||
一般日志框架中的warn、error级别均有存在传递Throwable异常类型的APl，可以直接将抛出的异常传入日志APl中。
|
||
1void error(String varl， Throwable var2);
|
||
2 public void doSth(){
|
||
3
|
||
tryf
|
||
4
|
||
//业务逻辑
|
||
5
|
||
6
|
||
}catch （Exception e){
|
||
7
|
||
log.error("executefailed"，e);
|
||
8
|
||
9}
|