Backport to 6.4: Multiple doc changes (elastic#7696 elastic#7889 elas…

…tic#7903 elastic#7937 elastic#7949) (elastic#7996) * Add document for beat export dashboard (elastic#7696) * Add safeguard related statements for max_backoff setting (elastic#7889) * Add docs about append_fields (elastic#7903) * Fix processor autodiscovery docs for Filebeat (elastic#7937) * Minor fixes to attributes in module docs (elastic#7949)
leweafan · Aug 17, 2018 · 1af8f17 · 1af8f17
1 parent 27d0265
commit 1af8f17
Show file tree

Hide file tree

Showing 14 changed files with 134 additions and 22 deletions.
diff --git a/auditbeat/auditbeat.reference.yml b/auditbeat/auditbeat.reference.yml
@@ -935,6 +935,13 @@ output.elasticsearch:
 # Path to fields.yml file to generate the template
 #setup.template.fields: "${path.config}/fields.yml"
 
+# A list of fields to be added to the template and Kibana index pattern. Also
+# specify setup.template.overwrite: true to overwrite the existing template.
+# This setting is experimental.
+#setup.template.append_fields:
+#- name: field_name
+#  type: field_type
+
 # Enable json template loading. If this is enabled, the fields.yml is ignored.
 #setup.template.json.enabled: false
 

diff --git a/filebeat/docs/autodiscover-hints.asciidoc b/filebeat/docs/autodiscover-hints.asciidoc
@@ -73,7 +73,7 @@ of supported processors.
 In order to provide ordering of the processor definition, numbers can be provided. If not, the hints builder will do
 arbitrary ordering:
 
-["source","yaml",subs="attributes"]
+["source","yaml"]
 -------------------------------------------------------------------------------------
 co.elastic.logs/processors.1.dissect.tokenizer: "%{key1} %{key2}"
 co.elastic.logs/processors.dissect.tokenizer: "%{key2} %{key1}"

diff --git a/filebeat/docs/inputs/input-common-file-options.asciidoc b/filebeat/docs/inputs/input-common-file-options.asciidoc
@@ -348,9 +348,10 @@ specifying 10s for `max_backoff` means that, at the worst, a new line could be
 added to the log file if {beatname_uc} has backed off multiple times. The
 default is 10s.
 
-Requirement: max_backoff should always be set to `max_backoff <=
-scan_frequency`. In case `max_backoff` should be bigger, it is recommended to
-close the file handler instead let the {beatname_uc} pick up the file again.
+Requirement: Set `max_backoff` to be greater than or equal to `backoff` and
+less than or equal to `scan_frequency` (`backoff <= max_backoff <= scan_frequency`).
+If `max_backoff` needs to be higher, it is recommended to close the file handler
+instead and let {beatname_uc} pick up the file again.
 
 [float]
 ===== `backoff_factor`

diff --git a/filebeat/docs/modules/kibana.asciidoc b/filebeat/docs/modules/kibana.asciidoc
@@ -23,16 +23,18 @@ include::../include/running-modules.asciidoc[]
 
 include::../include/configuring-intro.asciidoc[]
 
-//set the fileset name used in the included example
+//set the fileset name used in the included file
 :fileset_ex: log
 
 include::../include/config-option-intro.asciidoc[]
 
 [float]
-==== `{fileset}` log fileset settings
+==== `log` fileset settings
 
 include::../include/var-paths.asciidoc[]
 
+:fileset_ex!:
+
 
 [float]
 === Fields

diff --git a/filebeat/filebeat.reference.yml b/filebeat/filebeat.reference.yml
@@ -1595,6 +1595,13 @@ output.elasticsearch:
 # Path to fields.yml file to generate the template
 #setup.template.fields: "${path.config}/fields.yml"
 
+# A list of fields to be added to the template and Kibana index pattern. Also
+# specify setup.template.overwrite: true to overwrite the existing template.
+# This setting is experimental.
+#setup.template.append_fields:
+#- name: field_name
+#  type: field_type
+
 # Enable json template loading. If this is enabled, the fields.yml is ignored.
 #setup.template.json.enabled: false
 

diff --git a/filebeat/module/kibana/_meta/docs.asciidoc b/filebeat/module/kibana/_meta/docs.asciidoc
@@ -18,12 +18,14 @@ include::../include/running-modules.asciidoc[]
 
 include::../include/configuring-intro.asciidoc[]
 
-//set the fileset name used in the included example
+//set the fileset name used in the included file
 :fileset_ex: log
 
 include::../include/config-option-intro.asciidoc[]
 
 [float]
-==== `{fileset}` log fileset settings
+==== `log` fileset settings
 
 include::../include/var-paths.asciidoc[]
+
+:fileset_ex!:
diff --git a/filebeat/scripts/module/_meta/docs.asciidoc b/filebeat/scripts/module/_meta/docs.asciidoc
@@ -37,3 +37,7 @@ the relevant file. For example:
 ==== `{fileset}` log fileset settings
 
 include::../include/var-paths.asciidoc[]
+
+:fileset_ex!:
+
+:modulename!:
diff --git a/heartbeat/heartbeat.reference.yml b/heartbeat/heartbeat.reference.yml
@@ -1042,6 +1042,13 @@ output.elasticsearch:
 # Path to fields.yml file to generate the template
 #setup.template.fields: "${path.config}/fields.yml"
 
+# A list of fields to be added to the template and Kibana index pattern. Also
+# specify setup.template.overwrite: true to overwrite the existing template.
+# This setting is experimental.
+#setup.template.append_fields:
+#- name: field_name
+#  type: field_type
+
 # Enable json template loading. If this is enabled, the fields.yml is ignored.
 #setup.template.json.enabled: false
 

diff --git a/libbeat/_meta/config.reference.yml b/libbeat/_meta/config.reference.yml
@@ -828,6 +828,13 @@ output.elasticsearch:
 # Path to fields.yml file to generate the template
 #setup.template.fields: "${path.config}/fields.yml"
 
+# A list of fields to be added to the template and Kibana index pattern. Also
+# specify setup.template.overwrite: true to overwrite the existing template.
+# This setting is experimental.
+#setup.template.append_fields:
+#- name: field_name
+#  type: field_type
+
 # Enable json template loading. If this is enabled, the fields.yml is ignored.
 #setup.template.json.enabled: false
 

diff --git a/libbeat/docs/command-reference.asciidoc b/libbeat/docs/command-reference.asciidoc
@@ -14,7 +14,7 @@
 
 :global-flags: Also see <<global-flags,Global flags>>.
 
-:export-command-short-desc: Exports the configuration or index template to stdout
+:export-command-short-desc: Exports the configuration, index template or a dashboard to stdout
 :help-command-short-desc: Shows help for any command
 :keystore-command-short-desc: Manages the <<keystore,secrets keystore>>
 :modules-command-short-desc: Manages configured modules
@@ -77,7 +77,7 @@ endif::[]
 
 [options="header"]
 |=======================
-|Commands | 
+|Commands |
 |<<export-command,`export`>> |{export-command-short-desc}.
 |<<help-command,`help`>> |{help-command-short-desc}.
 |<<keystore-command,`keystore`>> |{keystore-command-short-desc}.
@@ -96,8 +96,8 @@ Also see <<global-flags,Global flags>>.
 ==== `export` command
 
 {export-command-short-desc}. You can use this
-command to quickly view your configuration or the contents of the index
-template.
+command to quickly view your configuration, see the contents of the index
+template or export a dashboard from Kibana.
 
 *SYNOPSIS*
 
@@ -113,6 +113,30 @@ template.
 Exports the current configuration to stdout. If you use the `-c` flag, this
 command exports the configuration that's defined in the specified file.
 
+
+
+*`dashboard`*::
+Exporting a dashboard allows to store a dashboard on disk in a
+module and load it automatically. The following command can be used:
++
+["source","shell",subs="attributes"]
+----
+{beatname_lc} export dashboard --id="dashboard-id" > dashboard.json
+----
++
+The `dashboard-id` can be found in the Kibana URL. By default `export dashboard`
+will write the dashboard to stdout. Above it's written into `dashboard.json` so
+it can later imported again. The file contains the dashboard with all
+visualizations and searches. The index pattern is removed as it is
+expected to be loaded separately for {beatname_uc}.
++
+The generated `dashboard.json` file can be copied into the `kibana/6/dashboard`
+directory of {beatname_lc} and next time +{beatname_lc} setup dashboards+ is
+run the dashboard will be imported.
++
+In case Kibana is not running on `localhost:5061` the {beatname_uc}
+configuration under `setup.kibana` must be adjusted.
+
 [[template-subcommand]]
 *`template`*::
 Exports the index template to stdout. You can specify the `--es.version` and
@@ -176,7 +200,7 @@ Specifies the name of the command to show help for.
 [[keystore-command]]
 ==== `keystore` command
 
-{keystore-command-short-desc}. 
+{keystore-command-short-desc}.
 
 *SYNOPSIS*
 
@@ -690,4 +714,3 @@ the _Beats Platform Reference_ for more information.
 
 *`-v, --v`*::
 Logs INFO-level messages.
-
diff --git a/libbeat/docs/template-config.asciidoc b/libbeat/docs/template-config.asciidoc
@@ -82,21 +82,52 @@ setup.template.overwrite: false
 setup.template.settings:
   _source.enabled: false
 ----------------------------------------------------------------------
-ifeval::["{beatname_lc}"!="apm-server"]
-*`setup.template.append_fields`*:: A list of of fields to be added to the template and Kibana index pattern. experimental[]
-
-NOTE: With append_fields only new fields can be added an no existing one overwritten or changed. This is especially useful if data is collected through the http/json metricset where the data structure is not known in advance. Changing the config of append_fields means the template has to be overwritten and only applies to new indices. If there are 2 Beats with different append_fields configs the last one writing the template will win. Any changes will also have an affect on the Kibana Index pattern.
-
-*`setup.template.json.enabled`*:: Set to true to load a json based template file. Specify the path to your Elasticsearch
-index template file and set the name of the template. experimental[]
 
+ifeval::["{beatname_lc}"!="apm-server"]
+*`setup.template.append_fields`* experimental[]:: A list of fields to be added
+to the template and {kib} index pattern. This setting adds new fields. It does
+not overwrite or change existing fields. 
++
+This setting is useful when your data contains fields that {beatname_uc} doesn't
+know about in advance. 
+ifeval::["{beatname_lc}"=="metricbeat"]
+For example, you might want to append fields to the template when you're using
+a metricset, such as the <<metricbeat-metricset-http-json>>, and the full data
+structure is not known in advance. 
+endif::[]
++
+If `append_fields` is specified along with `overwrite: true`, {beatname_uc}
+overwrites the existing template and applies the new template when creating new
+indices. Existing indices are not affected. If you're running multiple
+instances of {beatname_uc} with different `append_fields` settings, the last one
+writing the template takes precedence.
++
+Any changes to this setting also affect the {kib} index pattern.
++
+Example config:
++
+[source,yaml]
+----
+setup.template.overwrite: true
+setup.template.append_fields:
+- name: test.name
+  type: keyword
+- name: test.hostname
+  type: long
+----
+
+*`setup.template.json.enabled`*:: Set to `true` to load a
+JSON-based template file. Specify the path to your {es} index template file and
+set the name of the template. 
++
 ["source","yaml",subs="attributes"]
 ----------------------------------------------------------------------
 setup.template.json.enabled: true
 setup.template.json.path: "template.json"
 setup.template.json.name: "template-name
 ----------------------------------------------------------------------
 
-NOTE: If the JSON template is used, the fields.yml is skipped for the template generation.
+NOTE: If the JSON template is used, the `fields.yml` is skipped for the template
+generation.
 
 endif::[]
diff --git a/metricbeat/metricbeat.reference.yml b/metricbeat/metricbeat.reference.yml
@@ -1502,6 +1502,13 @@ output.elasticsearch:
 # Path to fields.yml file to generate the template
 #setup.template.fields: "${path.config}/fields.yml"
 
+# A list of fields to be added to the template and Kibana index pattern. Also
+# specify setup.template.overwrite: true to overwrite the existing template.
+# This setting is experimental.
+#setup.template.append_fields:
+#- name: field_name
+#  type: field_type
+
 # Enable json template loading. If this is enabled, the fields.yml is ignored.
 #setup.template.json.enabled: false
 

diff --git a/packetbeat/packetbeat.reference.yml b/packetbeat/packetbeat.reference.yml
@@ -1305,6 +1305,13 @@ output.elasticsearch:
 # Path to fields.yml file to generate the template
 #setup.template.fields: "${path.config}/fields.yml"
 
+# A list of fields to be added to the template and Kibana index pattern. Also
+# specify setup.template.overwrite: true to overwrite the existing template.
+# This setting is experimental.
+#setup.template.append_fields:
+#- name: field_name
+#  type: field_type
+
 # Enable json template loading. If this is enabled, the fields.yml is ignored.
 #setup.template.json.enabled: false
 

diff --git a/winlogbeat/winlogbeat.reference.yml b/winlogbeat/winlogbeat.reference.yml
@@ -857,6 +857,13 @@ output.elasticsearch:
 # Path to fields.yml file to generate the template
 #setup.template.fields: "${path.config}/fields.yml"
 
+# A list of fields to be added to the template and Kibana index pattern. Also
+# specify setup.template.overwrite: true to overwrite the existing template.
+# This setting is experimental.
+#setup.template.append_fields:
+#- name: field_name
+#  type: field_type
+
 # Enable json template loading. If this is enabled, the fields.yml is ignored.
 #setup.template.json.enabled: false