一.理论信息

 1. 使用logstash自带命令生成插件模版

    bin/logstash-plugin generate --type filter --name test  --path vendor/localgems

      --type  代表要生成的选项，有  filter ，input ，output 

      --name  代表要自定义的插件名称

      --path  代表生成的插件模版的目录 ，如果不指定的默认当前目录

            命令执行结果如下:

            查看生成的filter目录结构，如下(使用tree命令):

2. 目录结构以及代码结构

      插件的模版下，lib目录下就是你要开发的ruby代码的存放路径；.gemspec应该是一些配置信息，以及加入的一些依赖库信息。

      上述图片是模版生成的test.rb 的代码结构

          1.第一行 #encoding: utf-8  就是指定编码格式，ruby的普遍写法

          2.模版代码里默认 require 了 "logstash/filters/base" 和 "logstash/namespace",如果需要依赖其他代码或者gems就在这里添加上就好，如  require "redis"  (额外库的安装以及使用方法在下一节)

           3.config_name  "test"  配置的是插件名称

           4.如果插件需要添加外部参数，写法如下:

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

                   :variable_name：参数名称

                   :validate：验证参数类型，            如:string,:password,:boolean,:number,:array,:hash,:path等

                   :required：是否必须配置

                   :default：默认值

                   :deprecated：是否废弃

                   :obsolete：声明该配置不再使用，通常提供升级方案

        5.插件方法

          logstash 插件必须实现两个方法: register 和filter

          register方法如下：

register相当于初始化方法，不需要手动调用，可以在这个方法里面调用配置变量，也可以初始化自己的实例变量。

    filter方法如下:

filter方法是插件的数据处理逻辑，其中event变量封装了数据流，可以通过接口访问event中的内容，最后一句调用了filter_matched，这个方法用于保证Logstash的配置add_field, remove_field, add_tag 和remove_tag会被正确执行。

ps: 上述信息皆有官方原版，有兴趣请移步:https://www.elastic.co/guide/en/logstash/current/_how_to_write_a_logstash_filter_plugin.html

3. 额外类库添加

            这里以redis为例。

    1.安装类库:

              方式一:  切换到logstash的根目录的 vendor/jruby/bin 目录下， 然后执行  ./gem install  redis

            方式二:  直接copy redis的库到  vendor/jruby/lib/ruby/gems/shared/gems  即可使用

     2.配置类库

             在logstash-filter-test.gemspec配置文件中添加对redis的依赖，如下:

              s.add_runtime_dependency  "redis"

            3.使用类库

                  在rest.rb中require相关代码，然后使用即可

                          require "redis"

3. 在logstash中配置定制的插件

          1.切换到logstash的根目录下，在Gemfile添加以下配置:

       gem "logstash-filter-test", :path => "vendor/localgems/logstash-filter-test"

                      :path  :  是插件所放置的位置

              2.启动logstash ，配置我们定制的test插件:

./logstash  -e  "input { stdin { } } filter {test{}} output { stdout {} }"

2.一个具体的示例

      1.插件信息        

          插件功能:  把message中的ip信息根据redis中的ip库转换成地域信息，并添加额外的字段到解析后的日志中

          插件名称： xbsafe_ip

       2.安装redis库

            这里使用的是第二种方式

         2.   开始开发

首先引入类库，以及增加自己需要的配置信息:

然后是register方法，这里主要是做了redis的初始化工作，并打印出配置信息的值

filter方法 就做具体的业务逻辑，这里的getcityAndPropName方法是具体的业务方法，这里就不作展示了

        3.开始使用

打开插件目录下的logstash-filter-xbsafe_ip.gemspec,增加 s.add_runtime_dependency "redis"

打开logstash根目录下的Gemfile,在文件最下方增加自己定制的插件信息

     然后配置logstash的pipeline：

这里的input和output都用的控制台方式，因为是为了测试插件，比较方便。

       进入filter之后，会把日志信息，先进行格式的处理，拿到ip字段后使用定制的xbsafe_ip过滤器获取省份与城市，然后添加到格式化后的日志中。然后通过output就能看到最终结果。

ps:由于才刚刚接触ruby与logstash几天的时间，上述文章中不可避免会有一些错误，欢迎大家指正。另外，也希望有经验更丰富的大神给予指导，共同进步。

  在此感谢以下文章作者:

https://www.jianshu.com/p/756e404735af

https://www.elastic.co/guide/en/logstash/current/_how_to_write_a_logstash_filter_plugin.html

    https://doc.yonyoucloud.com/doc/logstash-best-practice-cn/dive_into/write_your_own.html