:plugin: prune
: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}"]

=== Prune filter plugin

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

==== Description

The prune filter is for removing fields from events based on
whitelists or blacklist of field names or their values (names and
values can also be regular expressions).

This can e.g. be useful if you have a <<plugins-filters-json,json>>
or <<plugins-filters-kv,kv>> filter that creates a number of fields
with names that you don't necessarily know the names of beforehand,
and you only want to keep a subset of them.

Usage help:
To specify a exact field name or value use the regular expression syntax `^some_name_or_value$`.
Example usage: Input data `{ "msg":"hello world", "msg_short":"hw" }`
[source,ruby]
    filter {
      prune {
        whitelist_names => [ "msg" ]
      }
    }
Allows both `"msg"` and `"msg_short"` through.

While:
[source,ruby]
    filter {
      prune {
        whitelist_names => ["^msg$"]
      }
    }
Allows only `"msg"` through.

Logstash stores an event's `tags` as a field which is subject to pruning. Remember to `whitelist_names => [ "^tags$" ]`
to maintain `tags` after pruning or use `blacklist_values => [ "^tag_name$" ]` to eliminate a specific `tag`.

NOTE: This filter currently only support operations on top-level fields,
i.e. whitelisting and blacklisting of subfields based on name or value
does not work.

[id="plugins-{type}s-{plugin}-options"]
==== Prune 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}-blacklist_names>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-blacklist_values>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-interpolate>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-whitelist_names>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-whitelist_values>> |<<hash,hash>>|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}-blacklist_names"]
===== `blacklist_names` 

  * Value type is <<array,array>>
  * Default value is `["%{[^}]+}"]`

Exclude fields whose names match specified regexps, by default exclude unresolved `%{field}` strings.
[source,ruby]
    filter {
      prune {
        blacklist_names => [ "method", "(referrer|status)", "${some}_field" ]
      }
    }

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

  * Value type is <<hash,hash>>
  * Default value is `{}`

Exclude specified fields if their values match one of the supplied regular expressions.
In case field values are arrays, each array item is matched against the regular expressions and matching array items will be excluded.
[source,ruby]
    filter {
      prune {
        blacklist_values => [ "uripath", "/index.php",
                              "method", "(HEAD|OPTIONS)",
                              "status", "^[^2]" ]
      }
    }

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

  * Value type is <<boolean,boolean>>
  * Default value is `false`

Trigger whether configuration fields and values should be interpolated for
dynamic values (when resolving `%{some_field}`).
Probably adds some performance overhead. Defaults to false.

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

  * Value type is <<array,array>>
  * Default value is `[]`

Include only fields only if their names match specified regexps, default to empty list which means include everything.
[source,ruby]
    filter {
      prune {
        whitelist_names => [ "method", "(referrer|status)", "${some}_field" ]
      }
    }

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

  * Value type is <<hash,hash>>
  * Default value is `{}`

Include specified fields only if their values match one of the supplied regular expressions.
In case field values are arrays, each array item is matched against the regular expressions and only matching array items will be included.
[source,ruby]
    filter {
      prune {
        whitelist_values => [ "uripath", "/index.php",
                              "method", "(GET|POST)",
                              "status", "^[^2]" ]
      }
    }



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