› ›

为 Logstash 插件贡献补丁

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

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

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

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

输入插件

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

输入 API

`#register() -> nil`	必需。此 API 为插件设置资源，通常是与外部源的连接。
`#run(queue) -> nil`	必需。此 API 获取或侦听源数据，通常循环直到停止。必须处理循环内的错误。将任何创建的事件推送到方法参数中指定的队列对象。某些输入可能会接收批处理数据以最大程度地减少外部调用开销。
`#stop() -> nil`	可选。停止外部连接并清理。

编解码器插件

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

编解码器 API

`#register() -> nil`	与输入插件的同名 API 相同。
`#decode(data){\|event\| block} -> nil`	必须实现。用于从方法参数中给出的原始数据创建事件。必须处理错误。调用者必须提供一个 Ruby 块。使用创建的事件调用该块。
`#encode(event) -> nil`	必需。用于从给定的事件创建结构化数据对象。可以处理错误。此方法使用两个参数调用先前存储为 @on_event 的块：原始事件和数据对象。

过滤器插件

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

过滤器 API

`#register() -> nil`	与输入插件的同名 API 相同。
`#filter(event) -> nil`	必需。可以处理错误。用于将变异函数应用于给定的事件。

输出插件

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

输出 API

`#register() -> nil`	与输入插件的同名 API 相同。
`#receive(event) -> nil`	必需。必须处理错误。用于准备给定的事件以传输到外部目标。某些输出可能会缓冲准备好的事件以批量传输到目标。

流程

识别错误或功能。在插件存储库中创建一个问题。创建一个补丁并提交拉取请求 (PR)。在审查和可能的返工后，PR 被合并并发布插件。

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

测试方法

测试驱动开发

测试驱动开发 (TDD) 描述了一种使用测试来指导源代码演变的方法。就我们的目的而言，我们只使用它的一部分。在编写修复程序之前，我们创建通过失败来说明错误的测试。当我们编写了足够的代码使测试通过时，我们就会停止，并将修复程序和测试作为补丁提交。没有必要在修复之前编写测试，但是之后编写一个通过测试非常容易，该测试实际上可能无法验证错误是否真的已修复，尤其是在可以通过多个执行路径或不同的输入数据触发错误的情况下。

RSpec 框架

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

RSpec 示例。

 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

描述块（示例 1 中的第 5、6 和 36 行）。

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

使用 RSpec，我们始终在描述插件方法行为。描述块在逻辑部分中添加，并且可以接受现有类名或字符串。第 5 行中使用的字符串是插件名称。第 6 行是 register 方法，第 36 行是 receive 方法。用一个井号作为实例方法的前缀，用一个点作为类方法的前缀是 RSpec 约定。

上下文块（第 11、19、27 和 41 行）。

context(string){block} -> nil

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

Let 块（第 7、12、20、28、37、42 和 43 行）。

let(symbol){block} -> nil

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

Before 块（第 50 行）。

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 块（第 14、22、30 和 54 行）。

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 方法（第 15、23、31、55 行）。

expect(object){block} -> nil

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

Matcher 方法（第 15、23、31、55 行）。

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 新手训练营。
文本编辑器。
JRuby 运行时环境。chruby 工具管理 Ruby 版本。
JRuby 1.7.22 或更高版本。
安装了 bundler 和 rake gem。
ZeroMQ 已安装。

在 Github 中，fork ZeroMQ 输出插件存储库。
在您的本地机器上，将 fork 克隆到已知文件夹，例如 logstash/。
在文本编辑器中打开以下文件
- logstash-output-zeromq/lib/logstash/outputs/zeromq.rb
- logstash-output-zeromq/lib/logstash/util/zeromq.rb
- logstash-output-zeromq/spec/outputs/zeromq_spec.rb
根据问题，服务器模式下的日志输出必须指示 bound。此外，测试文件不包含任何测试。

util/zeromq.rb 的第 21 行读取 @logger.info("0mq: #{server? ? 'connected' : 'bound'}", :address => address)
在文本编辑器中，通过添加以下行来要求 zeromq.rb 用于文件 zeromq_spec.rb
```
require "logstash/outputs/zeromq"
require "logstash/devutils/rspec/spec_helper"
```

所需的错误消息应显示为

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

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

将以下行添加到 zeromq_spec.rb，位于 describe LogStash::Outputs::ZeroMQ do 之后和 context "when in server mode" do 之前
```
  let(:output) { described_class.new("mode" => "server", "topology" => "pushpull" }
  let(:tracer) { double("logger") }
```

将主体添加到 it 块。在 context "when in server mode" do 行之后添加以下五行

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

	允许替身接收 `debug` 方法调用。
	使输出使用测试替身。
	对测试设置期望以接收 `info` 方法调用。
	在输出上调用 `register`。
	在输出上调用 `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

要運行此測試

打開終端窗口
導航到克隆的插件文件夾
第一次運行測試時，請運行命令 bundle install
運行命令 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 # LogStash::Outputs::ZeroMQ when in server mode a ‘bound’ info line is logged

Randomized with seed 2568

要糾正此錯誤，請在文本編輯器中打開 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。

您的拉取請求在原始 Github 存儲庫的拉取請求部分中可見。插件維護者會審查您的工作，如有必要，會建議更改，並合併和發布新版本的插件。

« 列出您的插件扩展 Logstash 核心 »