如何编写 Logstash 输出插件

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

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

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

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

您的文件结构应如下所示

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

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

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

require "logstash/outputs/base"
require "logstash/namespace"

# Add any asciidoc formatted documentation here
# An example output that does nothing.
class LogStash::Outputs::Example < LogStash::Outputs::Base
  config_name "example"

  # This sets the concurrency behavior of this plugin. By default it is :legacy, which was the standard
  # way concurrency worked before Logstash 2.4
  #
  # You should explicitly set it to either :single or :shared as :legacy will be removed in Logstash 6.0
  #
  # When configured as :single a single instance of the Output will be shared among the
  # pipeline worker threads. Access to the `#multi_receive/#multi_receive_encoded/#receive` method will be synchronized
  # i.e. only one thread will be active at a time making threadsafety much simpler.
  #
  # You can set this to :shared if your output is threadsafe. This will maximize
  # concurrency but you will need to make appropriate uses of mutexes in `#multi_receive/#receive`.
  #
  # Only the `#multi_receive/#multi_receive_encoded` methods need to actually be threadsafe, the other methods
  # will only be executed in a single thread
  concurrency :single

  public
  def register
  end # def register

  public
  # Takes an array of events
  # Must be threadsafe if `concurrency :shared` is set
  def multi_receive(events)
  end # def multi_receive
end # class LogStash::Outputs::Example

Logstash 输出插件需要在 logstash/outputs/base 和 logstash/namespace 中定义的父类

require "logstash/outputs/base"
require "logstash/namespace"

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

输出插件类应该是 LogStash::Outputs::Base 的子类

class LogStash::Outputs::Example < LogStash::Outputs::Base

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

LogStash::Outputs::Example

  config_name "example"

这是您的插件在输出配置块内调用的名称。

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

  public
  def register
  end # def register

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

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

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

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-output-example.gemspec

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

logstash-output-mypluginname-0.1.0.gem

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

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

恭喜！您已经构建、部署并成功运行了一个 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-output-mypluginname

将插件放在 logstash-plugins 存储库中的诸多好处包括：

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