formatter

功能描述

Formatter主要应用于规定待记录的日志字段,在实际调用时获取指定字段的具体值以生成详细的日志内容,并将日志内容格式化成规定的格式给到output输出器进行记录

类型支持

类型说明
json将日志内容格式化为json格式进行输出
line将日志内容格式化为line格式进行输出

备注: 不同类型仅为输出不同,配置规则基本一致。

输出流程

配置规则

{
  "fields": [
    "$request_id",
    "@proxy as proxy",
    "@proxy# as proxylist"
  ],
  "proxy": [
    "$proxy_uri",
    "$proxy_scheme"
  ]
}

key

key指的是上述yaml配置中的键,如fields和proxy

说明

  1. fields配置项为默认的格式化字段列表,其他为额外的自定义引用项(如上述proxy项)
  2. 在配置内容中可以用@{key}来引用自定义引用项作为复合内容,引用效果由value元素具体定义决定
  3. 自定义引用项可以嵌套引用其它自定义引用项

value

value指的是上述yaml配置中键所对应的值,如proxy所对应的["$proxy_uri","$proxy_scheme"]

说明:

  1. value为字符串列表,每一项元素表示一个字段取值
  2. 元素格式为: ($|@){pattern}[#] as {name}(注:[]表示可选内容)
    • $ 表示取出系统可用值(系统可用值说明在本页底层)
    • @{pattern}表示引用key名为{pattern}的配置,当{pattern}在上下文中的值类型为数组时,取最后一个元素
    • @{pattern}#表示引用key名为{pattern}的配置,输出值类型为数组类型
    • 当元素不带$或@前缀时,其为常量
    • as 表示给{pattern}起别名,仅对json formatter有效,因为line输出日志不包含{pattern},仅输出{pattern}对应的系统可用值

输出规则

${pattern}

对于形如”${pattern}“或""${pattern} as {name}"的字段格式,表示直接取出指定pattern字段的系统可用值进行记录。

配置

{
  "fields": [
    "$proxy_uri",
    "$proxy_scheme as scheme",
    "$proxy_addr as addr"
  ]
}

json输出

{
    "proxy_uri":"http://127.0.0.1/api/demo",
    "scheme":"http",
    "addr":"127.0.0.1",
}

line输出

as取别名对line无效,line只会输出值。

http://127.0.0.1/api/demo	http	127.0.0.1

@{pattern}

对于形如”@{pattern}“的字段格式,表示引用名为pattern的自定义引用项,当{pattern}在上下文中的值类型为数组时,取最后一个对象元素,{pattern}的值类型为对象类型,且{pattern}应事先定义在与fields配置项同级的自定义引用项中,具体例子如下所示:

配置

{
  "fields": [
    "@proxy"
  ],
  "proxy": [
    "$proxy_uri",
    "$proxy_scheme",
    "$proxy_addr"
  ]
}

json输出

{
    "proxy":{
    	"proxy_uri":"http://127.0.0.1/api/demo",
        "proxy_scheme":"http",
        "proxy_addr":"127.0.0.1",
    }
}

line输出

"http://127.0.0.1/api/demo http 127.0.0.1"

@{pattern}#

对于形如”@{pattern}#“的字段格式,表示引用名为pattern的自定义引用项,输出为数组类型。具体例子如下所示:

配置

{
  "fields": [
    "@proxy#"
  ],
  "proxy": [
    "$proxy_uri",
    "$proxy_scheme",
    "$proxy_addr"
  ]
}

json输出

{
    "proxy":[
        {
    		"proxy_uri":"http://127.0.0.2/api/demo2",
        	"proxy_scheme":"http",
        	"proxy_addr":"127.0.0.2",
    	},
        {
    		"proxy_uri":"http://127.0.0.1/api2/demo",
        	"proxy_scheme":"http",
        	"proxy_addr":"127.0.0.1",
    	},
    ]
}

line输出

"[http://127.0.0.1/api/demo,http,127.0.0.1] [http://127.0.0.2/api2/demo2,http,127.0.0.2]"

常量pattern

当元素前缀不为$或@时,表明该元素为常量,直接取值,具体例子如下所示:

配置

{
  "fields": [
    "123",
    "abc as service_name"
  ]
}

json输出

{
    "123":"123",
    "service_name":"abc"
}

line输出

123    abc

输出示例

json

类型为json的formatter输出json格式的日志信息,自定义引用项嵌套层数没有限制。

配置示例
{
  "fields": [
    "$request_id as id",
    "@http",
    "@service as t",
    "@tmp",
    "@proxy#"
  ],
  "http": [
    "$request_method",
    "$request_uri",
    "@service",
    "@proxy",
    "@proxy# as proxylist"
  ],
  "service": [
    "abc as service_name"
  ],
  "proxy": [
    "$proxy_username",
    "$proxy_password"
  ],
  "tmp": [
    123,
    "456 as test"
  ]
}
输出示例
{
    "id":"123",
    "http":{
        "request_uri":"/path",
        "request_method":"POST",
        "service":{
            "service_name":"abc"
        },
        "proxy":{
            "proxy_username":"username2",
            "proxy_password":"password2"
        },
        "proxylist":[
            {
                "proxy_username":"username1",
                "proxy_password":"password1"
            },{
                "proxy_username":"username2",
                "proxy_password":"password2"
            }
        ]
    },
    "t":{
        "service_name":"abc"
    },
    "tmp":{
        "123":"123",
        "test":"456"
    },
    "proxy":[
        {
            "proxy_username":"username2",
            "proxy_password":"password2"
        },{
            "proxy_username":"username2",
            "proxy_password":"password2"
        }
    ]
}

line

类型为line的formatter输出line格式的日志信息,信息嵌套层数不超过三层。

line日志内容仅包含系统可用值或常量,不像json那样有明确分层和以键值对形式出现的数据,故line日志会按照下面的规则来间隔变量和分层。

  1. 每个值之间用间隔符分割

  2. 使用@时,按层次替换分隔符,且按层次使用包含符号

    • 分隔符依次为:

      i. \t

      ii. 空格

      iii. ,

      iv. |

      v. 剩下的不显示

    • 包含符号依次为

      i. ""

      ii. []

      iii. <>

  3. 空值或者超过层级部分显示为-减号。

配置示例
{
  "fields": [
    "$request_id",
    "$time_local",
    "$null_value",
    "@proxy",
    "@proxy#",
    "@tmp1"
  ],
  "tmp1": [
    "@tmp2"
  ],
  "tmp2": [
    "@proxy",
    "@proxy#"
  ],
  "proxy": [
    "$proxy_scheme",
    "$proxy_uri"
  ]
}
输出示例
0ff7692b-3833-464d-9fb9-6d24274756fe    2021-12-28 17:29:32     -       "http /demo?a=1"        "[http,/demo?a=1]"      "[<http|/demo?a=1>,<->]"

系统可用值

系统可用值定义了可供formatter使用的可选字段,具体字段和表述如下所示:

字段名称字段描述备注
node节点id
cluster集群id
application应用ID
token用户访问鉴权信息
src_ip请求源IP
src_port请求源端口
dst_ip目标IP
dst_port目标端口
query请求中query参数字段,会对键值对里的值进行url_encode编码。
query_{name}请求中query参数字段,变量名中的后半部分{name}可以替换成任意query字段,值会进行url_encode编码。
uri请求中的当前URI(不带请求参数,参数位于$args),可以不同于浏览器传递的$request_uri的值,它可以通过内部重定向,或者使用index指令进行修改,$uri不包含主机名,如"/foo/bar.html"
content_length"Content-Length" 请求头字段
content_type"Content-Type" 请求头字段
cookie请求中cookie参数字段
cookie_{name}请求中cookie参数字段,变量名中的后半部分{name},从cookie里获取值
msec当前的Unix时间戳,毫秒级别
timestamp当前的Unix时间戳,秒级别
apinto_versionapinto版本
remote_addr客户端地址
remote_port客户端端口
request_id请求id
request_body客户端的请求主体
request_length请求的长度 (包括请求的地址,http请求头和请求主体)
request_methodHTTP请求方法,通常为"GET"或"POST"
request_time处理客户端请求使用的时间,单位为秒,精度毫秒; 从读入客户端的第一个字节开始,直到把最后一个字符发送给客户端后进行日志写入为止。
request_uri这个变量等于包含一些客户端请求参数的原始URI,它无法修改,请查看$uri更改或重写URI,不包含主机名,例如:"/cnphp/test.php?arg=freemouse"
scheme请求使用的Web协议,"http" 或 "https"
statusHTTP响应状态
time_iso8601服务器时间的ISO 8601格式
time_local服务器时间(“2006-01-02 15:04:05”格式)
header所有请求头字段,按照原格式输出
headers所有请求头字段,对象类型,针对json格式输出
http_{name}匹配任意请求头字段;变量名中的后半部分name可以替换成任意请求头字段,如在配置文件中需要获取http请求头:"Accept-Language",使用$http_accept_language即可,注意:"-"需要转成"_"
host请求地址,即浏览器中你输入的地址(IP或域名,不包括端口)
proxy_header转发请求的请求头,该值按照原格式输出所有头部信息
proxy_header_{name}转发请求头部,变量名中的后半部分{name}可以替换成任意请求头字段
proxy_query转发请求的所有query参数,键值对里的值进行url encode编码。
proxy_query_{name}转发请求query参数,变量名中的后半部分{name}可以替换成任意query字段,值会进行url_encode编码。
proxy_uri转发请求的uri,不包含主机名,例如:"/cnphp/test.php?arg=freemouse"
proxy_host转发请求头部中的host
proxy_status转发请求的状态码
proxy_method转发请求的http方法
proxy_scheme转发请求的协议
proxy_path转发请求的路径,不包含query参数
proxy_body转发请求的请求体
proxy_addr上游服务的地址(IP或域名,包括端口)
proxy_dst_ip上游服务的IP
proxy_dst_port上游服务的端口
response响应数据,直接输出原格式
response_body响应体数据
response_header响应头部
response_headers响应头部,对象类型,针对json格式输出
response_header_{name}响应头部,变量名的后半部分{name}可以替换成任意header字段
response_status原始的响应状态码
response_time请求上游的响应时间,单位为毫秒,从发送请求到接收到响应最后一个字节的时间

line_formatter注意事项:

request_bodyproxy_bodyresponseresponse_body这四个参数在line_formatter格式化时会进行Base64加密。