如何编写 Logstash codec 插件

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

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

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

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

您的文件结构应如下所示

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

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

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

require "logstash/codecs/base"
require "logstash/codecs/line"

# Add any asciidoc formatted documentation here
class LogStash::Codecs::Example < LogStash::Codecs::Base

  # This example codec will append a string to the message field
  # of an event, either in the decoding or encoding methods
  #
  # This is only intended to be used as an example.
  #
  # input {
  #   stdin { codec => example }
  # }
  #
  # or
  #
  # output {
  #   stdout { codec => example }
  # }
  config_name "example"

  # Append a string to the message
  config :append, :validate => :string, :default => ', Hello World!'

  public
  def register
    @lines = LogStash::Codecs::Line.new
    @lines.charset = "UTF-8"
  end

  public
  def decode(data)
    @lines.decode(data) do |line|
      replace = { "message" => line["message"].to_s + @append }
      yield LogStash::Event.new(replace)
    end
  end # def decode

  public
  def encode(event)
    @on_event.call(event, event.get("message").to_s + @append + NL)
  end # def encode

end # class LogStash::Codecs::Example

Logstash codec 插件需要在 logstash/codecs/base 和 logstash/namespace 中定义的父类

require "logstash/codecs/base"
require "logstash/namespace"

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

codec 插件类应该是 LogStash::Codecs::Base 的子类

class LogStash::Codecs::Example < LogStash::Codecs::Base

类名应与插件名称非常相似，例如

LogStash::Codecs::Example

  config_name "example"

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

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

  public
  def register
  end # def register

Logstash register 方法类似于 initialize 方法。它最初是为了强制调用 super 而创建的，从而避免了新手遇到的麻烦。（注意：它可能会被 initialize 取代，并结合一些强制执行的测试以确保调用了 super。）

public 表示该方法可以在任何地方调用，而不仅仅是在类中。这是 Ruby 中方法的默认行为，但这里还是明确指定了它。

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

  public
  def decode(data)
    @lines.decode(data) do |line|
      replace = { "message" => line["message"].to_s + @append }
      yield LogStash::Event.new(replace)
    end
  end # def decode

codec 的 decode 方法是输入数据转换为事件的地方。有一些复杂的示例，例如 collectd codec，以及更简单的示例，例如 spool codec。

必须在 decode 方法中包含一个 yield 语句，该语句会将解码后的事件返回到管道。

  public
  def encode(event)
    @on_event.call(event, event.get("message").to_s + @append + NL)
  end # def encode

encode 方法获取一个事件并将其序列化（*编码*) 为另一种格式。 encode 方法的一些很好的示例包括简单的 plain codec、稍微复杂一些的 msgpack codec，甚至 avro codec。

在大多数情况下，您的 encode 方法应包含一个 @on_event.call() 语句。此调用将以描述的方式输出每个事件的数据。

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

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

[{
        "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.16"

在 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-codec-example.gemspec

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

logstash-codec-mypluginname-0.1.0.gem

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

您应该在 Logstash 的干净安装中测试安装您的插件。从 Logstash 下载页面 下载最新版本。

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

示例编解码器插件将追加 append 的内容（默认情况下追加 ", Hello World!"）

启动 Logstash 后，键入一些内容，例如“Random output string”。结果输出消息字段内容应为“Random output string, Hello World！”

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

随意通过更改 append 参数进行实验和测试

bin/logstash -e 'input { stdin{ codec => example{ append => ", I am appending this! }} } output {stdout { codec => rubydebug }}'

恭喜！您已构建、部署并成功运行了 Logstash 编解码器。

Logstash 及其所有插件均在 Apache 许可证 2.0 版 (“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-codec-mypluginname

将您的插件包含在 logstash-plugins 存储库中有很多好处，其中一些包括

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