你的位置:首页 > 数据库

[数据库]Logstash 2.2 mutate 插件【翻译+实践】


官网地址

本文内容

  • 语法
  • 测试数据
  • 可选配置项

mutate 插件可以在字段上执行变换,包括重命名、删除、替换和修改。这个插件相当常用。

比如:

  • 你已经根据 Grok 表达式将 Tomcat 日志的内容放到各个字段中,想把状态码、字节大小或是响应时间,转换成整型;
  • 你已经根据正则表达式将日志内容放到各个字段中,但是字段的值,大小写都有,这对于 Elasticsearch 的全文检索来说,显然用处不大,那么可以用该插件,将字段内容全部转换成小写。

语法


该插件必须是用 mutate 包裹,如下所示:

mutate {}


可用的配置选项如下表所示:

设置 输入类型 是否必填 默认值
add_field hash No {}
add_tag array No []
convert hash No  
gsub array No  
join hash No  
lowercase array No  
merge hash No  
periodic_flush boolean No false
remove_field array No []
remove_tag array No []
rename hash No  
replace hash No  
split hash No  
strip array No  
update hash No  
uppercase array No  

其中,add_field、remove_field、add_tag、remove_tag 是所有 Logstash 插件都有。它们在插件过滤成功后生效。虽然 Logstash 叫过滤,但不仅仅过滤功能。

tag 作用是,当你对字段处理期间,还期望进行后续处理,就先作个标记。Logstash 有个内置 tags 数组,包含了期间产生的 tag,无论是 Logstash 自己产生的,还是你添加的,比如,你用 grok 解析日志,但是错了,那么 Logstash 自己就会自己添加一个 _grokparsefailure 的 tag。这样,你在 output 时,可以对解析失败的日志不做任何处理;

而 field 作用是,对字段的操作,比如,你想利用已有的字段,创建新的字段。这些在后面再说。

另外,你会发现,上表中所有选项,要么是动词,要么是动宾短语。估计你也猜到了,选项其实就是 ruby 函数,而它们后面,即“=>”,跟着的肯定是一堆参数(要是你写程序,你也会这么干)。第一个参数,肯定是字段,也就是你期望该函数作用在哪个字段上,从第二个字段开始往后,是具体参数~

什么是字段?比如,你想解析 Tomcat 日志,把一行访问日志拆分后,得到客户端IP、字节大小、响应时间等放到指定变量,那么这个变量就是字段。

下面具体介绍各个选项。

测试数据


假设有 Tomcat access 日志:

192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET "/goLogin" "" 8080 200 1692 23 "http://10.1.8.193:8080/goMain" "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0"
192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET "/js/common/jquery-1.10.2.min.js" "" 8080 304 - 67 "http://10.1.8.193:8080/goLogin" "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0"
192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET "/css/common/login.css" "" 8080 304 - 75 "http://10.1.8.193:8080/goLogin" "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0"
192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET "/js/system/login.js" "" 8080 304 - 53 "http://10.1.8.193:8080/goLogin" "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0"


它是按如下 Tomcat 配置产生的:

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
        prefix="localhost_access_log." suffix=".txt"
        pattern="%h %l %u %t %m &quot;%U&quot; &quot;%q&quot; %p %s %b %D &quot;%{Referer}i&quot; &quot;%{User-Agent}i&quot;" />


若用如下 Grok 表达式解析该日志:

%{IPORHOST:clientip} %{NOTSPACE:identd} %{NOTSPACE:auth} \[%{HTTPDATE:timestamp}\] %{WORD:http_method} %{NOTSPACE:request} %{NOTSPACE:request_query|-} %{NUMBER:port} %{NUMBER:statusCode} (%{NOTSPACE:bytes}|-) %{NUMBER:reqTime} %{QS:referer} %{QS:userAgent}


会得到如下结果:

{
     "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
     "@version" => "1",
    "@timestamp" => "2016-05-17T08:26:07.794Z",
       "host" => "vcyber",
     "clientip" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => "8080",
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\""
}


注意,日志拆分到各个字段后的数据类型。port、statusCode、bytes、reqTime 字段肯定是(最好是)数字,不过这里暂时先用字符串。后面会介绍,下面的示例都在此基础上。

可配置选项


add_field

  • 值是散列,就是键值对,比如 add_field => 值。
  • 默认值是空对象,即 {}

添加新的字段。

示例:

input {
    stdin {
    }
}
filter {
    grok {
        match=>["message","%{IPORHOST:clientip} %{NOTSPACE:identd} %{NOTSPACE:auth} \[%{HTTPDATE:timestamp}\] %{WORD:http_method} %{NOTSPACE:request} %{NOTSPACE:request_query|-} %{NUMBER:port} %{NUMBER:statusCode} (%{NOTSPACE:bytes}|-) %{NUMBER:reqTime} %{QS:referer} %{QS:userAgent}"]
    }
    mutate {
        add_field=>{
             "SayHi"=>"Hello , %{clientip}"
        }
    }
}
output{
    stdout{
        codec=>rubydebug
    }
}


注意黑体部分,如果用这个配置,解析前面的 Tcomat access 日志,会得到如下结果:
{
     "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
     "@version" => "1",
    "@timestamp" => "2016-05-17T04:52:02.031Z",
       "host" => "vcyber",
     "clientip" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => "8080",
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
      "SayHi" => "Hello , 192.168.6.25"
}


你会看到多了一个 SayHi 字段。这个字段是写死的,当然也可以动态。如果将
"SayHi"=>"Hello , %{clientip}"


改成:
"another_%{clientip}"=>"Hello , %{clientip}" 


你会看到如下结果:
{
         "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
        "@version" => "1",
       "@timestamp" => "2016-05-17T06:38:04.427Z",
          "host" => "vcyber",
        "clientip" => "192.168.6.25",
         "identd" => "-",
          "auth" => "-",
        "timestamp" => "24/Apr/2016:01:25:53 +0800",
       "http_method" => "GET",
         "request" => "\"/goLogin\"",
      "request_query" => "\"\"",
          "port" => "8080",
       "statusCode" => "200",
          "bytes" => "1692",
         "reqTime" => "23",
         "referer" => "\"http://10.1.8.193:8080/goMain\"",
        "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
  "another_192.168.6.25" => "Hello , 192.168.6.25"
}


虽然这个例子不太合理,但你现在知道,用已有字段的值,可以生成新的字段和它的值。
上面示例只添加了一个字段,你也可以添加多个字段:
add_field=>{
    "another_%{clientip}"=>"Hello , %{clientip}"
    "another_%{http_method}"=>"Hello, %{http_method}"
}


add_tag

  • 值是 array 数组
  • 默认值为空数组,即 []

添加新的标签。

示例:

mutate {
    add_tag=>[
        "foo_%{clientip}"
    ]
}


你会看到如下结果:
{
     "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
     "@version" => "1",
    "@timestamp" => "2016-05-17T06:48:43.278Z",
       "host" => "vcyber",
     "clientip" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => "8080",
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
       "tags" => [
    [0] "foo_192.168.6.25"
  ]
}


与 add_field 类似,也可以一次添加多个 tags。
注意,add_tag 是数组 [],不是 {}。

convert

  • 值是 hash
  • 无默认值

数据类型转换。

如果要转换成 boolean,那么可接受的数据是:

  • true, t, yes, y, 和 1
  • false, f, no, n, 和 0

另外,还可转换成 integer, float, string。

示例:

mutate {
    #convert=>["reqTime","integer","statusCode","integer","bytes","integer"]
    convert=>{"port"=>"integer"}
}


convert 有两种写法。一种是用数组,两个为一组;另一种是散列。得到如下结果:

{
     "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
     "@version" => "1",
    "@timestamp" => "2016-05-17T09:06:25.360Z",
       "host" => "vcyber",
     "clientip" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => 8080,
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\""
}


注意,

  • port 字段,已经没有双引号啦。
  • mutate 插件选项的值类型设计得很简单,要么是散列(键值对),要么数组……比如,convert=>["reqTime","integer","statusCode","integer"],两个为一组,第一个表示字段,第二个为想转换的数据类型,并没有采用嵌套或是复合类型。看来作者的意图是——简单,复杂的数据类型,虽然看起来容易,但要付出成本的。简单没关系,约定好就行。Logstash 很多插件和其选项都这样。

gsub

  • 值是 array 数组
  • 无默认值

字符串替换。用正则表达式和字符串都行。它只能用于字符串,如果不是字符串,那么什么都不会做,也不会报错。

该配置的值是数组,三个为一组,分别表示:字段名称,待匹配的字符串(或正则表达式),待替换的字符串。

示例:在解析 Tomcat 日志,会遇到一种情况,资源的字节大小,可能会是“-”,因此,需要将“-”,替换成0,然后在用convert转换成数字型。

input {
    stdin {
    }    
}
filter {
    grok {
        match=>["message","%{IPORHOST:clientip} %{NOTSPACE:identd} %{NOTSPACE:auth} \[%{HTTPDATE:timestamp}\] %{WORD:http_method} %{NOTSPACE:request} %{NOTSPACE:request_query|-} %{NUMBER:port} %{NUMBER:statusCode} (%{NOTSPACE:bytes}|-) %{NUMBER:reqTime} %{QS:referer} %{QS:userAgent}"]
    }
    mutate {
        gsub=>["bytes","_","0"]
        convert=>["port","integer","reqTime","integer","statusCode","integer","bytes","integer"]
    }
}
output{
    stdout{
        codec=>rubydebug
    }
}


得到如下结果:

{
     "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/js/common/jquery-1.10.2.min.js\" \"\" 8080 304 - 67 \"http://10.1.8.193:8080/goLogin\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
     "@version" => "1",
    "@timestamp" => "2016-05-17T09:17:21.745Z",
       "host" => "vcyber",
     "clientip" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/js/common/jquery-1.10.2.min.js\"",
  "request_query" => "\"\"",
       "port" => 8080,
    "statusCode" => 304,
      "bytes" => 0,
     "reqTime" => 67,
     "referer" => "\"http://10.1.8.193:8080/goLogin\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\""
}


join

  • 值是 hash
  • 无默认值

用分隔符连接数组. 如果字段不是数组,那什么都不做。

示例:

filter { mutate {  join =>{"fieldname"=>","}}}

lowercase 和 uppercase

  • 值是数组 array
  • 没有默认值

把字符串转换成小写或大写。

示例:

filter {
 mutate {
  lowercase =>["fieldname"]}}


示例:

filter {
 mutate {
  uppercase =>["fieldname"]}}


merge

  • 值是 hash
  • 无默认值

合并两个数组或散列字段。存在三种情况,合并后是数组:

  • 数组和字符串,可以合并
  • 字符串和字符串,可以合并
  • 数组和散列不能合并

示例:

mutate {
    add_field=>{"arr_clientip"=>"%{clientip}"}
    add_field=>{"arrmstr_clientip"=>"%{clientip}"}
    add_field=>{"arrmarr_clientip"=>"%{clientip}"}
    #merge=>{"merge_clientip"=>"clientip"}
}
mutate {
    split=>{"arr_clientip"=>"."}
    split=>{"arrmstr_clientip"=>"."}
    split=>{"arrmarr_clientip"=>"."}
}
mutate {
    merge=>{"arrmstr_clientip"=>"clientip"}
    merge=>{"arrmarr_clientip"=>"arr_clientip"}
}


=> 后面的字段值会合并到前面的字段。
得到如下结果:
{
       "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
      "@version" => "1",
     "@timestamp" => "2016-05-18T02:53:35.671Z",
        "host" => "vcyber",
      "clientip" => "192.168.6.25",
       "identd" => "-",
        "auth" => "-",
      "timestamp" => "24/Apr/2016:01:25:53 +0800",
     "http_method" => "GET",
       "request" => "\"/goLogin\"",
    "request_query" => "\"\"",
        "port" => "8080",
     "statusCode" => "200",
        "bytes" => "1692",
       "reqTime" => "23",
       "referer" => "\"http://10.1.8.193:8080/goMain\"",
      "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
    "arr_clientip" => [
    [0] "192",
    [1] "168",
    [2] "6",
    [3] "25"
  ],
  "arrmstr_clientip" => [
    [0] "192",
    [1] "168",
    [2] "6",
    [3] "25",
    [4] "192.168.6.25"
  ],
  "arrmarr_clientip" => [
    [0] "192",
    [1] "168",
    [2] "6",
    [3] "25",
    [4] "192",
    [5] "168",
    [6] "6",
    [7] "25"
  ]
}


periodic_flush

  • 值是 boolean
  • 默认值是 false

按时间间隔调用。可选。

remove_field

  • 值是数组 array
  • 默认值是数组 []

移除字段。

示例:移除 message 字段。

mutate {
    remove_field=>["message"]
}


得到如下结果:

{
     "@version" => "1",
    "@timestamp" => "2016-05-18T02:04:16.879Z",
       "host" => "vcyber",
     "clientip" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => "8080",
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\""
}


message 字段已经没有了~message 字段保存了原始日志,如果保留的话,就意味着日志存了两份:分割前和分割后。

当然,也可以一次移除多个字段。

remove_tag

  • 值是数组 array
  • 默认值是 []

移除标识。

示例:

filter {
 mutate {
  remove_tag =>["foo_%{somefield}"]}}


也可以一次移动多个 tag:
filter {
 mutate {
  remove_tag =>["foo_%{somefield}","sad_unwanted_tag"]}}


rename

  • 值是 hash
  • 无默认值

重命名一个或多个字段。

示例:

input {
    stdin {
    }    
}
filter {
    grok {
        match=>["message","%{IPORHOST:clientip} %{NOTSPACE:identd} %{NOTSPACE:auth} \[%{HTTPDATE:timestamp}\] %{WORD:http_method} %{NOTSPACE:request} %{NOTSPACE:request_query|-} %{NUMBER:port} %{NUMBER:statusCode} (%{NOTSPACE:bytes}|-) %{NUMBER:reqTime} %{QS:referer} %{QS:userAgent}"]
    }
    mutate {
        rename=>{"clientip"=>"host"}
    }
}
output{
    stdout{
        codec=>rubydebug
    }
}


得到如下结果:

{
     "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
     "@version" => "1",
    "@timestamp" => "2016-05-17T09:29:44.018Z",
       "host" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => "8080",
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\""
}


Grok 里,客户端IP本来叫 clientip,但是可以在 mutate 里重新命名为 host。

replace

  • 值是 hash
  • 无默认值

用一个新的值替换掉指定字段的值。

示例:

input {
    stdin {
    }    
}
filter {
    grok {
        match=>["message","%{IPORHOST:clientip} %{NOTSPACE:identd} %{NOTSPACE:auth} \[%{HTTPDATE:timestamp}\] %{WORD:http_method} %{NOTSPACE:request} %{NOTSPACE:request_query|-} %{NUMBER:port} %{NUMBER:statusCode} (%{NOTSPACE:bytes}|-) %{NUMBER:reqTime} %{QS:referer} %{QS:userAgent}"]
    }
    mutate {
        replace=>{"message"=>"%{clientip}: My new Message."}
    }
}
output{
    stdout{
        codec=>rubydebug
    }
}


得到如下结果:

{
     "message" => "192.168.6.25: My new Message.",
     "@version" => "1",
    "@timestamp" => "2016-05-18T01:55:34.566Z",
       "host" => "vcyber",
     "clientip" => "192.168.6.25",
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => "8080",
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\""
}


message 字段的值已经变了。

split

  • 值是 hash
  • 无默认值

用分隔符或字符分割一个字符串。只能应用在字符串上。

示例:把客户端IP按英文句号分割成数组。

mutate {
    split=>{"clientip"=>"."}
}


得到如下结果:
{
     "message" => "192.168.6.25 - - [24/Apr/2016:01:25:53 +0800] GET \"/goLogin\" \"\" 8080 200 1692 23 \"http://10.1.8.193:8080/goMain\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\"",
     "@version" => "1",
    "@timestamp" => "2016-05-18T01:58:40.687Z",
       "host" => "vcyber",
     "clientip" => [
    [0] "192",
    [1] "168",
    [2] "6",
    [3] "25"
  ],
      "identd" => "-",
       "auth" => "-",
    "timestamp" => "24/Apr/2016:01:25:53 +0800",
   "http_method" => "GET",
     "request" => "\"/goLogin\"",
  "request_query" => "\"\"",
       "port" => "8080",
    "statusCode" => "200",
      "bytes" => "1692",
     "reqTime" => "23",
     "referer" => "\"http://10.1.8.193:8080/goMain\"",
    "userAgent" => "\"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:46.0) Gecko/20100101 Firefox/46.0\""
}


strip

  • 值是数组 array
  • 无默认值

去掉字段首尾的空格。

示例:

filter {
 mutate {
   strip =>["field1","field2"]}}


update

  • 值是 hash
  • 无默认值

Update an existing field with a new value. If the field does not exist, then no action will be taken.

示例:

filter { mutate {  update =>{"sample"=>"My new message"}}}