Backport doc changes into 5.0 (#2847)

* Clarify instructions for running configtest * Add to FAQ the solution for having nested JSON objects under Discovery (#2726) * docs: Fix broken Kibana doc link in faq (#2837) The Kibana docs overhaul for 5.0+ changed the link to the index pattern field refresh instructions. * Use variable for filepath plus some light edits (#2838)
elastic · Oct 25, 2016 · fa08f52 · fa08f52
1 parent 41d228e
commit fa08f52
Show file tree

Hide file tree

Showing 14 changed files with 79 additions and 11 deletions.
diff --git a/filebeat/docs/getting-started.asciidoc b/filebeat/docs/getting-started.asciidoc
@@ -139,14 +139,18 @@ output.elasticsearch:
 +
 If you are sending output to Logstash, see <<config-filebeat-logstash>> instead.
 
-TIP: To test your configuration file, run Filebeat in the foreground with the following options specified:
-+./filebeat -configtest -e+.
+TIP: To test your configuration file, change to the directory where the Filebeat
+binary is installed, and run Filebeat in the foreground with the following
+options specified: +./filebeat -configtest -e+. Make sure your config files are
+in the path expected by Filebeat (see <<directory-layout>>). If you
+installed from DEB or RPM packages, run +./filebeat.sh -configtest -e+.
 
 See <<filebeat-configuration-details>> for more details about each configuration option.
 
 [[config-filebeat-logstash]]
 === Step 3: Configuring Filebeat to Use Logstash
 
+:allplatforms:
 include::../../libbeat/docs/shared-logstash-config.asciidoc[]
 
 [[filebeat-template]]

diff --git a/filebeat/docs/index.asciidoc b/filebeat/docs/index.asciidoc
@@ -38,6 +38,7 @@ include::../../libbeat/docs/shared-env-vars.asciidoc[]
 
 include::./multiple-prospectors.asciidoc[]
 
+:allplatforms:
 include::../../libbeat/docs/yaml.asciidoc[]
 
 include::../../libbeat/docs/regexp.asciidoc[]

diff --git a/libbeat/docs/config-file-format.asciidoc b/libbeat/docs/config-file-format.asciidoc
@@ -355,8 +355,9 @@ simply uncomment the line and change the values.
 [float]
 ==== Test Your Config File
 
-You can test your configuration file to verify that the structure is valid. Simply run
-your in the foreground with the `-configtest` flag specified. For example:
+You can test your configuration file to verify that the structure is valid.
+Simply change to the directory where the binary is installed, and run
+your Beat in the foreground with the `-configtest` flag specified. For example:
 
 ["source","yaml",subs="attributes,callouts"]
 ----------------------------------------------------------------------

diff --git a/libbeat/docs/faq-refresh-index.asciidoc b/libbeat/docs/faq-refresh-index.asciidoc
@@ -0,0 +1,23 @@
+[float]
+[[refresh-index-pattern]]
+=== Fields show up as nested JSON in Kibana?
+
+When {beatname_uc} exports a field of type dictionary, and the keys are not known in advance, the Discovery page in Kibana will display the field as a nested JSON object:
+
+[source,shell]
+----------------------------------------------------------------------
+http.response.headers = {
+        "content-length": 12,
+        "content-type": "application/json"
+}
+----------------------------------------------------------------------
+To fix this you need to {kibanadoc}/index-patterns.html#reload-fields[reload the index pattern] in Kibana under the Management->Index Patterns, and the index pattern will be
+updated with a field for each key available in the dictionary:
+
+[source,shell]
+----------------------------------------------------------------------
+http.response.headers.content-length = 12
+http.response.headers.content-type = "application/json"
+----------------------------------------------------------------------
+
+
diff --git a/libbeat/docs/shared-logstash-config.asciidoc b/libbeat/docs/shared-logstash-config.asciidoc
@@ -29,8 +29,23 @@ Beats connections.
 For this configuration, you must <<load-template-manually,load the index template into Elasticsearch manually>>
 because the options for auto loading the template are only available for the Elasticsearch output.
 
-TIP: To test your configuration file, run {beatname_uc} in the foreground with the following options specified:
-+./{beatname_lc} -configtest -e+.
+ifdef::allplatforms[]
+
+TIP: To test your configuration file, change to the directory where the {beatname_uc} 
+binary is installed, and run {beatname_uc} in the foreground with the following
+options specified: +./{beatname_lc} -configtest -e+. Make sure your config files are
+in the path expected by {beatname_uc} (see <<directory-layout>>). If you
+installed from DEB or RPM packages, run +./{beatname_lc}.sh -configtest -e+.
+
+endif::allplatforms[]
+
+ifdef::win[]
+
+TIP: To test your configuration file, change to the directory where the {beatname_uc} 
+binary is installed, and run {beatname_uc} in the foreground with the following
+options specified: +.\winlogbeat.exe -c .\winlogbeat.yml -configtest -e+.
+
+endif::win[]
 
 To use this configuration, you must also
 {libbeat}/logstash-installation.html#logstash-setup[set up Logstash] to receive events

diff --git a/libbeat/docs/yaml.asciidoc b/libbeat/docs/yaml.asciidoc
@@ -31,14 +31,28 @@ simply uncomment the line and change the setting.
 [float]
 === Test Your Config File
 
-You can test your configuration file to verify that the structure is valid. Simply run
+You can test your configuration file to verify that the structure is valid.
+Simply change to the directory where the binary is installed, and run
 {beatname_uc} in the foreground with the `-configtest` flag specified. For example: 
 
-["source","yaml",subs="attributes,callouts"]
+ifdef::allplatforms[]
+
+["source","shell",subs="attributes"]
 ----------------------------------------------------------------------
 {beatname_lc} -c {beatname_lc}.yml -configtest
 ----------------------------------------------------------------------
 
+endif::allplatforms[]
+
+ifdef::win[]
+
+["source","shell",subs="attributes"]
+----------------------------------------------------------------------
+.\winlogbeat.exe -c .\winlogbeat.yml -configtest -e
+----------------------------------------------------------------------
+
+endif::win[]
+
 You'll see a message if {beatname_uc} finds an error in the file.
 
 [float]

diff --git a/metricbeat/docs/configuring-logstash.asciidoc b/metricbeat/docs/configuring-logstash.asciidoc
@@ -1,4 +1,5 @@
 [[config-metricbeat-logstash]]
 == Configuring Metricbeat to Use Logstash
 
+:allplatforms:
 include::../../libbeat/docs/shared-logstash-config.asciidoc[]
diff --git a/metricbeat/docs/index.asciidoc b/metricbeat/docs/index.asciidoc
@@ -35,6 +35,7 @@ include::./configuring-logstash.asciidoc[]
 
 include::../../libbeat/docs/shared-env-vars.asciidoc[]
 
+:allplatforms:
 include::../../libbeat/docs/yaml.asciidoc[]
 
 include::../../libbeat/docs/regexp.asciidoc[]

diff --git a/packetbeat/docs/configuring-logstash.asciidoc b/packetbeat/docs/configuring-logstash.asciidoc
@@ -1,4 +1,5 @@
 [[config-packetbeat-logstash]]
 == Configuring Packetbeat to Use Logstash
 
+:allplatforms:
 include::../../libbeat/docs/shared-logstash-config.asciidoc[]
diff --git a/packetbeat/docs/faq.asciidoc b/packetbeat/docs/faq.asciidoc
@@ -71,4 +71,5 @@ option. However, keep in mind that very large timeout values can increase memory
 response messages are not sent. 
 
 include::../../libbeat/docs/faq-limit-bandwidth.asciidoc[]
-include::../../libbeat/docs/shared-faq.asciidoc[]
+include::../../libbeat/docs/shared-faq.asciidoc[]
+include::../../libbeat/docs/faq-refresh-index.asciidoc[]
diff --git a/packetbeat/docs/gettingstarted.asciidoc b/packetbeat/docs/gettingstarted.asciidoc
@@ -187,8 +187,11 @@ output.elasticsearch:
 +
 If you are sending output to Logstash, see <<config-packetbeat-logstash>> instead.
 
-TIP: To test your configuration file, run Packetbeat in the foreground with the following options specified:
-+sudo ./packetbeat -configtest -e+.
+TIP: To test your configuration file, change to the directory where the Packetbeat
+binary is installed, and run Packetbeat in the foreground with the following
+options specified: +sudo ./packetbeat -configtest -e+. Make sure your config files are
+in the path expected by Packetbeat (see <<directory-layout>>). If you
+installed from DEB or RPM packages, run +sudo ./packetbeat.sh -configtest -e+.
 
 [[packetbeat-template]]
 === Step 3: Loading the Index Template in Elasticsearch

diff --git a/packetbeat/docs/index.asciidoc b/packetbeat/docs/index.asciidoc
@@ -45,6 +45,7 @@ include::./thrift.asciidoc[]
 
 include::./maintaining-topology.asciidoc[]
 
+:allplatforms:
 include::../../libbeat/docs/yaml.asciidoc[]
 
 include::./fields.asciidoc[]

diff --git a/winlogbeat/docs/getting-started.asciidoc b/winlogbeat/docs/getting-started.asciidoc
@@ -121,6 +121,7 @@ PS C:\Program Files\Winlogbeat> .\winlogbeat.exe -c .\winlogbeat.yml -configtest
 [[config-winlogbeat-logstash]]
 === Step 3: Configuring Winlogbeat to Use Logstash
 
+:win:
 include::../../libbeat/docs/shared-logstash-config.asciidoc[]
 
 [[winlogbeat-template]]

diff --git a/winlogbeat/docs/index.asciidoc b/winlogbeat/docs/index.asciidoc
@@ -32,6 +32,7 @@ include::../../libbeat/docs/shared-config-ingest.asciidoc[]
 
 include::../../libbeat/docs/shared-env-vars.asciidoc[]
 
+:win:
 include::../../libbeat/docs/yaml.asciidoc[]
 
 include::./fields.asciidoc[]
-Original file line number
+Diff line change
@@ Expand Up / @@ -32,6 +32,7 @@ include::../../libbeat/docs/shared-config-ingest.asciidoc[] @@
     include::../../libbeat/docs/shared-env-vars.asciidoc[]
+    :win:
     include::../../libbeat/docs/yaml.asciidoc[]
     include::./fields.asciidoc[]
@@ Expand Down @@