› ›

Mutate 过滤器插件

编辑

Mutate 过滤器插件编辑

插件版本：v3.5.8
发布日期：2023-11-22
变更日志

有关其他版本，请参阅版本化插件文档。

获取帮助编辑

如果您对插件有任何疑问，请在 Discuss 论坛中发帖。如需报告错误或提出功能请求，请在 Github 中创建问题。有关 Elastic 支持的插件列表，请参阅 Elastic 支持矩阵。

描述编辑

Mutate 过滤器允许您对字段执行常规变异。您可以重命名、替换和修改事件中的字段。

处理顺序编辑

配置文件中的变异按以下顺序执行

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

如果需要保留操作顺序，则每个变异必须位于其自己的代码块中。

示例

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

    mutate {
        rename => {"shortHostname" => "hostname"}
    }
}

Mutate 过滤器配置选项编辑

此插件支持以下配置选项以及后面介绍的通用选项。

设置	输入类型	必需
`convert`	hash	否
`copy`	hash	否
`gsub`	array	否
`join`	hash	否
`lowercase`	array	否
`merge`	hash	否
`coerce`	hash	否
`rename`	hash	否
`replace`	hash	否
`split`	hash	否
`strip`	array	否
`update`	hash	否
`uppercase`	array	否
`capitalize`	array	否
`tag_on_failure`	string	否

另请参阅通用选项，了解所有过滤器插件支持的选项列表。

`convert`编辑

值类型为哈希
此设置没有默认值。

将字段的值转换为不同的类型，例如将字符串转换为整数。如果字段值为数组，则将转换所有成员。如果字段为哈希，则不会执行任何操作。

转换见解

值使用 Ruby 语义进行转换。请注意，使用 float 和 float_eu 会将值转换为双精度 64 位 IEEE 754 浮点十进制数。为了保持转换后的精度，您应该在 Elasticsearch 映射中使用 double。

有效的转换目标及其在不同输入下的预期行为如下

integer:
- 解析字符串；支持逗号分隔符（例如，字符串 "1,000" 生成值为一千的整数）；当字符串包含小数部分时，它们将被截断。
- 浮点数和小数将被截断（例如，3.99 变为 3，-2.7 变为 -2）
- 布尔值 true 和布尔值 false 分别转换为 1 和 0
integer_eu:
- 与 integer 相同，但字符串值支持点分隔符和逗号小数（例如，"1.000" 生成值为一千的整数）
float:
- 整数将转换为浮点数
- 解析字符串；支持逗号分隔符和点小数（例如，"1,000.5" 生成值为一千点五的浮点数）
- 布尔值 true 和布尔值 false 分别转换为 1.0 和 0.0
float_eu:
- 与 float 相同，但字符串值支持点分隔符和逗号小数（例如，"1.000,5" 生成值为一千点五的浮点数）
string:
- 所有值都将被字符串化并使用 UTF-8 编码
boolean:
- 整数 0 将转换为布尔值 false
- 整数 1 将转换为布尔值 true
- 浮点数 0.0 将转换为布尔值 false
- 浮点数 1.0 将转换为布尔值 true
- 字符串 "true"、"t"、"yes"、"y"、"1"`和 `"1.0" 将转换为布尔值 true
- 字符串 "false"、"f"、"no"、"n"、"0" 和 "0.0" 将转换为布尔值 false
- 空字符串将转换为布尔值 false
- 所有其他值将直接通过，不会进行转换，并记录警告消息
- 对于数组，每个值都将使用上面的规则单独处理

此插件可以在同一文档中转换多个字段，请参阅下面的示例。

示例

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

`copy`编辑

值类型为哈希
此设置没有默认值。

将现有字段复制到另一个字段。现有目标字段将被覆盖。

示例

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

`gsub`编辑

值类型为数组
此设置没有默认值。

将正则表达式与字段值匹配，并将所有匹配项替换为替换字符串。仅支持字符串或字符串数组类型的字段。对于其他类型的字段，不会执行任何操作。

此配置接受一个数组，每个字段/替换包含 3 个元素。

请注意，在配置文件中转义任何反斜杠。

示例

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

`join`编辑

值类型为哈希
此设置没有默认值。

使用分隔符字符或字符串连接数组。对非数组字段不执行任何操作。

示例

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

`lowercase`编辑

值类型为数组
此设置没有默认值。

将字符串转换为其小写等效项。

示例

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

`merge`编辑

值类型为哈希
此设置没有默认值。

合并两个数组或哈希字段。字符串字段将自动转换为数组，因此

`array` + `string` will work
`string` + `string` will result in an 2 entry array in `dest_field`
`array` and `hash` will not work

示例

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

`coerce`编辑

值类型为哈希
此设置没有默认值。

设置存在但为 null 的字段的默认值

示例

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

`rename`编辑

值类型为哈希
此设置没有默认值。

重命名一个或多个字段。

如果目标字段已存在，则其值将被替换。

如果源字段之一不存在，则不会对该字段执行任何操作。（这不会被视为错误；不会应用 tag_on_failure 标签。）

重命名多个字段时，操作顺序无法保证。

示例

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

`replace`编辑

值类型为哈希
此设置没有默认值。

将字段的值替换为新值，或者如果字段不存在，则添加该字段。新值可以包含 %{foo} 字符串，以帮助您从事件的其他部分构建新值。

示例

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

`split`编辑

值类型为哈希
此设置没有默认值。

使用分隔符字符或字符串将字段拆分为数组。仅适用于字符串字段。

示例

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

`strip`编辑

值类型为数组
此设置没有默认值。

从字段中删除空白。注意：这仅适用于前导和尾随空白。

示例

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

`update`编辑

值类型为哈希
此设置没有默认值。

使用新值更新现有字段。如果字段不存在，则不会执行任何操作。

示例

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

`uppercase`编辑

值类型为数组
此设置没有默认值。

将字符串转换为其大写等效项。

示例

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

`capitalize`编辑

值类型为数组
此设置没有默认值。

将字符串转换为其首字母大写等效项。

示例

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

`tag_on_failure`编辑

值类型为字符串
此设置的默认值为 _mutate_error

如果在应用此 mutate 过滤器时发生错误，则其余操作将中止，并且提供的标签将添加到事件中。

通用选项编辑

所有过滤器插件都支持以下配置选项

设置	输入类型	必需
`add_field`	hash	否
`add_tag`	array	否
`enable_metric`	boolean	否
`id`	string	否
`periodic_flush`	boolean	否
`remove_field`	array	否
`remove_tag`	array	否

`add_field`编辑

值类型为哈希
默认值为 {}

如果此过滤器成功，则将任何任意字段添加到此事件。字段名称可以是动态的，并包含使用 %{field} 的事件部分。

示例

    filter {
      mutate {
        add_field => { "foo_%{somefield}" => "Hello world, from %{host}" }
      }
    }

    # You can also add multiple fields at once:
    filter {
      mutate {
        add_field => {
          "foo_%{somefield}" => "Hello world, from %{host}"
          "new_field" => "new_static_value"
        }
      }
    }

如果事件具有字段 "somefield" == "hello"，则此过滤器在成功时将添加字段 foo_hello（如果存在），其值为上面，并且 %{host} 部分将被事件中的该值替换。第二个示例还将添加一个硬编码字段。

`add_tag`编辑

值类型为数组
默认值为 []

如果此过滤器成功，则将任意标签添加到事件中。标签可以是动态的，并使用 %{field} 语法包含事件的某些部分。

示例

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

    # You can also add multiple tags at once:
    filter {
      mutate {
        add_tag => [ "foo_%{somefield}", "taggedy_tag"]
      }
    }

如果事件具有字段 "somefield" == "hello"，则此过滤器在成功时将添加标签 foo_hello（第二个示例当然会添加 taggedy_tag 标签）。

`enable_metric`编辑

值类型为布尔值
默认值为 true

禁用或启用此特定插件实例的指标日志记录。默认情况下，我们会记录所有可能的指标，但您可以为特定插件禁用指标收集。

`id`编辑

值类型为字符串
此设置没有默认值。

向插件配置添加唯一的 ID。如果未指定 ID，Logstash 将生成一个。强烈建议在配置中设置此 ID。当您有两个或多个相同类型的插件时，这尤其有用，例如，如果您有两个 mutate 过滤器。在这种情况下，添加命名 ID 将有助于在使用监控 API 时监控 Logstash。

    filter {
      mutate {
        id => "ABC"
      }
    }

在 id 字段中进行变量替换仅支持环境变量，不支持使用来自密钥存储的值。

`periodic_flush`编辑

值类型为布尔值
默认值为 false

以定期间隔调用过滤器刷新方法。可选。

`remove_field`编辑

值类型为数组
默认值为 []

如果此过滤器成功，则从此事件中删除任意字段。字段名称可以是动态的，并使用 %{field} 示例包含事件的某些部分

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

    # You can also remove multiple fields at once:
    filter {
      mutate {
        remove_field => [ "foo_%{somefield}", "my_extraneous_field" ]
      }
    }

如果事件具有字段 "somefield" == "hello"，则此过滤器在成功时将删除名为 foo_hello 的字段（如果存在）。第二个示例将删除一个额外的非动态字段。

`remove_tag`编辑

值类型为数组
默认值为 []

如果此过滤器成功，则从事件中删除任意标签。标签可以是动态的，并使用 %{field} 语法包含事件的某些部分。

示例

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

    # You can also remove multiple tags at once:
    filter {
      mutate {
        remove_tag => [ "foo_%{somefield}", "sad_unwanted_tag"]
      }
    }

如果事件具有字段 "somefield" == "hello"，则此过滤器在成功时将删除标签 foo_hello（如果存在）。第二个示例还将删除一个令人沮丧的、不需要的标签。

« Metrics 过滤器插件 Prune 过滤器插件 »

Mutate 过滤器插件

Mutate 过滤器插件编辑

获取帮助编辑

描述编辑

处理顺序编辑

Mutate 过滤器配置选项编辑

convert编辑

转换见解

copy编辑

gsub编辑

join编辑

lowercase编辑

merge编辑

coerce编辑

rename编辑

replace编辑

split编辑

strip编辑

update编辑

uppercase编辑

capitalize编辑

tag_on_failure编辑