一、前言
本文档为监控系统服务日志技术规范修订版,明确了日志信息输出的规范要求,方便系统设计人员和开发人员使用。
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_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)固定日志头
- 固定日志头必须包括三个域:[日志级别][时间戳][扩展区域] ,且各个域中不允许出现空格。
- 日志级别包括 FATAL,WARNING,NOTICE,TRACE,DEBUG。
- 时间戳格式要求:yyyy-MM-ddTHH:mm:ss.SSSZ 带有毫秒,带有时区,日期与时间通过字母T分隔(eg: 2022-12-02T00:00:07.099+0800)。
- 扩展区域用户可以自行定义,大部分场景用来打印“代码行/类名/函数名”。
2)数据标签LOGTAG
- 用来标识该条日志记录的内容以及日志中能获得的字段信息
- 业务日志中的LOGTAG必须以下划线(_)为前缀,防止重复。公司级的LOGTAG统一使用_com_为前缀,例如_com_request_in,_com_request_out,_com_http_success 。
- 每个部门可以设置自己的LOGTAG用来做记录业务相关annotation,如:_guanwang_(官网),_base_(基础服务部)。
- LOGTAG的默认值为_undef,没有具体含义的日志或者无需定义专门LOGTAG的日志可以使用默认值。
3)KV字段列表
- 包含结构化的key与value数据,各个key/value组合以双竖线(||)分隔。
- key与value之间使用等号(=)链接。
- key/value的字段内容中需要避免出现双竖线,key的内容中需要避免出现等号,如果出现,可以通过日志组件进行自动转义。
- 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);