:plugin: mutate
:type: filter

///////////////////////////////////////////
START - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////
:version: %VERSION%
:release_date: %RELEASE_DATE%
:changelog_url: %CHANGELOG_URL%
:include_path: ../../../../logstash/docs/include
///////////////////////////////////////////
END - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////

[id="plugins-{type}-{plugin}"]

=== Mutate filter plugin

include::{include_path}/plugin_header.asciidoc[]

==== Description

The mutate filter allows you to perform general mutations on fields. You
can rename, remove, replace, and modify fields in your events.

[id="plugins-{type}s-{plugin}-options"]
==== Mutate Filter Configuration Options

This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.

[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-convert>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-copy>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-gsub>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-join>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-lowercase>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-merge>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-rename>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-replace>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-split>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-strip>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-update>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-uppercase>> |<<array,array>>|No
|=======================================================================

Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
filter plugins.

&nbsp;

[id="plugins-{type}s-{plugin}-convert"]
===== `convert` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Convert a field's value to a different type, like turning a string to an
integer. If the field value is an array, all members will be converted.
If the field is a hash, no action will be taken.

If the conversion type is `boolean`, the acceptable values are:

* **True:** `true`, `t`, `yes`, `y`, and `1`
* **False:** `false`, `f`, `no`, `n`, and `0`

If a value other than these is provided, it will pass straight through
and log a warning message.

Valid conversion targets are: integer, float, string, and boolean.

Example:
[source,ruby]
    filter {
      mutate {
        convert => { "fieldname" => "integer" }
      }
    }

[id="plugins-{type}s-{plugin}-copy"]
===== `copy` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Copy an existing field to another field. Existing target field will be overriden.

Example:
[source,ruby]
    filter {
      mutate {
         copy => { "source_field" => "dest_field" }
      }
    }

[id="plugins-{type}s-{plugin}-gsub"]
===== `gsub` 

  * Value type is <<array,array>>
  * There is no default value for this setting.

Convert a string field by applying a regular expression and a replacement.
If the field is not a string, no action will be taken.

This configuration takes an array consisting of 3 elements per
field/substitution.

Be aware of escaping any backslash in the config file.

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


[id="plugins-{type}s-{plugin}-join"]
===== `join` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Join an array with a separator character. Does nothing on non-array fields.

Example:
[source,ruby]
   filter {
     mutate {
       join => { "fieldname" => "," }
     }
   }

[id="plugins-{type}s-{plugin}-lowercase"]
===== `lowercase` 

  * Value type is <<array,array>>
  * There is no default value for this setting.

Convert a string to its lowercase equivalent.

Example:
[source,ruby]
    filter {
      mutate {
        lowercase => [ "fieldname" ]
      }
    }

[id="plugins-{type}s-{plugin}-merge"]
===== `merge` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Merge two fields of arrays or hashes.
String fields will be automatically be converted into an array, so:
==========================
  `array` + `string` will work
  `string` + `string` will result in an 2 entry array in `dest_field`
  `array` and `hash` will not work
==========================
Example:
[source,ruby]
    filter {
      mutate {
         merge => { "dest_field" => "added_field" }
      }
    }

[id="plugins-{type}s-{plugin}-rename"]
===== `rename` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Rename one or more fields.

Example:
[source,ruby]
    filter {
      mutate {
        # Renames the 'HOSTORIP' field to 'client_ip'
        rename => { "HOSTORIP" => "client_ip" }
      }
    }

[id="plugins-{type}s-{plugin}-replace"]
===== `replace` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Replace a field with a new value. The new value can include `%{foo}` strings
to help you build a new value from other parts of the event.

Example:
[source,ruby]
    filter {
      mutate {
        replace => { "message" => "%{source_host}: My new message" }
      }
    }

[id="plugins-{type}s-{plugin}-split"]
===== `split` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Split a field to an array using a separator character. Only works on string
fields.

Example:
[source,ruby]
    filter {
      mutate {
         split => { "fieldname" => "," }
      }
    }

[id="plugins-{type}s-{plugin}-strip"]
===== `strip` 

  * Value type is <<array,array>>
  * There is no default value for this setting.

Strip whitespace from field. NOTE: this only works on leading and trailing whitespace.

Example:
[source,ruby]
    filter {
      mutate {
         strip => ["field1", "field2"]
      }
    }

[id="plugins-{type}s-{plugin}-update"]
===== `update` 

  * Value type is <<hash,hash>>
  * There is no default value for this setting.

Update an existing field with a new value. If the field does not exist,
then no action will be taken.

Example:
[source,ruby]
    filter {
      mutate {
        update => { "sample" => "My new message" }
      }
    }

[id="plugins-{type}s-{plugin}-uppercase"]
===== `uppercase` 

  * Value type is <<array,array>>
  * There is no default value for this setting.

Convert a string to its uppercase equivalent.

Example:
[source,ruby]
    filter {
      mutate {
        uppercase => [ "fieldname" ]
      }
    }



[id="plugins-{type}s-{plugin}-common-options"]
include::{include_path}/{type}.asciidoc[]