官网地址
本文内容
- 语法
- 测试数据
- 可选配置项
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 "%U" "%q" %p %s %b %D "%{Referer}i" "%{User-Agent}i"" />
若用如下 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, 和1false,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"}}}