自己写一个插件

前面已经提过在运行 logstash 的时候,可以通过 --pluginpath 参数来加载自己写的插件。那么,插件又该怎么写呢?

插件格式

一个标准的 logstash 输入插件格式如下:

  1. require 'logstash/namespace'
  2. require 'logstash/inputs/base'
  3. class LogStash::Inputs::MyPlugin < LogStash::Inputs::Base
  4. config_name 'myplugin'
  5. default :codec, "line"
  6. config :myoption_key, :validate => :string, :default => 'myoption_value'
  7. public def register
  8. end
  9. public def run(queue)
  10. end
  11. end

其中大多数语句在过滤器和输出阶段是共有的。

  • config_name 用来定义该插件写在 logstash 配置文件里的名字;
  • config 可以定义很多个,即该插件在 logstash 配置文件中的可配置参数。logstash 很温馨的提供了验证方法,确保接收的数据是你期望的数据类型;
  • register logstash 在启动的时候运行的函数,一些需要常驻内存的数据,可以在这一步先完成。比如对象初始化,filters/ruby 插件中的 init 语句等。

插件的关键方法

输入插件独有的是 run 方法。在 run 方法中,必须实现一个长期运行的程序(最简单的就是 loop 指令)。然后在每次收到数据并处理成 event,这段示例在上一节演示 Logstash::Event 的生成时已经介绍过。最后,一定要调用 queue << event 语句。一个输入流程就算是完成了。

而如果是过滤器插件,对应修改成:

  1. require 'logstash/filters/base'
  2. class LogStash::Filters::MyPlugin < LogStash::Filters::Base
  3. config_name 'myplugin'
  4. public def register
  5. end
  6. public def filter(event)
  7. filter_matched(event)
  8. end
  9. end

其中,filter_matched 是在 filter 函数完成本插件自己的处理逻辑之后一定要调用的。

输出插件则是:

  1. require 'logstash/outputs/base'
  2. class LogStash::Outputs::MyPlugin < LogStash::Outputs::Base
  3. config_name 'myplugin'
  4. concurrency :single
  5. public def register
  6. end
  7. public def multi_receive(events)
  8. end
  9. end

这里和过去的版本最明显的差别是,处理方法改成了 multi_receive,而不是 receive。因为新的 pipeline 机制是批量传递数据给输出插件的。不过为了兼容过去的插件,LogStash::Outputs::Base 基类中的 multi_receive 实现继续迭代调用了 receive

另一个是新出现的配置 concurrency,代表着本插件是否 threadsafe,并由此取代了过去的 workers 选项。可选项为:singleshared

  • single 表示本插件是非线程安全的,必须在各 pipeline workers 之间同一时刻只有一个运行。
  • shared 表示本插件是线程安全的,每个 pipeline workers 之间可以独立运行,这也就意味着插件作者要自己在 multi_receive 里调用 Mutexes。

推荐阅读

插件打包

Logstash 从 1.5.0-GA 版开始,对插件规范做了重大变更。放弃了 milestone 定义,去除了 --pluginpath 命令行参数。统一改成 bin/plugin 管理的 rubygem 包插件。那么,我们自己写的 Logstash 插件,也同样需要适应这个新规则,写完 Ruby 代码,还要打包成 gem 才能使用。

为了我们更方便的完成工作,logstash 针对 4 种插件形态提供了 4 个示例库,可以按照自己所需克隆使用。比如要写一个 logstash-filter-mything 插件:

  1. git clone https://github.com/logstash-plugins/logstash-filter-example
  2. cd logstash-filter-example
  3. mv logstash-filter-example.gemspec logstash-filter-mything.gemspec
  4. mv lib/logstash/filters/example.rb lib/logstash/filters/mything.rb
  5. mv spec/filters/example_spec.rb spec/filters/mything_spec.rb

然后把代码写在 lib/logstash/filters/mything.rb 里即可。

代码部分完成。然后就是定义 gem 打包需要的额外文件和库依赖了。

目录中有两个文件,Gemfilelogstash-filter-mything.gemspec

Gemfile 文件就是标准格式,用来运行 bundler install 时下载 rubygems 包的。默认情况下,最基础的内容是:

  1. source 'https://rubygems.org' # 国内建议改成 'http://ruby.taobao.org'
  2. gemspec
  3. gem "logstash", :github => "elastic/logstash", :branch => "1.5"

gemspec 文件则是用来定义软件包本身规范,不单限于 rubygems。示例如下:

  1. Gem::Specification.new do |s|
  2. s.name = 'logstash-filter-mything'
  3. s.version = '1.1.0'
  4. s.licenses = ['Apache License (2.0)']
  5. s.summary = "This mything filter is just for Elastic Stack Guide example"
  6. s.description = "This gem is a logstash plugin required to be installed on top of the Logstash core pipeline using $LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program"
  7. s.authors = ["Chenryn"]
  8. s.email = 'chenlin7@staff.sina.com.cn'
  9. s.homepage = "http://kibana.logstash.es"
  10. s.require_paths = ["lib"]
  11. s.files = `find . -type f ! -wholename '*.svn*'`.split($\)
  12. s.test_files = s.files.grep(%r{^(test|spec|features)/})
  13. s.metadata = { "logstash_plugin" => "true", "logstash_group" => "filter" }
  14. s.requirements << "jar 'org.elasticsearch:elasticsearch', '1.4.0'"
  15. s.add_runtime_dependency "jar-dependencies"
  16. s.add_runtime_dependency "logstash-core", '>= 1.4.0', '< 2.0.0'
  17. s.add_development_dependency 'logstash-devutils'
  18. end

其中:

  • s.version 就是 milestone 的替代品,0.1.x 相当于是 milestone 0;0.9.x 相当于是 milestone 2;1.x.x 相当于是 milestone 3。
  • s.file 默认写法是 git ls-files,因为默认是 git 库,如果你本身采用了 svn,或者 cvs 库,都不要紧,只要命令列出的是你需要打包进去的文件即可。
  • s.metadata 是 logstash 的 plugin 命令在 install 的时候会提前 verify 的特殊信息,一定要保留。
  • s.add_runtime_dependency 是定义插件依赖库的指令。如果有 jar 包依赖,则额外再加 s.requirements

好了,全部完毕。下面打包:

  1. gem build logstash-filter-mything.gemspec

运行完就会生成一个 logstash-filter-mything-1.1.0.gem 软件包,可以安装使用了。