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中的文本字符串内部构建，因此最好使用path选项将 Ruby 代码放在 .rb 文件中。

    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 脚本文件的 register 方法的参数。

如果 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"
      }
    }

定期调用过滤器 flush 方法。可选。

如果此过滤器成功，则从此事件中删除任意字段。字段名称可以是动态的，并且可以使用 %{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（如果存在）。第二个示例还将删除一个不需要的标签。