From 77e2b3cddc78c1bc40a7ce0a0d29da669261b052 Mon Sep 17 00:00:00 2001 From: yaomanhai Date: Thu, 23 Dec 2021 17:50:37 +0800 Subject: [PATCH] Format check Signed-off-by: yaomanhai --- zh-cn/contribute/OpenHarmony-Log-guide.md | 43 +++++++++-------------- 1 file changed, 16 insertions(+), 27 deletions(-) diff --git a/zh-cn/contribute/OpenHarmony-Log-guide.md b/zh-cn/contribute/OpenHarmony-Log-guide.md index 3dbd82f31c..d49ff40b3e 100644 --- a/zh-cn/contribute/OpenHarmony-Log-guide.md +++ b/zh-cn/contribute/OpenHarmony-Log-guide.md @@ -27,10 +27,9 @@ DEBUG: 比INFO级别更详细的流程记录，通过该级别的日志可以更 **说明：** 日志内容应该简明扼要地描述发生的事情，阅读日志的人可以通过日志直接知道表述的含义，尽量不要通过产生日志的代码才能知道；符合语法语义的日志打印也有利于后续日志分析工具对日志进行自动化解析。如： -“1234” 除了开发人员自己没人知道什么意义 +“1234” 除了开发人员自己没人知道什么意义; -“Error happened” -哪里发生了什么错误，错误的原因值等都没有打印出来，不利于问题的定位分析。 +“Error happened” 哪里发生了什么错误，错误的原因值等都没有打印出来，不利于问题的定位分析。 - **【规则】日志中禁止打印隐私信息** @@ -88,7 +87,7 @@ DEBUG: 比INFO级别更详细的流程记录，通过该级别的日志可以更 - **【规则】代码运行失败的日志使用xxx failed, please xxx的形式打印，且需包含可能的解决方案，** - 如："Connect to server failed, please check network configuration" + 如："Connect to server failed, please check network configuration"。 ## 常见模式日志打印要求 @@ -106,24 +105,20 @@ DEBUG: 比INFO级别更详细的流程记录，通过该级别的日志可以更 - **【建议】对于性能敏感型业务的数据库操作日志中需记录操作消耗的时间** -**说明：** 数据库操作涉及I/O读写, -对于性能敏感性业务，数据库操作通常会是性能的关键节点，记录时间可以作为性能调优的参考依据。 +**说明：** 数据库操作涉及I/O读写, 对于性能敏感性业务，数据库操作通常会是性能的关键节点，记录时间可以作为性能调优的参考依据。 - **【建议】日志中应当记录数据库的JOB相关信息** -**说明：** -JOB的名称，执行内容，启动时间，结束时间，执行结果应当在日志中记录。 +**说明：** JOB的名称，执行内容，启动时间，结束时间，执行结果应当在日志中记录。 ### 文件类日志 - **【建议】日志中应当记录对文件的各种操作及其相关信息** -**说明：** 文件的常规操作包括: -创建、打开、读取、写入、关闭、删除、获取属性，操作的发起者、操作类型、操作结果需要记录日志；但文件内容不可记录以防止泄露用户隐私或暴露系统安全漏洞， -系统文件名可以打印，用户文件名不可以打印； 文件句柄值可以打印。 +**说明：** 文件的常规操作包括: 创建、打开、读取、写入、关闭、删除、获取属性，操作的发起者、操作类型、操作结果需要记录日志；但文件内容不可记录以防止泄露用户隐私或暴露系统安全漏洞，系统文件名可以打印，用户文件名不可以打印； 文件句柄值可以打印。 - **【建议】批量文件操作只打印一条日志而不是打印多条日志** -**说明：** 如批量删除大量文件，不要每删除一个文件就打印一条日志，只要记录删除的文件数即可，如果文件所在目录是系统创建，还要打印目录名称 +**说明：** 如批量删除大量文件，不要每删除一个文件就打印一条日志，只要记录删除的文件数即可，如果文件所在目录是系统创建，还要打印目录名称。 ### 关键对象/对象池日志 @@ -131,18 +126,17 @@ JOB的名称，执行内容，启动时间，结束时间，执行结果应当 - **【建议】日志中应当记录关键对象的操作过程，操作结果，状态变化** -**说明：** 对象的操作包括：创建、加载、卸载、释放等，对关键对象的操作需记录操作主体，操作类型，操作结果；状态类的需记录状态变化的前后值 +**说明：** 对象的操作包括：创建、加载、卸载、释放等，对关键对象的操作需记录操作主体，操作类型，操作结果；状态类的需记录状态变化的前后值。 ### 线程日志 - **【建议】日志中需记录线程的各种操作及相关信息** -**说明：** 线程的操作包括: -创建、启动、暂停、终止。日志中需记录操作线程的操作类型，操作结果、线程号，线程名称(重要线程一定要设置线程名)。 +**说明：** 线程的操作包括: 创建、启动、暂停、终止。日志中需记录操作线程的操作类型，操作结果、线程号，线程名称(重要线程一定要设置线程名)。 - **【建议】线程陷入死循环或死锁等错误时要记录日志** -**说明：** 对于有等锁处理、异步处理、循环处理等逻辑的线程在线程发生死锁或死循环时要有检测机制，并在错误发生时打印日志 +**说明：** 对于有等锁处理、异步处理、循环处理等逻辑的线程在线程发生死锁或死循环时要有检测机制，并在错误发生时打印日志。 - **【建议】消息处理型的线程需要打印消息处理相关的日志** @@ -158,17 +152,16 @@ JOB的名称，执行内容，启动时间，结束时间，执行结果应当 ### 共享内存日志 - -**说明：** 共享内存是软件系统中常用的进程间通信方法，它常用于在模块间共享数据或传递数据。共享内存所存放的数据可以是配置数据、数据库数据等 +**说明：** 共享内存是软件系统中常用的进程间通信方法，它常用于在模块间共享数据或传递数据。共享内存所存放的数据可以是配置数据、数据库数据等。 - **【建议】日志中需记录对共享内存的操作及相关信息** -**说明：** 对共享内存的操作包括：创建、删除、数据设置、数据查询、销毁等。日志中需记录对共享内存操作的操作者，操作类型、操作结果； +**说明：** 对共享内存的操作包括：创建、删除、数据设置、数据查询、销毁等。日志中需记录对共享内存操作的操作者，操作类型、操作结果。 ### 接口交互日志 -**说明：** 接口包括系统的内外部接口，内部接口指系统内部子系统、子模块之间的接口。形式可能包括模块间消息发送、IPC接口、RPC接口等。 +接口包括系统的内外部接口，内部接口指系统内部子系统、子模块之间的接口。形式可能包括模块间消息发送、IPC接口、RPC接口等。 - **【建议】日志需记录接口交互相关的信息** @@ -200,8 +193,7 @@ JOB的名称，执行内容，启动时间，结束时间，执行结果应当 - **【建议】每个业务内部基于Domain ID分配机制在领域内按照层次、模块的粒度划分使用** -**说明：** Domain -ID为32位整数，以16机制形式表达，分配范围0xD0xxxyy。其中D0为domain域标识，xxx高12位为DFT分配值，yy低8位业务领域内部使用。要求Domain ID 内部分配能够定界到组织或模块,反应领域内具体组织或模块日志质量，同时DFX会基于 Domain ID对日志打印进行管控，防止因为单个模块日志打印多影响领域内其它模块的日志输出，如BT业务内按照层次模块进一步划分： +**说明：** Domain ID为32位整数，以16机制形式表达，分配范围0xD0xxxyy。其中D0为domain域标识，xxx高12位为DFT分配值，yy低8位业务领域内部使用。要求Domain ID 内部分配能够定界到组织或模块,反应领域内具体组织或模块日志质量，同时DFX会基于 Domain ID对日志打印进行管控，防止因为单个模块日志打印多影响领域内其它模块的日志输出，如BT业务内按照层次模块进一步划分： APP | BT-App1 BT-App2 @@ -226,15 +218,12 @@ BT内的Domain ID可以进一步划分: - **【规则】日志服务会对每个业务的日志量进行流量管控，修改默认的流量阈值需要经过评审** -**说明：** 日志服务中会对每个领域的日志流量进行控制，在正式发布的版本上默认每个领域的日志流量阈值是**2048KB/秒**, -在调试版本上默认阈值是**10240KB/秒**, 如果需要修改默认阈值需经过DFX领域审查。 +**说明：** 日志服务中会对每个领域的日志流量进行控制，在正式发布的版本上默认每个领域的日志流量阈值是**2048KB/秒**, 在调试版本上默认阈值是**10240KB/秒**, 如果需要修改默认阈值需经过DFX领域审查。 - **【规则】正确填写日志格式化隐私参数标识{public},{private}** **说明：** 隐私参数标识{public}，{private}用来标识每个参数日志内容是否含隐私敏感信息。Hilog -API会自动对标识{public}参数内容以明文输出，对标识{private}参数内容以<private>过滤回显，禁止不分析日志打印内容随意设置隐私参数标识。 - -举例： +API会自动对标识{public}参数内容以明文输出，对标识{private}参数内容以<private>过滤回显，禁止不分析日志打印内容随意设置隐私参数标识。如： 源码: -- GitLab