如何编写 Logstash 过滤器插件

每个 Logstash 插件都位于其自己的 GitHub 存储库中。要为您的插件创建一个新的存储库

您可以在几秒钟内创建自己的 Logstash 插件！bin/logstash-plugin 的 generate 子命令使用模板化文件为新的 Logstash 插件创建基础。它创建了正确的目录结构、gemspec 文件和依赖项，以便您可以开始添加自定义代码以使用 Logstash 处理数据。

有关更多信息，请参阅 生成插件

或者，您可以使用我们在 github.com 上托管的示例存储库

您的文件结构应如下所示

$ tree logstash-filter-mypluginname
├── Gemfile
├── LICENSE
├── README.md
├── Rakefile
├── lib
│   └── logstash
│       └── filters
│           └── mypluginname.rb
├── logstash-filter-mypluginname.gemspec
└── spec
    └── filters
        └── mypluginname_spec.rb

有关 Ruby gem 文件结构的更多信息以及对 Ruby gem 创建过程的出色演练，请参阅 http://timelessrepo.com/making-ruby-gems

在我们深入细节之前，请在您喜欢的文本编辑器中打开插件文件并查看。

require "logstash/filters/base"
require "logstash/namespace"

# Add any asciidoc formatted documentation here
# This example filter will replace the contents of the default
# message field with whatever you specify in the configuration.
#
# It is only intended to be used as an example.
class LogStash::Filters::Example < LogStash::Filters::Base

  # Setting the config_name here is required. This is how you
  # configure this filter from your Logstash config.
  #
  # filter {
  #   example { message => "My message..." }
  # }
  config_name "example"

  # Replace the message with this value.
  config :message, :validate => :string, :default => "Hello World!"


  public
  def register
    # Add instance variables
  end # def register

  public
  def filter(event)

    if @message
      # Replace the event message with our message as configured in the
      # config file.
      event.set("message", @message)
    end

    # filter_matched should go in the last line of our successful code
    filter_matched(event)
  end # def filter

end # class LogStash::Filters::Example

Logstash 过滤器插件需要在 logstash/filters/base 和 logstash/namespace 中定义的父类

require "logstash/filters/base"
require "logstash/namespace"

当然，您构建的插件可能依赖于其他代码，甚至是 gem。只需将它们与这些 Logstash 依赖项一起放在这里。

过滤器插件类应该是 LogStash::Filters::Base 的子类

class LogStash::Filters::Example < LogStash::Filters::Base

类名应与插件名称紧密匹配，例如

LogStash::Filters::Example

  config_name "example"

这是您的插件在过滤器配置块内调用的名称。

如果您在插件代码中设置了 config_name "example"，则相应的 Logstash 配置块需要如下所示

  public
  def register
  end # def register

Logstash register 方法类似于 initialize 方法。它最初是为了强制调用 super 而创建的，以防止新手头疼。（注意：它可能会与一些强制测试一起消失，以支持 initialize，以确保调用 super。）

public 表示该方法可以在任何地方调用，而不仅仅是在类中调用。这是 Ruby 中方法的默认行为，但无论如何都在此处明确指定。

您也可以在此处分配实例变量（变量以 @ 开头）。配置变量现在在范围内作为实例变量，例如 @message

  public
  def filter(event)

    if @message
      # Replace the event message with our message as configured in the
      # config file.
      event.set("message", @message)
    end

  # filter_matched should go in the last line of our successful code
  filter_matched(event)
end # def filter

插件的 filter 方法是实际过滤工作发生的地方！在 filter 方法内部，您可以使用 Event 对象引用事件数据。事件是封装 Logstash 内部数据流的主要对象，并为插件开发人员提供了一个 API 来与事件的内容进行交互。

filter 方法还应通过显式调用 Event 类中可用的 sprintf 方法来处理任何 事件依赖配置。例如

field_foo = event.sprintf(field)

请注意，配置变量现在在范围内作为实例变量，例如 @message

  filter_matched(event)

在插件成功执行后调用 filter_matched 方法将确保正确处理通过 Logstash 配置为此过滤器添加的任何字段或标签。例如，任何 add_field、remove_field、add_tag 和/或 remove_tag 操作都将在此时间执行。

事件方法（例如 event.cancel）现在可用于控制正在处理的事件的工作流。

Ruby 中的 require 语句用于包含必要的代码。在某些情况下，您的插件可能需要其他文件。例如，collectd 插件 使用 由 collectd 提供的 types.db 文件。在插件的主目录中，名为 vendor.json 的文件描述了这些文件。

vendor.json 文件包含一个 JSON 对象数组，每个对象描述一个文件依赖项。此示例来自 collectd 编解码器插件

[{
        "sha1": "a90fe6cc53b76b7bdd56dc57950d90787cb9c96e",
        "url": "http://collectd.org/files/collectd-5.4.0.tar.gz",
        "files": [ "/src/types.db" ]
}]

vendor.json 文件的另一个例子是 geoip 过滤器

用于下载这些依赖项的过程是调用 rake vendor。这将在本文档的测试部分进一步讨论。

另一种外部依赖是 jar 文件。这将在“添加 gemspec 文件”部分中描述。

随着插件的发展，某个选项或功能可能不再满足预期用途，开发人员可能希望弃用其用法。弃用会警告用户有关选项的状态，因此在以后的版本中删除该选项时，他们不会措手不及。

Logstash 7.6 引入了一个“弃用记录器”，以便更轻松地处理这些情况。您可以使用适配器来确保您的插件可以使用弃用记录器，同时仍然支持旧版本的 Logstash。有关更多信息以及有关使用适配器的说明，请参阅自述文件。

弃用说明记录在 log 目录中的 logstash-deprecation.log 文件中。

Gemfile 允许 Ruby 的 Bundler 管理插件的依赖项。目前，我们只需要用于测试的 Logstash gem，但如果您需要其他 gem，则应该在此处添加它们。

source 'https://rubygems.org.cn'
gemspec
gem "logstash", :github => "elastic/logstash", :branch => "8.14"

在 gemspec 文件的底部是一个带有注释的部分：Gem dependencies。这里必须提及任何其他需要的 gem。如果您的插件需要某个 gem 才能正常运行，那么它就是一个运行时依赖项。如果某个 gem 仅用于测试，那么它就是一个开发依赖项。

  # Gem dependencies
  s.add_runtime_dependency "logstash-core-plugin-api", ">= 1.60", "<= 2.99"
  s.add_development_dependency 'logstash-devutils'

在某些情况下，例如Elasticsearch 输出插件，您的代码可能依赖于 jar 文件。在这种情况下，依赖项以这种方式添加到 gemspec 文件中

  # Jar dependencies
  s.requirements << "jar 'org.elasticsearch:elasticsearch', '5.0.0'"
  s.add_runtime_dependency 'jar-dependencies'

定义了这两者之后，安装过程将在 http://mvnrepository.com 中搜索所需的 jar 文件并下载指定的版本。

您已经拥有了所有必要的成分，所以让我们继续运行构建命令

gem build logstash-filter-example.gemspec

就是这样！您的 gem 应该已构建完成，并与名称位于同一路径中

logstash-filter-mypluginname-0.1.0.gem

gemspec 文件中的 s.version 号将提供 gem 版本，在本例中为 0.1.0。

您应该将插件测试安装到 Logstash 的全新安装中。从Logstash 下载页面下载最新版本。

bin/logstash -e 'input { stdin{} } filter { example {} } output {stdout { codec => rubydebug }}'

通过 stdin 发送输入并通过 stdout（过滤后）使用 rubydebug 编解码器（增强可读性）输出，测试您的过滤器。

在示例过滤器插件的情况下，您发送的任何文本都将被 message 配置参数的内容替换，默认值为“Hello World！”

Testing 1, 2, 3
{
       "message" => "Hello World!",
      "@version" => "1",
    "@timestamp" => "2015-01-27T19:17:18.932Z",
          "host" => "cadenza"
}

您可以随意尝试并通过更改 message 参数来对此进行测试

bin/logstash -e 'input { stdin{} } filter { example { message => "This is a new message!"} } output {stdout { codec => rubydebug }}'

恭喜！您已经构建、部署并成功运行了一个 Logstash 过滤器。

Logstash 及其所有插件均根据Apache 许可证版本 2（“ALv2”）获得许可。如果您通过RubyGems.org公开提供您的插件，请确保您的 gemspec 中包含以下行

首先，您需要在 RubyGems.org 上拥有一个帐户

创建帐户后，从 RubyGems.org获取API 密钥。默认情况下，RubyGems 使用文件 ~/.gem/credentials 来存储您的 API 密钥。这些凭据将用于发布 gem。将 username 和 password 替换为您在 RubyGems.org 上创建的凭据

curl -u username:password https://rubygems.org.cn/api/v1/api_key.yaml > ~/.gem/credentials
chmod 0600 ~/.gem/credentials

在继续之前，请确保您的 gemspec 文件中具有正确的版本并提交您的更改。

要发布新 logstash gem 的 0.1.0 版本

bundle install
bundle exec rake vendor
bundle exec rspec
bundle exec rake publish_gem

就是这样！您的插件已发布！Logstash 用户现在可以通过运行以下命令安装您的插件

bin/logstash-plugin install logstash-filter-mypluginname

在 logstash-plugins 存储库中拥有插件的众多好处包括

要开始将您的插件迁移到 logstash-plugins，只需在 Logstash 存储库中创建一个新的问题。完成验收指南后，我们将使用推荐的GitHub 流程协助迁移到 logstash-plugins 组织。