ELK——Logstash 2.2 mutate 插件【翻译+实践】

官网地址

本文内容

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

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

比如：

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

迁移到：http://www.bdata-cap.com/newsinfo/1712678.html

语法

---

该插件必须是用 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 => {"field1"=>"value1","field2"=>"value2"}。
• 默认值是空对象，即 {}

添加新的字段。

示例：

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"}}}