手把手教你编写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_tagsremove_tags 添加或者移除一个标签
  • event.cancel 取消当前的事件,即不在继续向下走。(在split插件中有典型的使用场景)

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

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

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

安装插件

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

logstash-2.1.0\vendor\bundle\jruby\1.9\gems

第二步,修改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时,输入任意字符,回车~~~大功告成!

手把手教你编写Logstash插件

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

参考

1 How to write a Logstash filter plugin

上一篇:slidingMenu默认显示菜单


下一篇:Subclipse和TortoiseSVN版本不一致导致升到高版本的project后,低版本svn客户端无法使用。