监控系统服务日志规范 - 思路参考

一、前言

本文档为监控系统服务日志技术规范修订版，明确了日志信息输出的规范要求，方便系统设计人员和开发人员使用。

ps现状: 公司各部门都有自己的日志规范，存在规范不统一，接入不统一，监控大盘，报警模版不统一的痛点。在日志接入，大盘创建，报警添加方面存在耗时耗力且效果不好的问题

二、Nginx日志规范

1、日志格式要求

#access 格式 配置
log_format json escape=json '{'
'"trace_id": "$trace_id", ' 
'"request_length": "$request_length", ' 
'"remote_addr": "$remote_addr", ' 
'"remote_user": "$remote_user", '  
'"time_local": "$time_local", '
'"time_iso8601": "$time_iso8601", ' 
'"request": "$request", ' 
'"args": "$args", ' 
'"status": "$status", ' 
'"body_bytes_sent": "$body_bytes_sent", ' 
'"bytes_sent": "$bytes_sent", ' 
'"http_referer": "$http_referer", ' 
'"http_user_agent": "$http_user_agent", ' 
'"http_x_forwarded_for": "$http_x_forwarded_for", '
'"http_host": "$http_host", ' 
'"server_name": "$server_name", ' 
'"request_time": "$request_time", ' 
'"request_method": "$request_method", ' 
'"server_protocol": "$server_protocol", '
'}';

 access_log  /var/log/nginx/access-json.log json buffer=64k flush=5s;

2、日志重要参数说明

参数	说明	举例
$remote_addr	来访客户端的ip地址(代理服务器，显示代理服务ip)	10.92.22.11
$remote_user	来访客户端的用户名称（一般为“-”）	-
$time_iso8601	ISO 8601 标准时间格式	2022-09-08T18:16:03+8:00
$time_local	访问时间和时区	[26/Sep/2022:17:05:59 +0800]
$request	请求的url以及请求方法	GET / HTTP/1.1
$status	响应状态码	200
$body_bytes_sent	给客户端发送的文件主体内容字节数	675
$http_referer	HTTP 头信息 Referer	http://10.92.22.11:9999/
$http_user_agent	用户所使用的代理（一般为浏览器）	Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36
$http_x_forwarded_for	可以记录客户端IP，通过代理服务器来记录客户端的ip地址	10.92.22.11
$request_time	请求处理时间（单位s,小数点精确到ms） 从读入客户端的第一个字节开始，直到把最后一个字符发送给客户端后	600
$request_legth	请求包体长度（字节） (包括 request_line, header, body)	8821
$args	请求参数
$http_host	请求 Host url或者header中获取

三、Runtime业务日志规范

1、日志编码

信息系统日志字符集均需设定为 UTF-8 编码。

2、日志命名

runtime.log.yyyymmddhh info debug 级别

runtime.log.wf.yyyymmddhh fatal、error、warning级别

trace.log.yyyymmddhh trace 级别

3、日志切割

日志每小时一个文件

runtime.log.yyyymmddhh => runtime.log.2022101104

对应日期 20221011 4:00:00 - 20221011 4:59:59.999

4、日志内容

[NOTICE][2016-03-28T12:29:20.999+0800][line=/home/busi/application/v1/helpers/log_helper.php +442 class=? function=::log_request] _com_request_in||traceid=0af289a156f8b3200e6f5344345e7e02||spanid=f4b6a0ec58a4f503||cspanid=5df56b99411f4fab||logid=408994954500||uri=/busi/v1/wxpayinterface/jsSDKSign||url=/busi/v1/wxpayinterface/jsSDKSign||from=10.242.154.79||house_id=12234||broker_id=23453||is_testing_user=0

1、格式描述

单条日志分为三个部分：“固定日志头数据标签LOGTAG||KV字段列表”

“固定日志头” 和 “LOGTAG”之间用“空格( )”进行区分

“LOGTAG”和“KV列表“之间用“双竖线(||)”分隔

2、格式说明

1）固定日志头

1. 固定日志头必须包括三个域：[日志级别][时间戳][扩展区域] ，且各个域中不允许出现空格。
2. 日志级别包括 FATAL，WARNING，NOTICE，TRACE，DEBUG。
3. 时间戳格式要求：yyyy-MM-ddTHH:mm:ss.SSSZ 带有毫秒，带有时区，日期与时间通过字母T分隔（eg: 2022-12-02T00:00:07.099+0800）。
4. 扩展区域用户可以自行定义，大部分场景用来打印“代码行/类名/函数名”。

2）数据标签LOGTAG

1. 用来标识该条日志记录的内容以及日志中能获得的字段信息
2. 业务日志中的LOGTAG必须以下划线（_）为前缀，防止重复。公司级的LOGTAG统一使用_com_为前缀，例如_com_request_in，_com_request_out，_com_http_success 。
3. 每个部门可以设置自己的LOGTAG用来做记录业务相关annotation，如：_guanwang_（官网），_base_（基础服务部）。
4. LOGTAG的默认值为_undef，没有具体含义的日志或者无需定义专门LOGTAG的日志可以使用默认值。

3）KV字段列表

1. 包含结构化的key与value数据，各个key/value组合以双竖线（||）分隔。
2. key与value之间使用等号（=）链接。
3. key/value的字段内容中需要避免出现双竖线，key的内容中需要避免出现等号，如果出现，可以通过日志组件进行自动转义。
4. key的默认值为_msg，没有具体含义的key可以使用默认值，一般搭配_undef的数据标签使用。相同含义的key要求使用相同的名称，例如order_id。

5 、通用参数列表

1、日志公共参数列表

参数名称	描述	示例
traceid	链路traceid	0af289a156f8b3200e6f5344345e7e02
spanid	spanid	f4b6a0ec58a4f503
cspanid	childspanid	5df56b99411f4fab
errno	错误码	0
module_name	模块名	panguan
urlkey	请求uri	/commute/getcommute

2、日志非公共参数列表

参数名称	描述	示例
ip	源ip地址	36.112.25.131
ua	ua	Mozilla/5.0
model	手机型号	MAR-AL00
version	app版本	1.0
proc_time	处理时长	0.434759
total_time	总时长	0.434756
namelookup_time	名字解析花费时间	0.10403
pretransfer_time	从开始到文件传输开始的时间	0.151865
startransfer_time	从请求开始到传输第一个字节花费的时间	0.274500
redirect_time	重定向花费的时间	0.000
appconnect_time	建立链接的时间	0.151536
http_method	http方法	get,post,put
host	下游服务ip地址	10.10.14.309
order_id	订单id	220416342
is_test_user	是否是测试用户	0
is_pressure_traffic	是否是压测流量	0
http_code	http错误码	502
uid	用户id	1175256554
event_id	事件id	11345744

6 、补充描述

1、关于网络请求耗时的描述

较为详细的请求耗时数据可用来分析请求各个阶段的情况，如判断是否DNS解析慢，后者建立连接慢，或者传输慢

示例： 访问 http://www.xiaofenglang.com/ 各阶段请求分析

curl -o /dev/null  -w "\ntime_namelookup:%{time_namelookup}\ntime_connect:%{time_connect}\ntime_appconnect:%{time_appconnect}\ntime_redirect:%{time_redirect}\ntime_pretransfer:%{time_pretransfer}\ntime_starttransfer:%{time_starttransfer}\ntime_total:%{time_total}\nspeed_download:%{speed_download}\n" http://www.xiaofenglang.com/

2、业务方使用问题

基础组后续会提供SDK或者jar包，在提供之前可以按照上述规范打印日志，字段可以不全，格式保持一一致。日志SDK及文档后续提供。

上述描述的通用参数，SDK会自动打印，业务无需关注。业务可以补充自己所需的key value数据，但不能和已有的通用参数名称重复。

集成SDK包后，调用方式形如：

/**
 * 打印info级别日志，PHP示例
 * @param $errno int 错误码
 * @param $message string 自定义错误信息，成功一般为 success
 * @param $arrData array 自定义KV信息,MAP类型（php中用array表示）
 * @return void
 */
public function Info($errno, $message = 'success', $arrData = []) {
    //something
}

调用：
WLog:info($errno, $mesage, $arrData);