为 Logstash 插件贡献补丁

本节讨论您需要了解的成功为 Logstash 插件贡献补丁的信息。

每个插件都定义了自己的配置选项。 这些在某种程度上控制着插件的行为。 配置选项定义通常包括

• 数据验证
• 默认值
• 任何必需的标志

插件是 Logstash 基类的子类。 插件的基类定义了常见的配置和方法。

输入插件从外部来源提取数据。 输入插件始终与编解码器相关联。 一个输入插件总会有一个关联的编解码器插件。 输入和编解码器插件协同工作来创建一个 Logstash 事件并将该事件添加到处理队列。 输入编解码器是 LogStash::Inputs::Base 类的子类。

#register() -> nil

必需。 此 API 设置插件的资源，通常是与外部来源的连接。

#run(queue) -> nil

必需。 此 API 获取或侦听源数据，通常循环直到停止。 必须处理循环内的错误。 将任何创建的事件推送到方法参数中指定的队列对象。 一些输入可能会收到批量数据以最大限度地减少外部调用开销。

#stop() -> nil

可选。 停止外部连接并清理。

编解码器插件解码具有特定结构的输入数据，例如 JSON 输入数据。 编解码器插件是 LogStash::Codecs::Base 的子类。

#register() -> nil

与输入插件的同名 API 相同。

#decode(data){|event| block} -> nil

必须实现。 用于从方法参数中给定的原始数据创建一个 Event。 必须处理错误。 调用者必须提供一个 Ruby 块。 使用创建的 Event 调用该块。

#encode(event) -> nil

必需。 用于从给定的 Event 创建一个结构化数据对象。 可以处理错误。 此方法调用先前存储为 @on_event 的块，并带有两个参数：原始事件和数据对象。

一种更改、改变或合并一个或多个 Event 的机制。 过滤器插件是 LogStash::Filters::Base 类的子类。

#register() -> nil

与输入插件的同名 API 相同。

#filter(event) -> nil

必需。 可以处理错误。 用于将突变函数应用于给定的事件。

一种将事件发送到外部目标的机制。 此过程可能需要序列化。 输出插件是 LogStash::Outputs::Base 类的子类。

#register() -> nil

与输入插件的同名 API 相同。

#receive(event) -> nil

必需。 必须处理错误。 用于准备给定的事件以传输到外部目标。 一些输出可能会缓冲准备好的事件以批量传输到目标。

识别出 bug 或功能。 在插件存储库中创建一个问题。 创建一个补丁并提交一个 pull request (PR)。 经过审查和可能的修改后，PR 被合并并发布该插件。

社区维护者指南 更详细地解释了如何获得补丁接受、合并和发布的过程。 社区维护者指南还详细说明了贡献者和维护者应承担的角色。

测试驱动开发 (TDD) 描述了一种使用测试来指导源代码演变的方。 为了我们的目的，我们仅使用它的一部分。 在编写修复程序之前，我们创建测试，通过失败来演示该 bug。 当我们编写了足够的代码来使测试通过时，我们停止并提交修复程序和测试作为补丁。 没有必要在修复之前编写测试，但是在之后编写一个可以通过的测试非常容易，该测试可能实际上并没有验证该故障是否真的被修复，特别是如果该故障可以通过多个执行路径或不同的输入数据来触发。

Logstash 使用 Rspec（一个 Ruby 测试框架）来定义和运行测试套件。 以下是各种来源的摘要。

 2 require "logstash/devutils/rspec/spec_helper"
 3 require "logstash/plugin"
 4
 5 describe "outputs/riemann" do
 6   describe "#register" do
 7     let(:output) do
 8       LogStash::Plugin.lookup("output", "riemann").new(configuration)
 9     end
10
11     context "when no protocol is specified" do
12       let(:configuration) { Hash.new }
13
14       it "the method completes without error" do
15         expect {output.register}.not_to raise_error
16       end
17     end
18
19     context "when a bad protocol is specified" do
20       let(:configuration) { {"protocol" => "fake"} }
21
22       it "the method fails with error" do
23         expect {output.register}.to raise_error
24       end
25     end
26
27     context "when the tcp protocol is specified" do
28       let(:configuration) { {"protocol" => "tcp"} }
29
30       it "the method completes without error" do
31         expect {output.register}.not_to raise_error
32       end
33     end
34   end
35
36   describe "#receive" do
37     let(:output) do
38       LogStash::Plugin.lookup("output", "riemann").new(configuration)
39     end
40
41     context "when operating normally" do
42       let(:configuration) { Hash.new }
43       let(:event) do
44         data = {"message"=>"hello", "@version"=>"1",
45                 "@timestamp"=>"2015-06-03T23:34:54.076Z",
46                 "host"=>"vagrant-ubuntu-trusty-64"}
47         LogStash::Event.new(data)
48       end
49
50       before(:example) do
51         output.register
52       end
53
54       it "should accept the event" do
55         expect { output.receive event }.not_to raise_error
56       end
57     end
58   end
59 end

describe(string){block} -> nil
describe(Class){block} -> nil

使用 RSpec，我们始终描述插件方法的行为。 describe 块以逻辑部分添加，并且可以接受现有类名或字符串。 第 5 行中使用的字符串是插件名称。 第 6 行是 register 方法，第 36 行是 receive 方法。 按照 RSpec 惯例，实例方法以一个哈希开头，而类方法以一个点开头。

context(string){block} -> nil

在 RSpec 中，上下文块定义了按变体分组测试的部分。 字符串应以单词 when 开头，然后详细说明变体。 参见第 11 行。 内容块中的测试应仅针对该变体。

let(symbol){block} -> nil

在 RSpec 中，let 块定义了在测试块中使用的资源。 这些资源为每个测试块重新初始化。 它们可以在测试块中作为方法调用使用。 在 describe 和 context 块中定义 let 块，这些块限定了 let 块和任何其他嵌套块的范围。 您可以使用 let 块主体中稍后定义的其他 let 方法。 参见第 7-9 行，它们定义了输出资源并使用配置方法，该方法在第 12、20 和 28 行中定义了不同的变体。

before(symbol){block} -> nil - symbol is one of :suite, :context, :example, but :all and :each are synonyms for :suite and :example respectively.

在 RSpec 中，before 块用于进一步设置将在 let 块中初始化的任何资源。 您不能在 before 块内定义 let 块。

您还可以定义 after 块，这些块通常用于清理 before 块执行的任何设置活动。

it(string){block} -> nil

在 RSpec 中，it 块设置了验证测试代码行为的期望。 字符串不应以 it 或 should 开头，但需要表达期望的结果。 当将封闭的 describe、context 和 it 块中的文本放在一起时，应该形成一个相当易读的句子，如第 5、6、11 和 14 行所示。

outputs/riemann
#register when no protocol is specified the method completes without error

像这样的可读代码使测试的目标易于理解。

expect(object){block} -> nil

在 RSpec 中，expect 方法验证比较实际结果和预期结果的语句。 expect 方法通常与对 to 或 not_to 方法的调用配对。 在期望错误或观察更改时使用块形式。 to 或 not_to 方法需要一个 matcher 对象，该对象封装了预期值。 expect 方法的参数形式封装了实际值。 当将整行放在一起时，会将实际值与预期值进行测试。

raise_error(error class|nil) -> matcher instance
be(object) -> matcher instance
eq(object) -> matcher instance
eql(object) -> matcher instance
  for more see http://www.relishapp.com/rspec/rspec-expectations/docs/built-in-matchers

在 RSpec 中，匹配器是由等效的方法调用（be、eq）生成的对象，该对象将用于评估预期值与实际值。

此示例修复了 ZeroMQ 输出插件中的一个 问题。 该问题不需要了解 ZeroMQ。

此示例中的活动具有以下先决条件

• Git 和 Github 的最少知识。 参见 Github boot camp。
• 文本编辑器。
• JRuby 运行时 环境。 chruby 工具管理 Ruby 版本。
• JRuby 1.7.22 或更高版本。
• 已安装 bundler 和 rake gem。
• ZeroMQ 已安装。

1. 在 Github 中，fork ZeroMQ 输出插件存储库。

2. 在您的本地计算机上，将 fork 克隆 到已知文件夹，例如 logstash/。

3. 在文本编辑器中打开以下文件

   • logstash-output-zeromq/lib/logstash/outputs/zeromq.rb
   • logstash-output-zeromq/lib/logstash/util/zeromq.rb
   • logstash-output-zeromq/spec/outputs/zeromq_spec.rb

4. 根据该问题，服务器模式下的日志输出必须指示 bound。 此外，测试文件不包含任何测试。

   注意

   util/zeromq.rb 的第 21 行读取 @logger.info("0mq: #{server? ? 'connected' : 'bound'}", :address => address)

5. 在文本编辑器中，通过添加以下行来为文件 zeromq_spec.rb 请求 zeromq.rb

   require "logstash/outputs/zeromq"
   require "logstash/devutils/rspec/spec_helper"
   

6. 所需的错误消息应读取

   LogStash::Outputs::ZeroMQ when in server mode a 'bound' info line is logged
   

   要正确生成此消息，请添加一个以完全限定的类名作为参数的 describe 块、一个上下文块和一个 it 块。

   describe LogStash::Outputs::ZeroMQ do
     context "when in server mode" do
       it "a 'bound' info line is logged" do
       end
     end
   end
   

7. 要添加缺少的测试，请使用 ZeroMQ 输出的实例和一个替代记录器。 此示例使用一个名为测试替身的 RSpec 功能作为替代记录器。

   在 describe LogStash::Outputs::ZeroMQ do 之后和 context "when in server mode" do 之前，将以下行添加到 zeromq_spec.rb

   let(:output) { described_class.new("mode" => "server", "topology" => "pushpull" }
   let(:tracer) { double("logger") }
   

8. 将正文添加到 it 块。 在行 context "when in server mode" do 之后添加以下五行

   allow(tracer).to receive(:debug)<1>
   output.logger = logger<2>
   expect(tracer).to receive(:info).with("0mq: bound", {:address=>"tcp://127.0.0.1:2120"})<3>
   output.register<4>
   output.do_close<5>
   

9. 允许替身接收 debug 方法调用。

10. 使输出使用测试替身。

11. 设置对测试的期望以接收 info 方法调用。

12. 在输出上调用 register。

13. 在输出上调用 do_close，以便测试不会挂起。

在修改结束时，相关代码部分读取

require "logstash/outputs/zeromq"
require "logstash/devutils/rspec/spec_helper"

describe LogStash::Outputs::ZeroMQ do
  let(:output) { described_class.new("mode" => "server", "topology" => "pushpull") }
  let(:tracer) { double("logger") }

  context "when in server mode" do
    it "a ‘bound’ info line is logged" do
      allow(tracer).to receive(:debug)
      output.logger = tracer
      expect(tracer).to receive(:info).with("0mq: bound", {:address=>"tcp://127.0.0.1:2120"})
      output.register
      output.do_close
    end
  end
end

要运行此测试

1. 打开一个终端窗口
2. 导航到克隆的插件文件夹
3. 首次运行测试时，运行命令 bundle install
4. 运行命令 bundle exec rspec

假设所有先决条件都已正确安装，测试将失败并显示类似如下的输出：

Using Accessor#strict_set for specs
Run options: exclude {:redis=>true, :socket=>true, :performance=>true, :couchdb=>true, :elasticsearch=>true,
:elasticsearch_secure=>true, :export_cypher=>true, :integration=>true, :windows=>true}

LogStash::Outputs::ZeroMQ
  when in server mode
    a ‘bound’ info line is logged (FAILED - 1)

Failures:

  1) LogStash::Outputs::ZeroMQ when in server mode a ‘bound’ info line is logged
     Failure/Error: output.register
       Double "logger" received :info with unexpected arguments
         expected: ("0mq: bound", {:address=>"tcp://127.0.0.1:2120"})
              got: ("0mq: connected", {:address=>"tcp://127.0.0.1:2120"})
     # ./lib/logstash/util/zeromq.rb:21:in `setup'
     # ./lib/logstash/outputs/zeromq.rb:92:in `register'
     # ./lib/logstash/outputs/zeromq.rb:91:in `register'
     # ./spec/outputs/zeromq_spec.rb:13:in `(root)'
     # /Users/guy/.gem/jruby/1.9.3/gems/rspec-wait-0.0.7/lib/rspec/wait.rb:46:in `(root)'

Finished in 0.133 seconds (files took 1.28 seconds to load)
1 example, 1 failure

Failed examples:

rspec ./spec/outputs/zeromq_spec.rb:10

Randomized with seed 2568

1. LogStash::Outputs::ZeroMQ 在服务器模式下会记录一条 ‘bound’ 信息行

要更正此错误，请在文本编辑器中打开 util/zeromq.rb 文件，并将第 21 行上的单词 connected 和 bound 的位置互换。第 21 行现在应为：

@logger.info("0mq: #{server? ? 'bound' : 'connected'}", :address => address)

使用 bundle exec rspec 命令再次运行测试。

测试通过，并显示类似如下的输出：

Using Accessor#strict_set for specs
Run options: exclude {:redis=>true, :socket=>true, :performance=>true, :couchdb=>true, :elasticsearch=>true, :elasticsearch_secure=>true, :export_cypher=>true, :integration=>true, :windows=>true}

LogStash::Outputs::ZeroMQ
  when in server mode
    a ‘bound’ info line is logged

Finished in 0.114 seconds (files took 1.22 seconds to load)
1 example, 0 failures

Randomized with seed 45887

提交 更改到 git 和 Github。

您的 pull request 在原始 Github 存储库的 Pull Requests 部分可见。插件维护人员会审查您的工作，并在必要时提出更改建议，然后合并并发布该插件的新版本。