插件-处理采集数据_数据源_Logtail采集_用户指南

实现原理

处理方式

目前支持的处理方式如下：

正则提取
标定提取
单字符分隔符
多字符分隔符
GeoIP转换
正则过滤

您也可以根据以上处理方式，为您的输入源定制组合配置。

使用说明

为采集数据配置处理方式，处理配置的key为processors，value为json object的数组，数组内每个object代表一个处理方式配置。

单一处理方式包含两个字段: type、 detail，其中 type为该处理方式的类型， detail内部为该处理方式的详细配置。

"processors" : [
        {
            "type" : "processor_anchor",
            "detail" : {
                ...
            }
        },
        {
            "type" : "processor_regex",
            "detail" : {
                ...
            }
        }
    ]

正则提取

该方式通过对指定字段进行正则表达式匹配来提取其中匹配的字段。

参数说明

正则提取方式的类型（type）为 processor_regex。


参数	类型	必选或可选	参数说明
SourceKey	string	必选	原始字段名，即需要进行正则提取的字段。
Regex	string	必选	用于匹配的正则表达式，需要提取的字段使用`()`标注，详细内容请参考维基百科。
Keys	string 数组	必选	需要提取的字段名，例如[“key1”, “key2” …]。
NoKeyError	bool	可选	默认为false，为true时若没有找到`SourceKey`字段则报错。
NoMatchError	bool	可选	默认为false，为true时若正则不匹配则报错。
KeepSource	bool	可选	默认为false，为true时匹配完后不丢弃`SourceKey`字段。
FullMatch	bool	必选	默认为true，为true时只有字段完全匹配`Regex`时才会进行提取，为false时部分字段匹配也会进行提取。

示例

配置提取Access日志，详细配置如下：

输入

"content" : "10.200.**.** - - [10/Aug/2017:14:57:51 +0800] \"POST /PutData?
Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=*******************************
 HTTP/1.1\" 0.024 18204 200 37 \"-\" \"aliyun-sdk-java"

配置详情

{
    "type" : "processor_regex",
    "detail" : {"SourceKey" : "content",
         "Regex" : "([\\d\\.]+) \\S+ \\S+ \\[(\\S+) \\S+\\] \"(\\w+) ([^\\\"]*)\" ([\\d\\.]+) (\\d+) (\\d+) (\\d+|-) \"([^\\\"]*)\" \"([^\\\"]*)\" (\\d+)",
         "Keys"   : ["ip", "time", "method", "url", "request_time", "request_length", "status", "length", "ref_url", "browser"],
         "NoKeyError" : true,
         "NoMatchError" : true,
         "KeepSource" : false
    }
}

处理后结果

"ip" : "10.200.**.**"
"time" : "10/Aug/2017:14:57:51"
"method" : "POST"
"url" : "/PutData?Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=*******************************"
"request_time" : "0.024"
"request_length" : "18204"
"status" : "200"
"length" : "27"
"ref_url" : "-"
"browser" : "aliyun-sdk-java"

标定提取

该方式通过标定指定字段起始和结束关键字进行提取，标定后的字符串支持直接提取和JSON展开方式。

参数说明

标定提取方式的类型（type）为 processor_anchor。


参数	类型	必选或可选	参数说明
SourceKey	string	必选	原始字段名，即需要进行提取的字段。
Anchors	Anchor 数组	必选	标定项列表，具体参见下述表格。
NoAnchorError	bool	可选	默认为false，为true时若查找不到关键字则报错。
NoKeyError	bool	可选	默认为false，为true时若没有找到`SourceKey`字段则报错。
KeepSource	bool	可选	默认为false，为true时匹配完后不丢弃`SourceKey`字段。

Anchor类型说明


参数	类型	必选或可选	参数说明
Start	string	必选	起始关键字，若为空则代表匹配字符串开头。
Stop	string	必选	结束关键字，若为空则代表匹配字符串结尾。
FieldName	string	必选	提取的字段名。
FieldType	string	必选	提取字段类型，支持”string”、”json”两种类型。
ExpondJson	bool	可选	默认为false，为true且`FieldType`为`json`时将提取的json逐层展开。
ExpondConnecter	string	可选	JSON展开的连接符，默认为`_`。
MaxExpondDepth	int	可选	JSON展开最大深度，默认为`0`（无限制）。

示例

如下配置对某混合类型输入的处理结果如下：

输入

"content" : "time:2017.09.12 20:55:36\tjson:{\"key1\" : \"xx\", \"key2\": false, \"key3\":123.456, \"key4\" : { \"inner1\" : 1, \"inner2\" : false}}"

配置详情

{
   "type" : "processor_anchor",
   "detail" : {"SourceKey" : "content",
      "Anchors" : [
          {
              "Start" : "time",
              "Stop" : "\t",
              "FieldName" : "time",
              "FieldType" : "string",
              "ExpondJson" : false
          },
          {
              "Start" : "json:",
              "Stop" : "",
              "FieldName" : "val",
              "FieldType" : "json",
              "ExpondJson" : true 
          }
      ]
  }
}

处理后结果

"time" : "2017.09.12 20:55:36"
"val_key1" : "xx"
"val_key2" : "false"
"val_key3" : "123.456"
"value_key4_inner1" : "1"
"value_key4_inner2" : "false"

单字符分隔符

该方式通过指定分隔符对字段进行分割，可指定Quote进行分隔符屏蔽。

参数说明

单字分隔符方式的类型（type）为 processor_split_char。


参数	类型	必选或可选	参数说明
SourceKey	string	必选	原始字段名，即需要进行提取的字段。
SplitSep	string	必选	分隔符，必须为单字符，可以设置不可见字符，例如`\u0001`。
SplitKeys	string 数组	必选	切分后的字段名，例如[“key1”, “key2”…]。
QuoteFlag	bool	可选	默认为false，为true时代表使用quote。
Quote	string	可选	必须为单字符，QuoteFlag为true时生效，可以设置不可见字符，例如`\u0001`。
NoKeyError	bool	可选	默认为false，为true时若没有找到`SourceKey`字段则报错。
NoMatchError	bool	可选	默认为false，为true时若切分。
KeepSource	bool	可选	默认为false，为true时匹配完后不丢弃`SourceKey`字段。

示例

对分隔符数据输入配置单字符分隔符处理方式，配置详情及处理结果如下：

输入

"content" : "10.**.**.**|10/Aug/2017:14:57:51 +0800|POST|PutData?
Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=**************************|0.024|18204|200|37|-|
aliyun-sdk-java"

配置详情

{
   "type" : "processor_split_char",
   "detail" : {"SourceKey" : "content",
      "SplitSep" : "|",
      "SplitKeys" : ["ip", "time", "method", "url", "request_time", "request_length", "status", "length", "ref_url", "browser"]     
  }
}

处理后结果

"ip" : "10.**.**.**"
"time" : "10/Aug/2017:14:57:51 +0800"
"method" : "POST"
"url" : "/PutData?Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=********************************"
"request_time" : "0.024"
"request_length" : "18204"
"status" : "200"
"length" : "27"
"ref_url" : "-"
"browser" : "aliyun-sdk-java"

多字符分隔符

和单字符分隔符类似，多字符分隔符不支持Quote，完全按照分隔符拆分日志。

参数说明

多字符分隔符方式类型（type）为processor_split_string。


参数	类型	必选或可选	参数说明
SourceKey	string	必选	原始字段名，即需要进行提取的字段。
SplitSep	string	必选	分隔符，可以设置不可见字符，例如`\u0001\u0002`。
SplitKeys	string 数组	必选	切分后的字段名，例如[“key1”, “key2”…]。
PreserveOthers	bool	可选	默认为false, 为true时若分割的字段大于`SplitKeys`长度会保留超出部分。
ExpandOthers	bool	可选	默认为false，为true时继续解析超出部分。
ExpandKeyPrefix	string	可选	超出部分命名前缀，例如配置的`expand_`，则key为`expand_1`、`expand_2` 。
NoKeyError	bool	可选	默认为false，为true时若没有找到`SourceKey`字段则报错。
NoMatchError	bool	可选	默认为false，为true时若切分。
KeepSource	bool	可选	默认为false，为true时匹配完后不丢弃`SourceKey`字段。

示例

对分隔符数据输入采用多字符分隔符方式处理，配置详情及处理结果如下：

输入

"content" : "10.**.**.**|#|10/Aug/2017:14:57:51 +0800|#|POST|#|PutData?
Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=********************************|#|0.024|#|18204|#|200|#|37|#|-|#|
aliyun-sdk-java"

配置详情

{
   "type" : "processor_split_string",
   "detail" : {"SourceKey" : "content",
      "SplitSep" : "|#|",
      "SplitKeys" : ["ip", "time", "method", "url", "request_time", "request_length", "status"],
      "PreserveOthers" : true,
      "ExpandOthers" : true,
      "ExpandKeyPrefix" : "expand_"
  }
}

处理后结果

"ip" : "10.**.**.**"
"time" : "10/Aug/2017:14:57:51 +0800"
"method" : "POST"
"url" : "/PutData?Category=YunOsAccountOpLog&AccessKeyId=******************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=*******************************"
"request_time" : "0.024"
"request_length" : "18204"
"status" : "200"
"expand_1" : "27"
"expand_2" : "-"
"expand_3" : "aliyun-sdk-java"

GeoIP转换

GeoIP转换对数据输入中的IP进行地理位置转换，能够将IP转换成：国家、省份、城市、经纬度。

	说明
	Logtail安装包本身并不带有GeoIP的数据库，需要您手动下载到本地并配置，建议下载精确到`City`的数据库。

参数说明

GeoIP转换插件类型（type）为processor_geoip。


参数	类型	必选或可选	参数说明
SourceKey	string	必选	原始字段名，即需要进行IP转换的字段。
DBPath	string	必选	GeoIP数据库的全路径，数据库格式为`mmdb`，例如`/user/data/GeoLite2-City_20180102/GeoLite2-City.mmdb`。
NoKeyError	bool	可选	默认为false，为true时若没有找到`SourceKey`字段则报错。
NoMatchError	bool	可选	默认为false，为true时若IP地址无效或数据库中未匹配到该IP则上报错误。
KeepSource	bool	可选	默认为true，为false时转换完毕后丢弃`SourceKey`字段。
Language	string	可选	语言，默认为`zh-CN`，需确保您的GeoIP数据库中包含相应的语言。

示例

对输入的IP采用GeoIP转换成地理位置信息，配置详情及处理结果如下：

输入
```
"source_ip" : "**.**.**.**"
```
下载GeoIP数据库下载GeoIP数据库到安装Logtail的主机，例如可使用 MaxMind GeoLite2中的 City数据库

说明

请检查数据库格式为mmdb类型。

配置详情

{
   "type": "processor_geoip",
    "detail": {
         "SourceKey": "ip",
         "NoKeyError": true,
         "NoMatchError": true,
         "KeepSource": true,
         "DBPath" : "/user/local/data/GeoLite2-City_20180102/GeoLite2-City.mmdb"
    }
}

配置后结果

"source_ip_city_" : "**.**.**.**"
"source_ip_province_" : "浙江省"
"source_ip_city_" : "杭州"
"source_ip_province_code_" : "ZJ"
"source_ip_country_code_" : "CN"
"source_ip_longitude_" : "120.********"
"source_ip_latitude_" : "30.********"

正则过滤

该方式通过对字段进行正则表达式匹配过滤日志，可组合使用Include和Exclude两种方式。

参数说明

正则过滤方式的类型（type）为processor_filter_regex。


参数	类型	必选或可选	参数说明
Include	key:string value:string 的map	可选	key为日志字段，value为该字段匹配的正则表达式，若指定字段符合该表达式，则该条日志被收集。
Exclude	key:string value:string 的map	可选	key为日志字段，value为该字段匹配的正则表达式，若指定字段符合该表达式，则该条日志不被收集。

	说明
	一条日志只有完全被`Include`中的参数匹配，且不被`Exclude`中的任一参数匹配时才会被采集，否则直接丢弃。

示例

对输入日志采正则过滤方式处理，配置详情及处理结果如下：

输入

日志1

"ip" : "10.**.**.**"
"method" : "POST"
...
"browser" : "aliyun-sdk-java"

日志2

"ip" : "10.**.**.**"
"method" : "POST"
...
"browser" : "chrome"

日志3

"ip" : "192.168.*.*"
"method" : "POST"
...
"browser" : "ali-sls-ilogtail"

配置详情

{
   "type" : "processor_filter_regex",
    "detail" : {
         "Include" : {
            "ip" : "10\\..*",
            "method" : "POST"
         },
         "Exclude" : {
            "browser" : "aliyun.*"
         }
    }
}

处理后结果


日志	是否匹配	原因
日志1	不匹配	browser匹配上了Exclude。
日志2	匹配	-
日志3	不匹配	Include中”ip”字段不匹配，不以”10”开头。

组合配置

各个处理配置可以组合搭配使用。您可以参考下述配置对日志先进行分隔符切分后，再对切分后的detail进行标定提取。

输入

"content" : 
"ACCESS|QAS|11.**.**.**|1508729889935|52460dbed4d540b88a973cf5452b1447|1238|appKey=ba,env=pub,requestTime=1508729889913,latency=22ms,
request={appKey:ba,optional:{\\domains\\:\\daily\\,\\version\\:\\v2\\},rawQuery:{\\query\\:\\去乐山的路线\\,\\domain\\:\\导航\\,\\intent\\:\\navigate\\,\\slots\\:\\to_geo:level3=乐山\\,\\location\\:\\北京\\},
requestId:52460dbed4d540b88a973cf5452b1447},
response={answers:[],status:SUCCESS}|"

配置详情

"processors" : [
      {
          "type" : "processor_split_char",
          "detail" : {"SourceKey" : "content",
              "SplitSep" : "|",
              "SplitKeys" : ["method", "type", "ip", "time", "req_id", "size", "detail"]
          }
      },
      {
          "type" : "processor_anchor",
          "detail" : "SourceKey" : "detail",
              "Anchors" : [
                  {
                          "Start" : "appKey=",
                      "Stop" : ",env=",
                      "FieldName" : "appKey",
                      "FieldType" : "string"
                  },
                  {
                      "Start" : ",env",
                      "Stop" : ",requestTime=",
                      "FieldName" : "env",
                      "FieldType" : "string"
                  },
                  {
                      "Start" : ",requestTime=",
                      "Stop" : ",latency",
                      "FieldName" : "requestTime",
                      "FieldType" : "string"
                  },
                  {
                      "Start" : ",latency=",
                      "Stop" : ",request=",
                      "FieldName" : "latency",
                      "FieldType" : "string"
                  },
                  {
                      "Start" : ",request=",
                      "Stop" : ",response=",
                      "FieldName" : "request",
                      "FieldType" : "string"
                  },
                  {
                      "Start" : ",response=",
                      "Stop" : "",
                      "FieldName" : "response",
                      "FieldType" : "json"
                  }
              ]
          }
      }
  ]

处理后结果

"method" : "ACCESS"
"type" : "QAS"
"ip" : "**.**.**.**"
"time" : "1508729889935"
"req_id" : "52460dbed4d540b88a973cf5452b1447"
"size" : "1238"
"appKey" : "ba"  
"env" : "pub"
"requestTime" : "1508729889913"
"latency" : "22ms"
"request" : "{appKey:nui-banma,optional:{\\domains\\:\\daily-faq\\,\\version\\:\\v2\\},rawQuery:{\\query\\:\\\345\216\273\344\271\220\345\261\261\347\232\204\350\267\257\347\272\277\\,\\domain\\:\\\345\257\274\350\210\252\\,\\intent\\:\\navigate\\,\\slots\\:\\to_geo:level3=\344\271\220\345\261\261\\,\\location\\:\\\345\214\227\344\272\254\\},requestId:52460dbed4d540b88a973cf5452b1447}"  
"response_answers" : "[]"
"response_status" : "SUCCESS"

	说明
	目前数据处理配置只适用于Binlog、MySQL查询结果、Nginx监控和HTTP输入源。

	说明
	请检查数据库格式为mmdb类型。