github-mirrors/logstash
1
0
Fork 0
mirror of https://github.com/elastic/logstash.git synced 2025-04-24 14:47:19 -04:00
Code Issues Projects Releases Packages Wiki Activity

Incorporate review comments

Browse source 
Fixes #9861
This commit is contained in:
Karen Metts 2018-08-02 11:03:22 -04:00
parent 92dd9a932f
commit b83d8a0dee
2 changed files with 160 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

140
docs/static/doc-for-plugin.asciidoc vendored
View file

@ -3,27 +3,27 @@
Quality documentation with good examples contributes to the adoption of your plugin.
The documentation for your plugin will be generated and published in the
{logstash-ref}/index.html[Logstash Reference] and the
{lsplugindocs}[Versioned plugin docs].
The documentation that you write for your plugin will be generated and published
in the {logstash-ref}/index.html[Logstash Reference] and the
{lsplugindocs}[Logstash Versioned Plugin Reference].
[[plugin-doc-file]]
==== Documentation file
Documentation should be included in your plugin structure as a single file called 'docs/index.asciidoc'.
Include documentation in your plugin structure as a single file called 'docs/index.asciidoc'.
[[heading-ids]]
==== Heading IDs
Heading IDs must be in a format that supports generated IDs. This approach
creates unique IDs when the
{lsplugindocs}[Versioned plugin docs] are generated.
Format heading anchors with variables that can support generated IDs. This approach
creates unique IDs when the {lsplugindocs}[Logstash Versioned Plugin Reference]
is built. Unique heading IDs are required to avoid duplication over multiple versions of a plugin.
*Example*
Don't hardcode a heading ID like this: `[[config_models]]`
Instead, define it like this:
Instead, use variables to define it:
[source,txt]
----------------------------------
@ -31,9 +31,82 @@ Instead, define it like this:
==== Configuration models
----------------------------------
If you hardcode an ID, the versioned plugin docs will build correctly the
first time. The second time the doc build runs, the ID will be flagged as
a duplicate, and the build will fail.
If you hardcode an ID, the {lsplugindocs}[Logstash Versioned Plugin Reference]
builds correctly the first time. The second time the doc build runs, the ID
is flagged as a duplicate, and the build fails.
[[link-format]]
==== Link formats
Correct link formatting is essential for directing users to the content you
want them to see. Incorrect link formatting or duplicate links can break the
documentation build. Let's not do that.
===== Link to content in the same file
Use angle brackets to format links to content in the same asciidoc file.
*Example*
This link:
[source,txt]
-----
<<plugins-{type}s-{plugin}-config_models>>
-----
Points to this heading in the same file:
[source,txt]
----------------------------------
[id="plugins-{type}s-{plugin}-config_models"]
==== Configuration models
----------------------------------
===== Link to content in the Logstash Reference Guide
Use external link syntax for links that point to documentation for other plugins or content in the Logstash Reference Guide.
*Examples*
[source,txt]
-----
{logstash-ref}/plugins-codecs-multiline.html[Multiline codec plugin]
-----
[source,txt]
-----
{logstash-ref}/getting-started-with-logstash.html
-----
===== Links specifying link text
If you don't specify link text, the URL is used as the link text.
*Examples*
If you want your link to display as {logstash-ref}/getting-started-with-logstash.html, use this format:
[source,txt]
-----
{logstash-ref}/getting-started-with-logstash.html
-----
If you want your link to display as {logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash], use this format:
[source,txt]
-----
{logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash]
-----
===== Link to data type descriptions
We make an exception for links that point to data type descriptions,
such as `<<boolean,boolean>>`, because they are used so frequently.
We have a cleanup step in the conversion script that converts the links to the
correct syntax.
[[format-code]]
==== Code samples
@ -41,23 +114,23 @@ a duplicate, and the build will fail.
We all love code samples. Asciidoc supports code blocks and config examples.
To include Ruby code, use the asciidoc `[source,ruby]` directive.
Note that the hash marks (#) are present to make the example render correctly.
Don't include the hash marks in your asciidoc file.
Note that the hashmarks (#) are present to make the example render correctly.
Don't include the hashmarks in your asciidoc file.
[source,txt]
[subs="attributes"]
----------------------------------
# [source,ruby]
# ----------------------------------
# -----
# match => {
# "field1" => "value1"
# "field2" => "value2"
# ...
# }
# ----------------------------------
# -----
----------------------------------
This sample renders in the documentation like this:
The sample above (with hashmarks removed) renders in the documentation like this:
[source,ruby]
----------------------------------
match => {
@ -67,10 +140,43 @@ match => {
}
----------------------------------
==== Where's my doc?
Plugin documentation goes through several steps before it gets published in the
{lsplugindocs}[Logstash Versioned Plugin Reference] and the {logstash-ref}/index.html[Logstash Reference].
Here's an overview of the workflow:
* Be sure that you have signed the CLI and have all necessary approvals and sign offs.
* Merge the pull request for your plugin (including the `index.asciidoc` file, the `changelog.md` file, and the gemspec).
* Wait for the continuous integration build to complete successfully.
* Publish the plugin to https://rubygems.org.
* A script detects the new or changed version, and picks up the `index.asciidoc` file for inclusion in the doc build.
* The documentation for your new plugin is published in the {lsplugindocs}[Logstash Versioned Plugin Reference].
We're not done yet.
* For each release, we package the new and changed documentation files into a pull request to add or update content.
(We sometimes package plugin docs between releases if we make significant changes to plugin documentation or add a new plugin.)
* The script detects the new or changed version, and picks up the `index.asciidoc` file for inclusion in the doc build.
* We create a pull request, and merge the new and changed content into the appropriate version branches.
* For a new plugin, we add a link to the list of plugins in the {logstash-ref}/index.html[Logstash Reference].
* The documentation for your new (or changed) plugin is published in the {logstash-ref}/index.html[Logstash Reference].
===== Documentation or plugin updates
When you make updates to your plugin or the documentation, consider
bumping the version number in the changelog and gemspec (or version file). The
version change triggers the doc build to pick up your changes for publishing.
==== Resources
For more asciidoc formatting tips, see the excellent reference at
https://github.com/elastic/docs#asciidoc-guide
https://github.com/elastic/docs#asciidoc-guide.
For tips on contributing and changelog guidelines, see
https://github.com/elastic/logstash/blob/master/CONTRIBUTING.md#logstash-plugin-changelog-guidelines[CONTRIBUTING.md].
For general information about contributing, see
{logstash-ref}/contributing-to-logstash.html[Contributing to Logtash].

73
docs/static/include/pluginbody.asciidoc vendored
View file

@ -13,7 +13,7 @@ https://www.ruby-lang.org/en/documentation/quickstart/[].)
{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:
. Log in to GitHub.
@ -25,7 +25,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.
. Click **Create Repository**.
==== Use the plugin generator tool
===== Use the plugin generator tool
You can now create your own Logstash plugin in seconds! The `generate` subcommand of `bin/logstash-plugin` creates the foundation
for a new Logstash plugin with templatized files. It creates the correct directory structure, gemspec files, and dependencies so you
@ -33,7 +33,7 @@ can start adding custom code to process data with Logstash.
For more information, see <<plugin-generator>>
==== Copy the {plugintype} code
===== Copy the {plugintype} code
Alternatively, you can use the examples repo we host on github.com
@ -92,7 +92,7 @@ For more information about the Ruby gem file structure and an excellent
walkthrough of the Ruby gem creation process, see
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
and take a look.
@ -312,7 +312,7 @@ endif::multi_receive_method[]
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
beginning of your plugin code:
@ -325,7 +325,7 @@ beginning of your plugin code:
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.
==== `require` Statements
===== `require` Statements
Logstash {plugintype} plugins require parent classes defined in
+logstash/pass:attributes[{plugintype}]s/base+ and logstash/namespace:
@ -344,16 +344,7 @@ them here along with these Logstash dependencies.
Let's go through the various elements of the plugin itself.
==== Documentation for your plugin
Documentation is an important part of your plugin. All plugin documentation is
rendered and placed in the
http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash
Reference] and the {lsplugindocs}[Versioned plugin docs].
See <<plugin-doc>> for tips and guidelines.
==== `class` Declaration
===== `class` Declaration
The {plugintype} plugin class should be a subclass of
+LogStash::pass:attributes[{pluginclass}]::Base+:
@ -370,7 +361,7 @@ The class name should closely mirror the plugin name, for example:
LogStash::{pluginclass}::{pluginnamecap}
----
==== `config_name`
===== `config_name`
[source,ruby]
[subs="attributes"]
----------------------------------
@ -455,7 +446,7 @@ will become a valid boolean in the config. This coercion works for the
// /////////////////////////////////////////////////////////////////////////////
ifdef::register_method[]
==== `register` Method
===== `register` Method
[source,ruby]
[subs="attributes"]
----------------------------------
@ -484,7 +475,7 @@ endif::register_method[]
ifdef::filter_method[]
ifndef::blockfilter[]
==== `filter` Method
===== `filter` Method
[source,ruby]
[subs="attributes"]
@ -539,7 +530,7 @@ endif::filter_method[]
ifdef::decode_method[]
ifndef::blockcodec[]
==== `decode` Method
===== `decode` Method
[source,ruby]
[subs="attributes"]
@ -569,7 +560,7 @@ endif::decode_method[]
ifdef::encode_method[]
ifndef::blockcodec[]
==== `encode` Method
===== `encode` Method
[source,ruby]
[subs="attributes"]
@ -596,7 +587,7 @@ endif::encode_method[]
ifdef::run_method[]
ifndef::blockinput[]
==== `run` Method
===== `run` Method
The {pluginname} input plugin has the following `run` Method:
@ -684,7 +675,7 @@ endif::run_method[]
// /////////////////////////////////////////////////////////////////////////////
ifdef::receive_method[]
==== `receive` Method
===== `receive` Method
[source,ruby]
[subs="attributes"]
@ -747,9 +738,9 @@ endif::receive_method[]
==== Building the Plugin
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 information will help you complete the process.
==== External dependencies
===== External dependencies
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
@ -788,7 +779,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
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.
Currently, all we'll need is the Logstash gem, for testing, but if you require
@ -854,7 +845,7 @@ please make sure to have this line in your gemspec:
The gem version, designated by `s.version`, helps track changes to plugins over
time. You should use http://semver.org/[semver versioning] strategy for version numbers.
==== Runtime & Development Dependencies
===== Runtime and Development Dependencies
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
@ -881,7 +872,7 @@ it have a version number greater than or equal to version 1.60 and less than or
IMPORTANT: All plugins have a runtime dependency on the `logstash-core-plugin-api` gem, and
a development dependency on `logstash-devutils`.
==== Jar dependencies
===== Jar dependencies
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],
@ -899,6 +890,16 @@ added in the gemspec file in this manner:
With these both defined, the install process will search for the required jar
file at http://mvnrepository.com and download the specified version.
==== Document your plugin
Documentation is an important part of your plugin. All plugin documentation is
rendered and placed in the
http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash
Reference] and the {lsplugindocs}[Versioned plugin docs].
See <<plugin-doc>> for tips and guidelines.
==== Add Tests
Logstash loves tests. Lots of tests. If you're using your new {plugintype}
@ -960,7 +961,7 @@ Hooray! You're almost there! (Unless you saw failures... you should fix those
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
build command:
@ -979,7 +980,7 @@ logstash-{plugintype}-mypluginname-0.1.0.gem
The `s.version` number from your gemspec file will provide the gem version, in
this case, `0.1.0`.
==== Test installation
===== Test installation
You should test install your plugin into a clean installation of Logstash.
Download the latest version from the
@ -1166,7 +1167,7 @@ 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
Logstash users by simply publishing it to RubyGems.org.
==== Licensing
===== Licensing
Logstash and all its plugins are licensed under
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],
@ -1174,7 +1175,7 @@ please make sure to have this line in your gemspec:
* `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
@ -1235,7 +1236,7 @@ It is not required to contribute your source code to
https://github.com/logstash-plugins[logstash-plugins] github organization, but
we always welcome new plugins!
==== Benefits
===== Benefits
Some of the many benefits of having your plugin in the logstash-plugins
repository are:
@ -1249,11 +1250,11 @@ tested against current and future releases of Logstash. As a result, users will
have the assurance that if incompatibilities arise, they will be quickly
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.
* **Tests** Your plugin must contain tests to be accepted. These tests are also
* **Tests.** Your plugin must contain tests to be accepted. These tests are also
subject to code review for scope and completeness. It's ok if you don't know
how to write tests -- we will guide you. We are working on publishing a guide to
creating tests for Logstash which will make it easier. In the meantime, you can