github-mirrors/logstash
1
0
Fork 0
mirror of https://github.com/elastic/logstash.git synced 2025-04-25 07:07:54 -04:00
Code Issues Projects Releases Packages Wiki Activity

Changes file hierarchy for Contributing to Logstash

Browse source 
Fixes #3708
This commit is contained in:
Paul Echeverri 2015-08-12 12:46:58 -07:00 • committed by Jordan Sissel
parent 73a38043fa
commit f6444ef962
2 changed files with 38 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/asciidoc/static/contributing-to-logstash.asciidoc
View file

@ -1,5 +1,5 @@
[[contributing-to-logstash]] [[contributing-to-logstash]]
=== Contributing to Logstash == Contributing to Logstash
Before version 1.5, Logstash included all plugins in each release. This made it Before version 1.5, Logstash included all plugins in each release. This made it
easy to make use of any plugin, but it complicated plugin development--a new easy to make use of any plugin, but it complicated plugin development--a new
@ -8,7 +8,7 @@ release of Logstash became necessary if a plugin needed patching. Since version
input, codec, filter, or output plugins to Logstash much more easily! input, codec, filter, or output plugins to Logstash much more easily!
[float] [float]
==== Adding plugins === Adding plugins
Since plugins can now be developed and deployed independently of the Logstash Since plugins can now be developed and deployed independently of the Logstash
core, there are documents which guide you through the process of coding and core, there are documents which guide you through the process of coding and
@ -20,7 +20,7 @@ deploying your own plugins:
* http://www.elasticsearch.org/guide/en/logstash/current/_how_to_write_a_logstash_output_plugin.html[How to write a Logstash output plugin] * http://www.elasticsearch.org/guide/en/logstash/current/_how_to_write_a_logstash_output_plugin.html[How to write a Logstash output plugin]
[float] [float]
==== Extending Logstash core === Extending Logstash core
We also welcome contributions and bug fixes to the Logstash core feature set. We also welcome contributions and bug fixes to the Logstash core feature set.

70
docs/asciidoc/static/include/pluginbody.asciidoc
View file

@ -1,6 +1,6 @@
pass::[<?edit_url https://github.com/elastic/logstash/edit/master/docs/asciidoc/static/include/pluginbody.asciidoc ?>] pass::[<?edit_url https://github.com/elastic/logstash/edit/master/docs/asciidoc/static/include/pluginbody.asciidoc ?>]
==== How to write a Logstash {plugintype} plugin === How to write a Logstash {plugintype} plugin
To develop a new {plugintype} for Logstash, you build a self-contained Ruby gem To develop a new {plugintype} for Logstash, you build a self-contained Ruby gem
whose source code lives in its own GitHub repository. The Ruby gem can then be whose source code lives in its own GitHub repository. The Ruby gem can then be
@ -17,7 +17,7 @@ versions, plugins were part of the core Logstash distribution.
{getstarted} {getstarted}
===== Create a GitHub repo for your new plugin ==== Create a GitHub repo for your new plugin
Each Logstash plugin lives in its own GitHub repository. To create a new repository for your plugin: Each Logstash plugin lives in its own GitHub repository. To create a new repository for your plugin:
. Log in to GitHub. . Log in to GitHub.
@ -29,7 +29,7 @@ Each Logstash plugin lives in its own GitHub repository. To create a new reposit
** **Initialize this repository with a README** -- enables you to immediately clone the repository to your computer. ** **Initialize this repository with a README** -- enables you to immediately clone the repository to your computer.
. Click **Create Repository**. . Click **Create Repository**.
===== Copy the {plugintype} code ==== Copy the {plugintype} code
Build your local repository: Build your local repository:
@ -88,7 +88,7 @@ For more information about the Ruby gem file structure and an excellent
walkthrough of the Ruby gem creation process, see walkthrough of the Ruby gem creation process, see
http://timelessrepo.com/making-ruby-gems http://timelessrepo.com/making-ruby-gems
===== See what your plugin looks like ==== See what your plugin looks like
Before we dive into the details, open up the plugin file in your favorite text editor Before we dive into the details, open up the plugin file in your favorite text editor
and take a look. and take a look.
@ -287,11 +287,11 @@ end # class LogStash::{pluginclass}::{pluginnamecap}
---------------------------------- ----------------------------------
endif::receive_method[] endif::receive_method[]
===== Coding {plugintype} plugins ==== Coding {plugintype} plugins
Now let's take a line-by-line look at the example plugin. Now let's take a line-by-line look at the example plugin.
===== `encoding` ==== `encoding`
It seems like a small thing, but remember to specify the encoding at the It seems like a small thing, but remember to specify the encoding at the
beginning of your plugin code: beginning of your plugin code:
@ -304,7 +304,7 @@ beginning of your plugin code:
Logstash depends on things being in UTF-8, so we put this here to tell the Ruby Logstash depends on things being in UTF-8, so we put this here to tell the Ruby
interpreter that we’re going to be using the UTF-8 encoding. interpreter that we’re going to be using the UTF-8 encoding.
===== `require` Statements ==== `require` Statements
Logstash {plugintype} plugins require parent classes defined in Logstash {plugintype} plugins require parent classes defined in
+logstash/pass:attributes[{plugintype}]s/base+ and logstash/namespace: +logstash/pass:attributes[{plugintype}]s/base+ and logstash/namespace:
@ -319,11 +319,11 @@ require "logstash/namespace"
Of course, the plugin you build may depend on other code, or even gems. Just put Of course, the plugin you build may depend on other code, or even gems. Just put
them here along with these Logstash dependencies. them here along with these Logstash dependencies.
===== Plugin Body ==== Plugin Body
Let's go through the various elements of the plugin itself. Let's go through the various elements of the plugin itself.
===== Inline Documentation ==== Inline Documentation
Logstash provides infrastructure to automatically generate documentation for Logstash provides infrastructure to automatically generate documentation for
plugins. We use the asciidoc format to write documentation so _any_ comments in plugins. We use the asciidoc format to write documentation so _any_ comments in
the source code will be first converted into asciidoc and then into html. the source code will be first converted into asciidoc and then into html.
@ -367,7 +367,7 @@ match => {
TIP: For more asciidoc formatting tips, see the excellent reference at TIP: For more asciidoc formatting tips, see the excellent reference at
https://github.com/elastic/docs#asciidoc-guide https://github.com/elastic/docs#asciidoc-guide
===== `class` Declaration ==== `class` Declaration
The {plugintype} plugin class should be a subclass of The {plugintype} plugin class should be a subclass of
+LogStash::pass:attributes[{pluginclass}]::Base+: +LogStash::pass:attributes[{pluginclass}]::Base+:
@ -384,7 +384,7 @@ The class name should closely mirror the plugin name, for example:
LogStash::{pluginclass}::{pluginnamecap} LogStash::{pluginclass}::{pluginnamecap}
---- ----
===== `config_name` ==== `config_name`
[source,ruby] [source,ruby]
[subs="attributes"] [subs="attributes"]
---------------------------------- ----------------------------------
@ -436,7 +436,7 @@ output {
endif::blockinput[] endif::blockinput[]
endif::encode_method[] endif::encode_method[]
===== Configuration Parameters ==== Configuration Parameters
[source,ruby] [source,ruby]
---------------------------------- ----------------------------------
config :variable_name, :validate => :variable_type, :default => "Default value", :required => boolean, :deprecated => boolean config :variable_name, :validate => :variable_type, :default => "Default value", :required => boolean, :deprecated => boolean
@ -458,7 +458,7 @@ will become a valid boolean in the config. This coercion works for the
`false`) `false`)
* `:deprecated` - informational (also a Boolean `true` or `false`) * `:deprecated` - informational (also a Boolean `true` or `false`)
===== Plugin Methods ==== Plugin Methods
{methodheader} {methodheader}
@ -467,7 +467,7 @@ will become a valid boolean in the config. This coercion works for the
// ///////////////////////////////////////////////////////////////////////////// // /////////////////////////////////////////////////////////////////////////////
ifdef::register_method[] ifdef::register_method[]
===== `register` Method ==== `register` Method
[source,ruby] [source,ruby]
[subs="attributes"] [subs="attributes"]
---------------------------------- ----------------------------------
@ -496,7 +496,7 @@ endif::register_method[]
ifdef::filter_method[] ifdef::filter_method[]
ifndef::blockfilter[] ifndef::blockfilter[]
===== `filter` Method ==== `filter` Method
[source,ruby] [source,ruby]
[subs="attributes"] [subs="attributes"]
@ -539,7 +539,7 @@ endif::filter_method[]
ifdef::decode_method[] ifdef::decode_method[]
ifndef::blockcodec[] ifndef::blockcodec[]
===== `decode` Method ==== `decode` Method
[source,ruby] [source,ruby]
[subs="attributes"] [subs="attributes"]
@ -569,7 +569,7 @@ endif::decode_method[]
ifdef::encode_method[] ifdef::encode_method[]
ifndef::blockcodec[] ifndef::blockcodec[]
===== `encode` Method ==== `encode` Method
[source,ruby] [source,ruby]
[subs="attributes"] [subs="attributes"]
@ -596,7 +596,7 @@ endif::encode_method[]
ifdef::run_method[] ifdef::run_method[]
ifndef::blockinput[] ifndef::blockinput[]
===== `run` Method ==== `run` Method
The {pluginname} input plugin has the following `run` Method: The {pluginname} input plugin has the following `run` Method:
@ -684,7 +684,7 @@ endif::run_method[]
// ///////////////////////////////////////////////////////////////////////////// // /////////////////////////////////////////////////////////////////////////////
ifdef::receive_method[] ifdef::receive_method[]
===== `receive` Method ==== `receive` Method
[source,ruby] [source,ruby]
[subs="attributes"] [subs="attributes"]
@ -749,7 +749,7 @@ endif::receive_method[]
At this point in the process you have coded your plugin and are ready to build At this point in the process you have coded your plugin and are ready to build
a Ruby Gem from it. The following steps will help you complete the process. a Ruby Gem from it. The following steps will help you complete the process.
===== External dependencies ==== External dependencies
A `require` statement in Ruby is used to include necessary code. In some cases A `require` statement in Ruby is used to include necessary code. In some cases
your plugin may require additional files. For example, the collectd plugin your plugin may require additional files. For example, the collectd plugin
@ -788,7 +788,7 @@ will be discussed further in the testing section of this document.
Another kind of external dependency is on jar files. This will be described Another kind of external dependency is on jar files. This will be described
in the "Add a `gemspec` file" section. in the "Add a `gemspec` file" section.
===== Add a Gemfile ==== Add a Gemfile
Gemfiles allow Ruby's Bundler to maintain the dependencies for your plugin. Gemfiles allow Ruby's Bundler to maintain the dependencies for your plugin.
Currently, all we'll need is the Logstash gem, for testing, but if you require Currently, all we'll need is the Logstash gem, for testing, but if you require
@ -804,7 +804,7 @@ gemspec
gem "logstash", :github => "elastic/logstash", :branch => "{branch}" gem "logstash", :github => "elastic/logstash", :branch => "{branch}"
---------------------------------- ----------------------------------
===== Add a `gemspec` file ==== Add a `gemspec` file
Gemspecs define the Ruby gem which will be built and contain your plugin. Gemspecs define the Ruby gem which will be built and contain your plugin.
TIP: More information can be found on the TIP: More information can be found on the
@ -875,7 +875,7 @@ This plugin should work but would benefit from use by folks like you. Please let
You will no longer see a message indicating potential code immaturity when a You will no longer see a message indicating potential code immaturity when a
plugin reaches version 1.0.0 plugin reaches version 1.0.0
===== Runtime & Development Dependencies ==== Runtime & Development Dependencies
At the bottom of the `gemspec` file is a section with a comment: At the bottom of the `gemspec` file is a section with a comment:
`Gem dependencies`. This is where any other needed gems must be mentioned. If `Gem dependencies`. This is where any other needed gems must be mentioned. If
@ -903,7 +903,7 @@ and less than version 2.0 `'< 2.0.0'`.
IMPORTANT: All plugins have a runtime dependency on the `logstash` core gem, and IMPORTANT: All plugins have a runtime dependency on the `logstash` core gem, and
a development dependency on `logstash-devutils`. a development dependency on `logstash-devutils`.
===== Jar dependencies ==== Jar dependencies
In some cases, such as the In some cases, such as the
https://github.com/logstash-plugins/logstash-output-elasticsearch/blob/master/logstash-output-elasticsearch.gemspec#L22-L23[Elasticsearch output plugin], https://github.com/logstash-plugins/logstash-output-elasticsearch/blob/master/logstash-output-elasticsearch.gemspec#L22-L23[Elasticsearch output plugin],
@ -921,7 +921,7 @@ added in the gemspec file in this manner:
With these both defined, the install process will search for the required jar With these both defined, the install process will search for the required jar
file at http://mvnrepository.com and download the specified version. file at http://mvnrepository.com and download the specified version.
===== Add Tests ==== Add Tests
Logstash loves tests. Lots of tests. If you're using your new {plugintype} Logstash loves tests. Lots of tests. If you're using your new {plugintype}
plugin in a production environment, you'll want to have some tests to ensure you plugin in a production environment, you'll want to have some tests to ensure you
@ -934,7 +934,7 @@ For help learning about tests and testing, look in the
+spec/pass:attributes[{plugintype}]s/+ directory of several other similar +spec/pass:attributes[{plugintype}]s/+ directory of several other similar
plugins. plugins.
===== Clone and test! ==== Clone and test!
Now let's start with a fresh clone of the plugin, build it and run the tests. Now let's start with a fresh clone of the plugin, build it and run the tests.
@ -978,11 +978,11 @@ Finished in 0.034 seconds
Hooray! You're almost there! (Unless you saw failures... you should fix those Hooray! You're almost there! (Unless you saw failures... you should fix those
first). first).
===== Building and Testing ==== Building and Testing
Now you're ready to build your (well-tested) plugin into a Ruby gem. Now you're ready to build your (well-tested) plugin into a Ruby gem.
===== Build ==== Build
You already have all the necessary ingredients, so let's go ahead and run the You already have all the necessary ingredients, so let's go ahead and run the
build command: build command:
@ -1001,7 +1001,7 @@ logstash-{plugintype}-mypluginname-0.1.0.gem
The `s.version` number from your gemspec file will provide the gem version, in The `s.version` number from your gemspec file will provide the gem version, in
this case, `0.1.0`. this case, `0.1.0`.
===== Test installation ==== Test installation
You should test install your plugin into a clean installation of Logstash. You should test install your plugin into a clean installation of Logstash.
Download the latest version from the Download the latest version from the
@ -1182,13 +1182,13 @@ endif::receive_method[]
Congratulations! You've built, deployed and successfully run a Logstash Congratulations! You've built, deployed and successfully run a Logstash
{plugintype}. {plugintype}.
===== Submitting your plugin to http://rubygems.org[RubyGems.org] and https://github.com/logstash-plugins[logstash-plugins] ==== Submitting your plugin to http://rubygems.org[RubyGems.org] and https://github.com/logstash-plugins[logstash-plugins]
Logstash uses http://rubygems.org[RubyGems.org] as its repository for all plugin Logstash uses http://rubygems.org[RubyGems.org] as its repository for all plugin
artifacts. Once you have developed your new plugin, you can make it available to artifacts. Once you have developed your new plugin, you can make it available to
Logstash users by simply publishing it to RubyGems.org. Logstash users by simply publishing it to RubyGems.org.
===== Licensing ==== Licensing
Logstash and all its plugins are licensed under Logstash and all its plugins are licensed under
https://github.com/elasticsearch/logstash/blob/master/LICENSE[Apache License, version 2 ("ALv2")]. https://github.com/elasticsearch/logstash/blob/master/LICENSE[Apache License, version 2 ("ALv2")].
If you make your plugin publicly available via http://rubygems.org[RubyGems.org], If you make your plugin publicly available via http://rubygems.org[RubyGems.org],
@ -1196,7 +1196,7 @@ please make sure to have this line in your gemspec:
* `s.licenses = ['Apache License (2.0)']` * `s.licenses = ['Apache License (2.0)']`
===== Publishing to http://rubygems.org[RubyGems.org] ==== Publishing to http://rubygems.org[RubyGems.org]
To begin, you’ll need an account on RubyGems.org To begin, you’ll need an account on RubyGems.org
@ -1251,13 +1251,13 @@ by running:
bin/plugin install logstash-{plugintype}-mypluginname bin/plugin install logstash-{plugintype}-mypluginname
---------------------------------- ----------------------------------
===== Contributing your source code to https://github.com/logstash-plugins[logstash-plugins] ==== Contributing your source code to https://github.com/logstash-plugins[logstash-plugins]
It is not required to contribute your source code to It is not required to contribute your source code to
https://github.com/logstash-plugins[logstash-plugins] github organization, but https://github.com/logstash-plugins[logstash-plugins] github organization, but
we always welcome new plugins! we always welcome new plugins!
===== Benefits ==== Benefits
Some of the many benefits of having your plugin in the logstash-plugins Some of the many benefits of having your plugin in the logstash-plugins
repository are: repository are:
@ -1271,7 +1271,7 @@ tested against current and future releases of Logstash. As a result, users will
have the assurance that if incompatibilities arise, they will be quickly have the assurance that if incompatibilities arise, they will be quickly
discovered and corrected. discovered and corrected.
===== Acceptance Guidelines ==== Acceptance Guidelines
* **Code Review** Your plugin must be reviewed by members of the community for * **Code Review** Your plugin must be reviewed by members of the community for
coherence, quality, readability, stability and security. coherence, quality, readability, stability and security.