手把手教你編寫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.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時，輸入任意字符，回車~~~大功告成！

是否是，沒有想象中的那麼難？要想要熟練的編寫更復雜的插件，還須要多看官方插件的源碼！

參考

1 How to write a Logstash filter plugin