Ruby 过滤器插件

要在过滤器中添加内联 Ruby 代码，请将所有代码放在 code 选项中。此代码将针对过滤器接收的每个事件执行。您也可以将 Ruby 代码放在 init 选项中。它只会在插件的注册阶段执行一次。

例如，要取消 90% 的事件，您可以这样做

    filter {
      ruby {
        # Cancel 90% of events
        code => "event.cancel if rand <= 0.90"
      }
    }

如果您需要创建其他事件，则必须使用特定的语法 new_event_block.call(event)，如下例所示，复制输入事件

filter {
  ruby {
    code => "new_event_block.call(event.clone)"
  }
}

由于内联代码在 code 中的文本字符串内可能会变得复杂且难以组织，因此最好将 Ruby 代码放在 .rb 文件中，使用 path 选项。

    filter {
      ruby {
        # Cancel 90% of events
        path => "/etc/logstash/drop_percentage.rb"
        script_params => { "percentage" => 0.9 }
      }
    }

Ruby 脚本文件应定义以下方法

下面是一个 drop_percentage.rb Ruby 脚本的示例实现，该脚本会丢弃可配置百分比的事件

# the value of `params` is the value of the hash passed to `script_params`
# in the logstash configuration
def register(params)
	@drop_percentage = params["percentage"]
end

# the filter method receives an event and must return a list of events.
# Dropping an event means not including it in the return array,
# while creating new ones only requires you to add a new instance of
# LogStash::Event to the returned array
def filter(event)
	if rand >= @drop_percentage
		return [event]
	else
		return [] # return empty array to cancel event
	end
end

为了验证您实现的 filter 方法的行为，Ruby 过滤器插件提供了一个内联测试框架，您可以在其中断言期望。您定义的测试将在创建管道时运行，如果测试失败，将阻止管道启动。

您还可以使用 logstash -t 标志来验证测试是否通过。

例如，在上面，您可以在 drop_percentage.rb Ruby 脚本的底部编写以下测试

def register(params)
  # ..
end

def filter(event)
  # ..
end

test "drop percentage 100%" do
  parameters do
    { "percentage" => 1 }
  end

  in_event { { "message" => "hello" } }

  expect("drops the event") do |events|
    events.size == 0
  end
end

我们现在可以测试我们正在使用的 Ruby 脚本是否已正确实现

% bin/logstash -e "filter { ruby { path => '/etc/logstash/drop_percentage.rb' script_params => { 'drop_percentage' => 0.5 } } }" -t
[2017-10-13T13:44:29,723][INFO ][logstash.filters.ruby.script] Test run complete {:script_path=>"/etc/logstash/drop_percentage.rb", :results=>{:passed=>1, :failed=>0, :errored=>0}}
Configuration OK
[2017-10-13T13:44:29,887][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash

为每个事件执行的代码。您将有一个可用的 event 变量，它是事件本身。有关更多信息，请参阅事件 API。

在 Logstash 启动时执行的任何代码

实现 filter 方法的 Ruby 脚本文件的路径。

一个键/值哈希，其中包含传递给 path 中定义的 Ruby 脚本文件的注册方法的参数。

如果 Ruby 代码（内联或基于文件）导致异常，则添加到事件的标记。

如果为 true，则向事件添加一个标记，该标记是 tag_with_exception_message 和异常消息的串联。

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

示例

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

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

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

如果此过滤器成功，则向事件添加任意标记。标记可以是动态的，并使用 %{field} 语法包含事件的部分内容。

示例

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

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

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

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

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

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

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

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

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

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

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

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

示例

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

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

如果事件具有字段 "somefield" == "hello"，则此过滤器在成功后，如果存在，将删除标签 foo_hello。第二个示例也将删除一个悲伤且不需要的标签。