Logstash过滤器之Mutate过滤器详解

Mutate(改变)过滤器插件

该文章内容参考官方文档7.8版本，由于使用范围有限并未翻译全篇文章

描述

Mutate过滤器允许你执行一些对字段的修改操作。你可以通过这个过滤器对事件中的字段进行重命名，移除，替换和修改。

处理命令

在Mutate过滤器的配置文件中可以执行如下命令:

• coerce
• rename
• update
• replace
• convert
• gsub
• uppercase
• capitalize
• lowercase
• strip
• remove
• split
• join
• merge
• copy

你可以在不同的mutate配置块中使用这些命令。 例如：

filter {
    mutate {
        split => ["hostname", "."]
        add_field => { "shortHostname" => "%{hostname[0]}" }
    }

    mutate {
        rename => ["shortHostname", "hostname" ]
    }
}

Mutate过滤器的配置选项

下面是过滤器支持的配置项，配置项详情参考下面的详解。

选项	类型	是否必须	简述
convert	hash	No	转化命令，是对字段类型做转化，例如:String转为integer
copy	hash	No	将一个已经存在的字段复制给另一个字段。
gsub	array	No	通过正则表达式匹配字段的值，然后替换为指定的字符串。
join	hash	No	使用分隔符连接数组。
lowercase	array	No	将string类型的字段值转化为小写的形式。
merge	hash	No	合并两个数组或者Hash类型的字段。string类型的字段会自动的合并为一个数组。
coerce	hash	No	为存在但是不为空的字段设置默认值
rename	hash	No	字段重命名
replace	hash	No	将一个字段的值替换为一个新的值。
split	hash	No	将一个字段按照指定符号切割为数组。
strip	array	No	去除字段中的空格。
update	hash	No	更新字段为一个新值。
uppercase	array	No	将字符串字段转化为大写形式。
capitalize	array	No	将字符串字段转化为首字母大写的形式。
tag_on_failure	string	No	错误发生时的配置

---

convert

• 字段类型为 hash
• 没有默认值

将字段转化为不同的类型，例如：string 转 integer。如果被转化的字段类型是数组，数组的所有成员都将被转化。如果对象是hash 就不会进行转化。

实例：

filter {
  mutate {
    convert => {
      "fieldname" => "integer"
      "booleanfield" => "boolean"
    }
  }
}

---

copy

• 字段类型为 hash
• 没有默认值

将一个已经存在的字段复制给另一个字段。如果目标字段已经存在，目标字段的值将被覆盖。

实例：

filter {
     mutate {
        copy => { "source_field" => "dest_field" }
     }
   }

---

gsub

• 字段类型为 array
• 没有默认值

通过正则表达式匹配字段的值，然后替换为指定的字符串。只有字段类型是string类型或者string数组类型才会进行匹配替换。其他类型字段不会做任何操作。

注意配置文件中需要转义斜杠线。

实例：

filter {
  mutate {
    gsub => [
      # replace all forward slashes with underscore
      "fieldname", "/", "_",
      # replace backslashes, question marks, hashes, and minuses
      # with a dot "."
      "fieldname2", "[\\?#-]", "."
    ]
  }
}

---

join

• 字段类型为 hash
• 没有默认值

使用分隔符连接数组。如果不是数组则不执行操作。

实例：

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

[“a”,“b”]转为 “a”|“b”

---

lowercase

• 字段类型为 array
• 没有默认值

将string类型的字段值转化为小写的形式。

实例：

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

---

merge

• 字段类型为 hash
• 没有默认值

合并两个数组或者Hash类型的字段。string类型的字段会自动的合并为一个数组。例如：
array + string 可以合并为一个数组
string + string 会合并为数组
array 和 hash 类型的两个字段将不会执行合并.

实例：

filter {
  mutate {
     merge => { "dest_field" => "added_field" }
  }
}

---

coerce

• 字段类型为 hash
• 没有默认值

为存在但是不为空的字段设置默认值。

实例：

filter {
  mutate {
    # Sets the default value of the 'field1' field to 'default_value'
    coerce => { "field1" => "default_value" }
  }
}

---

rename

• 字段类型为 hash
• 没有默认值

字段重命名
实例：

filter {
      mutate {
        # Renames the 'HOSTORIP' field to 'client_ip'
        rename => { "HOSTORIP" => "client_ip" }
      }
}

---

replace

• 字段类型为 hash
• 没有默认值

将一个字段的值替换为一个新的值。新值可以包括%{foo}字符串，以帮助您从事件的其他字段构建出新值。
实例：

filter {
  mutate {
    replace => { "message" => "%{source_host}: My new message" }
  }
}

---

split

• 字段类型为 hash
• 没有默认值

将一个字段按照指定符号切割为数组。仅在string类型的字段中生效。
实例：

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

---

strip

• 字段类型为 hash
• 没有默认值

去除字段中的空格。NOTE:去除字段中前端部分.

实例：

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

---

update

• 字段类型为 hash
• 没有默认值

更新字段为一个新值。如果这个字段不存在，更新将不执行。

实例：

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

---

uppercase

• 字段类型为 hash
• 没有默认值

将字符串字段转化为大写形式。

实例：

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

---

capitalize

• 字段类型为 hash
• 没有默认值

将字符串字段转化为首字母大写形式。

实例：

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

---

tag_on_failure

• 字段类型为 hash
• 默认值_mutate_error

如果在过滤器中发生了错误，这次操作将不会执行，并且提供一个标记标记当前事件。