日志规范

规范英文名：HiveNet Log Standards

规范中文名：HiveNet 日志规范

HiveNet标识名：hivenet_log_standards

HiveNet版本：v1.0.0

文件存放路径

同一个应用的日志文件应统一路径存放，不应存放到多个路径下，路径命名统一为小写，用下划线”_”区分词组。日志根目录统一命名为：

  • log/ - 日志目录

  • log_bak_yyyy[mm][dd]/ - 备份目录，根据需要可以按年/月/日进行备份

日志文件可以直接放在日志根目录下，但如果类型太多（需要按应用、模块区分），则可增加一层路径区分不同应用模块日志，路径格式如下：

  • log/app[_module][_IP] - 根据需要区分到应用还是模块，以及涉及分布式部署的情况下指定IP（或远程日志的情况）

此外，基于存储划分的考虑，可以将日志根目录放置在应用部署路径下，或存在服务器的根目录下，采用何种方式根据实际需要选用：

  • 在应用部署路径存放 - 必须直接放在部署路径根目录下，例如/weblogic/hive_net/log/…

  • 在服务器根路径存放 - 例如 /log/…

文件命名

日志文件的命名规则为（均为小写）：app[_moudle][_info/debug/…]_yyyymmdd.log[.n]

app ： 应用名

moudle : 模块名，可选

info/debug/… : 日志级别，可选；当需要将不同级别的的日志内容区分开时选用

yyyymmdd ： 日志日期

.n : 日志序号，如果控制了日志文件的最大大小，则在文件超过限额时自动增加序号，并开始写下一个日志

日志输出规范

日志输出信息格式固定为 “日志头+日志信息”，”日志头”的所有信息均在日志开始行中，”日志信息”可以在日志头同一行中全部输出，也可以分多行输出。

标准格式

每行日志的日志头的开头均为以下标准格式：[%(asctime)s][%(levelname)s][PID:][TID:3676][FILE:][FUN:]

说明如下：

日志头为规则的字符串格式，每个信息项用中括号”[]”标注起来，日志头的前2个为固定顺序的信息项，包括：

  • [%(asctime)s] : 日志记录时间，格式为”yyyy-mm-dd hh:mi:ss,ms”，例如[2018-09-09 13:58:08,243]

  • [%(levelname)s] : 日志级别名称，例如[DEBUG]、[INFO]、[WARNING]、[ERROR]、[CRITICAL]

后面的日志头信息项为不固定信息项，格式为 [信息项标识:信息项值] ，常用的信息项标识包括：

  • PID : 进程ID， 例如 [PID:4348]

  • TID : 线程ID, 例如 [TID:3676]

  • TNAME: 线程名称，例如 [TNAME:Service_Recv]

  • PATH : 执行文件路径，例如 [PATH:/hivenet/]

  • FILE : 执行文件名，例如 [FILE:simple_log_demo.py]

  • FUN : 函数名，例如 [FUN:test_case2]

日志信息为具体输出的详细信息，没有具体格式要求，可以一行也可以多行，如存在格式化的数据需要分析，建议抽离为日志头信息处理，采用手段为将信息项按照日志头格式标注并放在日志信息开始位置传入日志处理。

示例如下：

[2018-09-09 14:46:27,847][INFO][PID:4328][TID:4776][FILE:simple_log_demo.py][FUN:test_case2]test_case2:write_log:INFO:6-1:界面应显示本日志
，文件应显示本日志
[2018-09-09 14:46:27,848][DEBUG][PID:4328][TID:4776][FILE:simple_log_demo.py][FUN:test_case2]test_case2:write_log:DEBUG:6-1:界面应显示本日
志，文件应显示本日志
[2018-09-09 14:46:27,848][INFO][PID:4328][TID:4776][FILE:simple_log_demo.py][FUN:test_case2]test_case2:write_log:INFO:7-1:界面应显示本日志
，文件应显示本日志

应用启停日志规范

可以通过应用标识（APPTAG）识别启停的应用类型，应用标识定义如下：

SER - 服务，指整体服务，可能是多个应用的集合（启动服务涉及启动多个应用）

APP - 应用，指某个独立应用，例如报表应用、批量处理应用

MOD - 模块，指应用中的重要处理模块

CLI - 客户端，指客户端程序

LIS - 监听，指网络服务的IP及端口的监听服务

应用启动日志

标准日志格式如下（这里只列出标准日志头后面的内容）：

[APPTAG-STARTING][NAME:标识名][补充信息项][...]处理事项文字描述

...

[APPTAG-STARTED][NAME:标识名][USE:0.01s][补充信息项][...]处理事项文字描述

要求如下：

1、对于非毫秒级完成启动的应用，应输出包括STARTING和STARTED的完整日志信息（注意：可以多个STARTING对应一个STARTED），登记开始启动和完成启动的时间信息；对于毫秒级能完成启动的情况，可以只有STARTED的日志信息；

2、STARTED的日志信息日志头中通过[USE:]信息项记录启动所需时间；

3、处理事项文字按具体需要输出描述信息，目的是让非开发人员理解并能重复说明日志内容，例如“加载生产参数…”、“清理缓存文件…”等；

4、针对不同应用标识，补充信息项要求如下（STARTING和STARTED都需要）：

  • LIS - 监听，[IP:监听IP]、[PORT:监听端口]

示例如下（这里只列出标准日志头后面的内容）：

[SER-STARTING][NAME:upp-service-1]启动统一支付服务
[APP-STARTING][NAME:upp-app-quota]启动限额模块
[MOD-STARTED][NAME:quota-para][USE:0.01s]加载限额参数
[LIS-STARTED][NAME:lisent-service][USE:0.11s][IP:10.1.1.1][PORT:8001]启动限额服务监听
[APP-STARTED][NAME:upp-app-quota][USE:0.13s]完成启动限额模块
[SER-STARTED][NAME:upp-service-1][USE:1.01s]完成启动统一支付服务

应用关闭日志

格式与应用启动日志一致，只是STARTING和STARTED对应为STOPING和STOPED。

操作审计日志规范

操作审计日志用于记录系统用户所执行的操作，格式如下：[USER:用户ID][OP:操作标识][MOD:操作模块]操作信息描述

  • 操作模块是可选信息，视需要增加

  • 操作标识可统一定义，部分建议操作标识如下（建议统一管理）：

    • login - 登陆系统

    • logout - 签退

    • change-pwd - 修改密码

    • reset-pwd - 重置密码

    • change - 修改信息

    • add - 新增信息

    • del - 删除信息

示例如下（这里只列出标准日志头后面的内容）：

[USER:00001][OP:login]登陆系统
[USER:00001][OP:change-pwd][MOD:password]

交易日志规范

交易日志用于输出交易处理痕迹，便于分析查找问题，格式如下：

[TR:交易标识][PRD:产品标识][CID:客户标识][GSEQ:全局流水号][SEQ:流水号]交易详细信息

接口日志规范

接口日志用于输出接口调用信息，包括发送方和接收方两端的信息。

发送方日志

[INF-SEND][S-IP:服务端IP地址][S-PORT:服务端端口][SYS:目标系统标识][SEQ:接口流水号]发送报文打印信息

或

[INF-STREAM-SEND][S-IP:服务端IP地址][S-PORT:端口][SYS:目标系统标识][SEQ:接口流水号]发送流报文打印信息

正常收到返回时：

[INF-BACK][SEQ:接口流水号][USE:耗时]返回报文打印信息

或

[INF-STREAM-BACK][SEQ:接口流水号][USE:耗时]收到返回流报文打印信息

获取返回超时时：

[INF-OT][SEQ:接口流水号][USE:耗时]

获取返回网络错误时：

[INF-EX][SEQ:接口流水号][USE:耗时]异常信息（具体格式参考异常日志规范）

接收方日志

[INF-RECV][S-IP:服务端IP][S-PORT:服务端监听端口][C-IP:发起方IP地址][C-PORT:连接端口][SYS:发起方系统标识][SEQ:接口流水号]收到报文打印信息

或

[INF-STREAM-RECV][S-IP:服务端IP][S-PORT:服务端监听端口][C-IP:发起方IP地址][C-PORT:连接端口][SYS:发起方系统标识][SEQ:接口流水号]收到流报文打印信息

正常返回时：

[INF-RET][SEQ:接口流水号][USE:耗时]返回报文打印信息

或

[INF-STREAM-RET][SEQ:接口流水号][USE:耗时]返回报文打印信息

返回报文出现网络错误时：

[INF-EX][SEQ:接口流水号][USE:耗时]异常信息（具体格式参考异常日志规范）

处理流报文不返回时

[INF-STREAM-DEAL][SEQ:接口流水号][USE:耗时]处理情况打印信息

函数调用链日志规范

日志头信息项包括：

TRACE : 调用关系追踪信息，里面登记多个信息，通过冒号（“:”）分隔，按顺序依次为TRACE_ID（追踪ID）、CALL_ID（执行ID）、PARENT_CALL_ID（父调用函数的执行ID）、TRACE_LEVEL（调用层级，每CALL一个下级函数+1）、CALL_FILE（调用文件）、CALL_FUN（调用函数名）

函数调用开始日志

日志信息格式为一个JSON字符串，格式如下（日志格式会压缩，key为入参中标记业务的关键参数，para为其他关注打印参数）：

{
    "key": {
    	"key1": "value1"，
    	"key2": "value2"，
    	...
    },
    "para": {
        "para1": "value1",
        "para2": "value2",
        ...
    }
}

函数调用结束日志

日志头信息增加：

USE : 耗时，单位为秒，例如 [USE:30.345s]

日志信息格式为一个JSON字符串，格式如下（日志格式会压缩，return为返回值的str格式内容，out_para为如果有输出参数的情况下，输出参数的值）：

{
    "return": "value",
    "out_para": {
        "para1": "value1",
        "para2": "value2",
        ...
    }
}

接口调用链日志规范

接口调用链日志的日志头与接口日志一致（区分发送和接收），日志头信息项增加以下项：

TRACE-API : 接口调用关系追踪信息，里面登记多个信息，通过冒号（“:”）分隔，按顺序依次为TRACE_ID（追踪ID）、CALL_ID（执行ID）、PARENT_CALL_ID（父调用函数的执行ID）、TRACE_LEVEL（调用层级，每CALL一个下级函数+1）

可以通过工具在接口调用链日志输出时同步完成接口日志的记录（合并为1条）。

异常日志规范

当应用处理出现异常时，应输出异常日志，注意需按照预期结果确定输出日志的级别：如果异常是可忽略不处理的，日志级别要为INFO；异常无需紧急处理但需后续关注的，日志级别为WARNNING；异常必须马上应急处理的，或为预期之外的异常，日志级别必须为ERROR或者CRITICAL（灾难）。

异常日志的日志头前面部分信息项按照各类日志规范要求输出，增加异常信息项[EX:异常类名]，输出信息内容为异常的堆栈信息（trace_back）

示例如下：

[TR:交易标识][PRD:产品标识][CID:客户标识][GSEQ:全局流水号][SEQ:流水号][EX:FileExistsError]异常堆栈信息...