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

=== Ruby filter plugin

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

==== Description

Execute ruby code.

For example, to cancel 90% of events, you can do this:
[source,ruby]
    filter {
      ruby {
        # Cancel 90% of events
        code => "event.cancel if rand <= 0.90"
      }
    }

If you need to create additional events, it cannot be done as in other filters where you would use `yield`,
you must use a specific syntax `new_event_block.call(event)` like in this example duplicating the input event
[source,ruby]
filter {
  ruby {
    code => "new_event_block.call(event.clone)"
  }
}


[id="plugins-{type}s-{plugin}-options"]
==== Ruby 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}-code>> |<<string,string>>|Yes
| <<plugins-{type}s-{plugin}-init>> |<<string,string>>|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}-code"]
===== `code` 

  * This is a required setting.
  * Value type is <<string,string>>
  * There is no default value for this setting.

The code to execute for every event.
You will have an `event` variable available that is the event itself. See the <<event-api,Event API>> for more information.

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

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

Any code to execute at logstash startup-time



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