Update shared files to support versioned plugin docs (#8937)

* Update shared files to support versioned plugin docs

test

* Make common files work for LS Ref and versioned plugin ref

* Remove plugin name from TOC entry

* Remove plugin-intro because it needs to live in logstash-docs only

* Edit common files
This commit is contained in:
DeDe Morton 2018-01-26 14:45:34 -08:00 committed by GitHub
parent 42a7da2bcd
commit 5931e98c55
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 214 additions and 36 deletions

View file

@ -1,23 +1,47 @@
==== Common Options
// Contributors: You must conditionally code all internal links and IDs in this
// file to make the common files work in both the LS Reference and the versioned
// plugin docs
The following configuration options are supported by all filter plugins:
ifeval::["{versioned_docs}"!="true"]
[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-add_field>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-add_tag>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-enable_metric>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-id>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-periodic_flush>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-remove_field>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-remove_tag>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-add_field>> |{logstash-ref}/configuration-file-structure.html#hash[hash]|No
| <<plugins-{type}s-{plugin}-add_tag>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
| <<plugins-{type}s-{plugin}-enable_metric>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<plugins-{type}s-{plugin}-id>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
| <<plugins-{type}s-{plugin}-periodic_flush>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<plugins-{type}s-{plugin}-remove_field>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
| <<plugins-{type}s-{plugin}-remove_tag>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
|=======================================================================
endif::[]
ifeval::["{versioned_docs}"=="true"]
[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<{version}-plugins-{type}s-{plugin}-add_field>> |{logstash-ref}/configuration-file-structure.html#hash[hash]|No
| <<{version}-plugins-{type}s-{plugin}-add_tag>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
| <<{version}-plugins-{type}s-{plugin}-enable_metric>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<{version}-plugins-{type}s-{plugin}-id>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
| <<{version}-plugins-{type}s-{plugin}-periodic_flush>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<{version}-plugins-{type}s-{plugin}-remove_field>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
| <<{version}-plugins-{type}s-{plugin}-remove_tag>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
|=======================================================================
endif::[]
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-add_field"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-add_field"]
endif::[]
===== `add_field`
* Value type is <<hash,hash>>
* Value type is {logstash-ref}/configuration-file-structure.html#hash[hash]
* Default value is `{}`
If this filter is successful, add any arbitrary fields to this event.
@ -48,10 +72,15 @@ would add field `foo_hello` if it is present, with the
value above and the `%{host}` piece replaced with that value from the
event. The second example would also add a hardcoded field.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-add_tag"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-add_tag"]
endif::[]
===== `add_tag`
* Value type is <<array,array>>
* Value type is {logstash-ref}/configuration-file-structure.html#array[array]
* Default value is `[]`
If this filter is successful, add arbitrary tags to the event.
@ -78,20 +107,30 @@ Example:
If the event has field `"somefield" == "hello"` this filter, on success,
would add a tag `foo_hello` (and the second example would of course add a `taggedy_tag` tag).
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-enable_metric"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-enable_metric"]
endif::[]
===== `enable_metric`
* Value type is <<boolean,boolean>>
* Value type is {logstash-ref}/configuration-file-structure.html#boolean[boolean]
* Default value is `true`
Disable or enable metric logging for this specific plugin instance
by default we record all the metrics we can, but you can disable metrics collection
for a specific plugin.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-id"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-id"]
endif::[]
===== `id`
* Value type is <<string,string>>
* Value type is {logstash-ref}/configuration-file-structure.html#string[string]
* There is no default value for this setting.
Add a unique `ID` to the plugin configuration. If no ID is specified, Logstash will generate one.
@ -107,19 +146,30 @@ Adding a named ID in this case will help in monitoring Logstash when using the m
}
}
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-periodic_flush"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-periodic_flush"]
endif::[]
===== `periodic_flush`
* Value type is <<boolean,boolean>>
* Value type is {logstash-ref}/configuration-file-structure.html#boolean[boolean]
* Default value is `false`
Call the filter flush method at regular interval.
Optional.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-remove_field"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-remove_field"]
endif::[]
===== `remove_field`
* Value type is <<array,array>>
* Value type is {logstash-ref}/configuration-file-structure.html#array[array]
* Default value is `[]`
If this filter is successful, remove arbitrary fields from this event.
@ -145,10 +195,15 @@ If the event has field `"somefield" == "hello"` this filter, on success,
would remove the field with name `foo_hello` if it is present. The second
example would remove an additional, non-dynamic field.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-remove_tag"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-remove_tag"]
endif::[]
===== `remove_tag`
* Value type is <<array,array>>
* Value type is {logstash-ref}/configuration-file-structure.html#array[array]
* Default value is `[]`
If this filter is successful, remove arbitrary tags from the event.

View file

@ -1,53 +1,89 @@
==== Common Options
// Contributors: You must conditionally code all internal links and IDs in this
// file to make the common files work in both the LS Reference and the versioned
// plugin docs
The following configuration options are supported by all input plugins:
[cols="<,<,<",options="header",]
ifeval::["{versioned_docs}"!="true"]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-add_field>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-codec>> |<<codec,codec>>|No
| <<plugins-{type}s-{plugin}-enable_metric>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-id>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-tags>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-type>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-add_field>> |{logstash-ref}/configuration-file-structure.html#hash[hash]|No
| <<plugins-{type}s-{plugin}-codec>> |{logstash-ref}/configuration-file-structure.html#codec[codec]|No
| <<plugins-{type}s-{plugin}-enable_metric>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<plugins-{type}s-{plugin}-id>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
| <<plugins-{type}s-{plugin}-tags>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
| <<plugins-{type}s-{plugin}-type>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
|=======================================================================
endif::[]
ifeval::["{versioned_docs}"=="true"]
|=======================================================================
|Setting |Input type|Required
| <<{version}-plugins-{type}s-{plugin}-add_field>> |{logstash-ref}/configuration-file-structure.html#hash[hash]|No
| <<{version}-plugins-{type}s-{plugin}-codec>> |{logstash-ref}/configuration-file-structure.html#codec[codec]|No
| <<{version}-plugins-{type}s-{plugin}-enable_metric>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<{version}-plugins-{type}s-{plugin}-id>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
| <<{version}-plugins-{type}s-{plugin}-tags>> |{logstash-ref}/configuration-file-structure.html#array[array]|No
| <<{version}-plugins-{type}s-{plugin}-type>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
|=======================================================================
endif::[]
==== Details
&nbsp;
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-add_field"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-add_field"]
endif::[]
===== `add_field`
* Value type is <<hash,hash>>
* Value type is {logstash-ref}/configuration-file-structure.html#hash[hash]
* Default value is `{}`
Add a field to an event
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-codec"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-codec"]
endif::[]
===== `codec`
* Value type is <<codec,codec>>
* Value type is {logstash-ref}/configuration-file-structure.html#codec[codec]
* Default value is `"plain"`
The codec used for input data. Input codecs are a convenient method for decoding your data before it enters the input, without needing a separate filter in your Logstash pipeline.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-enable_metric"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-enable_metric"]
endif::[]
===== `enable_metric`
* Value type is <<boolean,boolean>>
* Value type is {logstash-ref}/configuration-file-structure.html#boolean[boolean]
* Default value is `true`
Disable or enable metric logging for this specific plugin instance
by default we record all the metrics we can, but you can disable metrics collection
for a specific plugin.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-id"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-id"]
endif::[]
===== `id`
* Value type is <<string,string>>
* Value type is {logstash-ref}/configuration-file-structure.html#string[string]
* There is no default value for this setting.
Add a unique `ID` to the plugin configuration. If no ID is specified, Logstash will generate one.
@ -64,20 +100,31 @@ input {
}
---------------------------------------------------------------------------------------------------
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-tags"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-tags"]
endif::[]
===== `tags`
* Value type is <<array,array>>
* Value type is {logstash-ref}/configuration-file-structure.html#array[array]
* There is no default value for this setting.
Add any number of arbitrary tags to your event.
This can help with processing later.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-type"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-type"]
endif::[]
===== `type`
* Value type is <<string,string>>
* Value type is {logstash-ref}/configuration-file-structure.html#string[string]
* There is no default value for this setting.
Add a `type` field to all events handled by this input.
@ -95,10 +142,18 @@ when sent to another Logstash server.
ifeval::["{type}"=="input" and "{plugin}"=="beats"]
ifeval::["{versioned_docs}"!="true"]
NOTE: The Beats shipper automatically sets the `type` field on the event.
You cannot override this setting in the Logstash config. If you specify
a setting for the <<plugins-inputs-beats-type,`type`>> config option in
Logstash, it is ignored.
endif::[]
ifeval::["{versioned_docs}"=="true"]
NOTE: The Beats shipper automatically sets the `type` field on the event.
You cannot override this setting in the Logstash config. If you specify
a setting for the <<{version}-plugins-inputs-beats-type,`type`>> config option in
Logstash, it is ignored.
endif::[]
endif::[]

View file

@ -1,37 +1,67 @@
==== Common Options
// Contributors: You must conditionally code all internal links and IDs in this
// file to make the common files work in both the LS Reference and the versioned
// plugin docs
The following configuration options are supported by all output plugins:
ifeval::["{versioned_docs}"!="true"]
[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-codec>> |<<codec,codec>>|No
| <<plugins-{type}s-{plugin}-enable_metric>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-id>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-codec>> |{logstash-ref}/configuration-file-structure.html#codec[codec]|No
| <<plugins-{type}s-{plugin}-enable_metric>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<plugins-{type}s-{plugin}-id>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
|=======================================================================
endif::[]
ifeval::["{versioned_docs}"=="true"]
[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<{version}-plugins-{type}s-{plugin}-codec>> |{logstash-ref}/configuration-file-structure.html#codec[codec]|No
| <<{version}-plugins-{type}s-{plugin}-enable_metric>> |{logstash-ref}/configuration-file-structure.html#boolean[boolean]|No
| <<{version}-plugins-{type}s-{plugin}-id>> |{logstash-ref}/configuration-file-structure.html#string[string]|No
|=======================================================================
endif::[]
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-codec"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-codec"]
endif::[]
===== `codec`
* Value type is <<codec,codec>>
* Value type is {logstash-ref}/configuration-file-structure.html#codec[codec]
* Default value is `"plain"`
The codec used for output data. Output codecs are a convenient method for encoding your data before it leaves the output without needing a separate filter in your Logstash pipeline.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-enable_metric"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-enable_metric"]
endif::[]
===== `enable_metric`
* Value type is <<boolean,boolean>>
* Value type is {logstash-ref}/configuration-file-structure.html#boolean[boolean]
* Default value is `true`
Disable or enable metric logging for this specific plugin instance.
By default we record all the metrics we can, but you can disable metrics collection
for a specific plugin.
ifeval::["{versioned_docs}"!="true"]
[id="plugins-{type}s-{plugin}-id"]
endif::[]
ifeval::["{versioned_docs}"=="true"]
[id="{version}-plugins-{type}s-{plugin}-id"]
endif::[]
===== `id`
* Value type is <<string,string>>
* Value type is {logstash-ref}/configuration-file-structure.html#string[string]
* There is no default value for this setting.
Add a unique `ID` to the plugin configuration. If no ID is specified, Logstash will generate one.

View file

@ -1,18 +1,41 @@
ifeval::["{versioned_docs}"!="true"]
++++
<titleabbrev>{plugin}</titleabbrev>
++++
endif::[]
ifeval::["{versioned_docs}"=="true"]
++++
<titleabbrev>{version}</titleabbrev>
++++
endif::[]
* Plugin version: {version}
* Released on: {release_date}
* {changelog_url}[Changelog]
ifeval::[{default_plugin} == 0]
ifeval::["{versioned_docs}"!="true"]
For other plugin versions, see the
{lsplugindocs}/{type}-{plugin}-index.html[Versioned {plugin} {type} plugin docs].
endif::[]
ifeval::["{versioned_docs}"=="true"]
For other versions, see the <<{type}-{plugin}-index,overview list>>.
To learn more about Logstash, see the {logstash-ref}/index.html[Logstash Reference].
endif::[]
ifeval::[("{default_plugin}"=="0") and ("{versioned_docs}"!="true")]
==== Installation
For plugins not bundled by default, it is easy to install by running +bin/logstash-plugin install logstash-{type}-{plugin}+. See <<working-with-plugins>> for more details.
For plugins not bundled by default, it is easy to install by running +bin/logstash-plugin install logstash-{type}-{plugin}+. See {logstash-ref}/working-with-plugins.html[Working with plugins] for more details.
endif::[]
==== Getting Help
For questions about the plugin, open a topic in the http://discuss.elastic.co[Discuss] forums. For bugs or feature requests, open an issue in https://github.com/logstash-plugins/logstash-{type}-{plugin}[Github].

View file

@ -0,0 +1,13 @@
[id="{type}-{plugin}-index"]
== Versioned {plugin} {type} plugin docs
++++
<titleabbrev>{plugin}</titleabbrev>
++++
This page lists all available versions of the documentation for this plugin.
To see which version of the plugin you have installed, run `bin/logstash-plugin
list --verbose`.
NOTE: Versioned plugin documentation is not available for plugins released prior
to Logstash 6.0.

View file

@ -11,6 +11,7 @@
release-state can be: released | prerelease | unreleased
//////////
:release-state: unreleased
:versioned_docs: false
:jdk: 1.8.0
:guide: https://www.elastic.co/guide/en/elasticsearch/guide/current/
@ -18,6 +19,7 @@ release-state can be: released | prerelease | unreleased
:filebeat: https://www.elastic.co/guide/en/beats/filebeat/{branch}/
:metricbeat: https://www.elastic.co/guide/en/beats/metricbeat/{branch}/
:lsissue: https://github.com/elastic/logstash/issues/
:lsplugindocs: https://www.elastic.co/guide/en/logstash/versioned-plugins/current
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]