手把手教你编写Logstash插件

使用过Logstash的朋友都知道，它强大的插件生态几乎覆盖了所有的开源框架。从基本的http、tcp、udp、file，到强大的kafa、redis、ganglia，还有丰富的解析工具，比如date、json、grok、kv等等，有了它再也不用担心数据不好搜集了！

不过需求是无限的，如果这些框架都不满足怎么办呢？

没关系，十分佩服Logstash的作者，他以插件的方式组织每个部分，使得logstash本身具有超强的扩展性。

Logstash基本组成

有过使用经验的都知道Logstash主要由输入、过滤器、输出三部分组成。
每一部分的插件都符合统一的标准，因此扩展起来也十分容易。

自定义过滤器插件

由于需求大多都是集中在过滤部分，因此这里就简单的介绍下过滤器的自定义写法。

官网上面的过程太过繁琐，比如：

• 1 创建github开源工程
• 2 拷贝样例工程
• 3 替换样例工程基本信息
• 4 编写业务代码
• 5 安装插件
• 6 分享与贡献

但是如果自己用的话，上面做了很多的无用功。我这里提供一个极简的样例工程，插件的目录大致如下：

$ tree logstash-filter-example
├──lib
│   └── logstash
│       └── filters
│           └── mypluginname.rb
├── logstash-filter-example.gemspec

其实只需要这两个文件即可！

先看看logstash-filter-example.gemspec都做了什么吧！

Gem::Specification.new do|s|
  s.name ='logstash-filter-example'
  s.version ='1.0.0'
  s.licenses =['Apache License (2.0)']
  s.summary =" "
  s.description =" "
  s.authors =["xingoo"]
  s.email ='xinghalo@163.com'
  s.homepage ="http://www.elastic.co/guide/en/logstash/current/index.html"
  s.require_paths =["lib"]# Files
  s.metadata ={"logstash_plugin"=>"true","logstash_group"=>"filter"}# Gem dependencies
  s.add_runtime_dependency 'logstash-core','>= 2.0.0','< 3.0.0'
  s.add_development_dependency 'logstash-devutils'
end

上面的信息，只要改改版本和名字，其他的信息基本不需要动。

关键的信息还有：

• s.require_paths定义了插件核心文件的位置
• s.add_runtime_dependency 定义了插件运行的环境

然后再看看logstash-filter-example.rb

这个文件就需要详细说说了，基本的框架如下，

# encoding: utf-8
require "logstash/filters/base"
require "logstash/namespace"

class LogStash::Filters::Example < LogStash::Filters::Base
  config_name "example"
  config :name,:validate =>:string,:default =>"xingoo!"

  public
  def register
  end

  public
  def filter(event)
    event["name"] = @name
    filter_matched(event)
  end 
end 

挨行看看！

首先第一行的# encoding: utf-8,不要以为是注释就没什么作用。它定义了插件的编码方式。

下面两行：

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

引入了插件必备的包。

class LogStash::Filters::Example < LogStash::Filters::Base
  config_name "example"

插件继承自Base基类，并配置插件的使用名称。

下面的一行对参数做了配置，参数有很多的配置属性，完整的如下：

 config :variable_name,:validate =>:variable_type,:default =>"Default value",:required => boolean,:deprecated => boolean

其中

• variable_name就是参数的名称了。
• validate 定义是否进行校验，如果不是指定的类型，在logstash -f xxx --configtest的时候就会报错。它支持多种数据类型，比如:string, :password, :boolean, :number, :array, :hash, :path (a file-system path), :codec (since 1.2.0), :bytes.
• default 定义参数的默认值
• required 定义参数是否是必须值
• deprecated 定义参数的额外信息，比如一个参数不再推荐使用了，就可以通过它给出提示！典型的就是es-output里面的Index_type，当使用这个参数时，就会给出提示：

config :index_type, :validate => :string, :deprecated => "Please use the 'document_type' setting instead. It has the same effect, but is more appropriately named."

下面的两个方法是插件的核心了！

register方法相当于初始化的构造方法，可以在里面进行插件的初始化工作。

filter中则是过滤器的核心代码。

其中event是从input插件中传入的事件对象，它是Logstash::Event的对象，在logstashj-core包中，有兴趣的可以了解一下！

然后在这个方法中可以使用几个默认的方法；

• filter_matched()，该方法会把事件传入下一个过滤器
• add_field、`remove_field 添加或者移除一个字段
• add_tags、remove_tags 添加或者移除一个标签
• event.cancel 取消当前的事件，即不在继续向下走。（在split插件中有典型的使用场景）

在上面的例子中，定义了一个name参数，在register中使用@name实例变量，把参数赋值给event对象。

这个插件的目的就是给每条事件都加上一个name属性。

至此一个插件就算编写完成了！

安装插件

第一步，首先把这个插件文件夹拷贝到下面的目录中

logstash-2.1.0vendorundlejruby1.9gems

第二步，修改logstash根目录下的Gemfile,添加如下的内容：

gem "logstash-filter-example", :path => "vendor/bundle/jruby/1.9/gems/logstash-filter-example-1.0.0"

第三步，编写配置文件，test.conf：

input{
	stdin{

	}
}
filter{
	example{
		name => "test name:xingoo"
	}
}
output{
	stdout{
		codec => rubydebug
	}
}

第四步，输入logstash -f test.conf时，输入任意字符，回车~~~大功告成！

是不是，没有想象中的那么难？要想要熟练的编写更复杂的插件，还需要多看官方插件的源码！

参考

1 How to write a Logstash filter plugin