[docs] Fixed doc suggestions

elastic · Apr 17, 2024 · 4d93746 · 4d93746
1 parent c34d2a9
commit 4d93746
Show file tree

Hide file tree

Showing 3 changed files with 46 additions and 0 deletions.
diff --git a/docs/static/running-logstash-command-line.asciidoc b/docs/static/running-logstash-command-line.asciidoc
@@ -230,6 +230,9 @@ With this command, Logstash concatenates three config files, `/tmp/one`, `/tmp/t
  Specify if Logstash should write its own logs in JSON form (one event per line) or in plain text
  (using Ruby's Object#inspect). The default is "plain".
 
+*`--log.format.json.fix_duplicate_message_fields ENABLED`*::
+ Avoid `message` field collision using JSON log format. Possible values are `false` (default) and `true`.
+
 *`--path.settings SETTINGS_DIR`*::
  Set the directory containing the `logstash.yml` <<logstash-settings-file,settings file>> as well
  as the log4j logging configuration. This can also be set through the LS_SETTINGS_DIR environment variable.

diff --git a/docs/static/settings-file.asciidoc b/docs/static/settings-file.asciidoc
@@ -336,6 +336,10 @@ The log level. Valid options are:
 | The log format. Set to `json` to log in JSON format, or `plain` to use `Object#.inspect`.
 | `plain`
 
+| `log.format.json.fix_duplicate_message_fields`
+| When the log format is `json` avoid collision of field names in log lines.
+| `false`
+
 | `path.logs`
 | The directory where Logstash will write its log to.
 | `LOGSTASH_HOME/logs`

diff --git a/docs/static/troubleshoot/ts-logstash.asciidoc b/docs/static/troubleshoot/ts-logstash.asciidoc
@@ -213,6 +213,26 @@ Reset the logging level to `info`.
 When format of log is `json` and certain log events (for example errors from JSON codec plugin)
 contains two instances of the `message` field.
 
+Without setting this flag, json log could contain objects like:
+
+[source,json]
+-----
+{
+ "level":"WARN",
+ "loggerName":"logstash.codecs.jsonlines",
+ "timeMillis":1712937761955,
+ "thread":"[main]<stdin",
+ "logEvent":{
+ "message":"JSON parse error, original data now in message field",
+ "message":"Unexpected close marker '}': expected ']' (for Array starting at [Source: (String)\"{\"name\": [}\"; line: 1, column: 10])\n at [Source: (String)\"{\"name\": [}\"; line: 1, column: 12]",
+ "exception":"LogStash::Json::ParserError",
+ "data":"{\"name\": [}"
+ }
+}
+-----
+
+Please note the duplication of `message` field, that despite is a formally valid json, it's not well accepted by many parsers.
+
 *Solution*
 In `config/logstash.yml` enable the strict json flag:
 
@@ -226,4 +246,23 @@ or pass the command line switch
 [source]
 -----
 bin/logstash --log.format.json.fix_duplicate_message_fields true
+-----
+
+With the `log.format.json.fix_duplicate_message_fields` enabled the duplication of `message` field is removed,
+adding a `_1` suffix:
+
+[source,json]
+-----
+{
+ "level":"WARN",
+ "loggerName":"logstash.codecs.jsonlines",
+ "timeMillis":1712937629789,
+ "thread":"[main]<stdin",
+ "logEvent":{
+ "message":"JSON parse error, original data now in message field",
+ "message_1":"Unexpected close marker '}': expected ']' (for Array starting at [Source: (String)\"{\"name\": [}\"; line: 1, column: 10])\n at [Source: (String)\"{\"name\": [}\"; line: 1, column: 12]",
+ "exception":"LogStash::Json::ParserError",
+ "data":"{\"name\": [}"
+ }
+}
 -----