Logstash过滤器之Mutate过滤器详解

骑猪看日落 2022-11-26 07:46 353阅读 0赞

# 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过滤器的配置选项 ##

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

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

--------------------

### 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 ###