diff options
Diffstat (limited to '')
-rw-r--r-- | source/configuration/modules/mmjsonparse.rst | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/source/configuration/modules/mmjsonparse.rst b/source/configuration/modules/mmjsonparse.rst new file mode 100644 index 0000000..3d47c4f --- /dev/null +++ b/source/configuration/modules/mmjsonparse.rst @@ -0,0 +1,147 @@ +*********************************************************** +JSON/CEE Structured Content Extraction Module (mmjsonparse) +*********************************************************** + +=========================== =========================================================================== +**Module Name:** **mmjsonparse** +**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com> +**Available since:** 6.6.0 +=========================== =========================================================================== + + +Purpose +======= + +This module provides support for parsing structured log messages that +follow the CEE/lumberjack spec. The so-called "CEE cookie" is checked +and, if present, the JSON-encoded structured message content is parsed. +The properties are then available as original message properties. + +As a convenience, mmjsonparse will produce a valid CEE/lumberjack log +message if passed a message without the CEE cookie. A JSON structure +will be created and the "msg" field will be the only field and it will +contain the message. Note that in this case, mmjsonparse will +nonetheless return that the JSON parsing has failed. + +The "CEE cookie" is the character squence "@cee:" which must prepend the +actual JSON. Note that the JSON must be valid and MUST NOT be followed +by any non-JSON message. If either of these conditions is not true, +mmjsonparse will **not** parse the associated JSON. This is based on the +cookie definition used in CEE/project lumberjack and is meant to aid +against an erroneous detection of a message as being CEE where it is +not. + +This also means that mmjsonparse currently is NOT a generic JSON parser +that picks up JSON from wherever it may occur in the message. This is +intentional, but future versions may support config parameters to relax +the format requirements. + + +Notable Features +================ + +- :ref:`mmjsonparse-parsing-result` + + +Configuration Parameters +======================== + +.. note:: + + Parameter names are case-insensitive. + + +Action Parameters +----------------- + +cookie +^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "@cee:", "no", "none" + +Permits to set the cookie that must be present in front of the +JSON part of the message. + +Most importantly, this can be set to the empty string ("") in order +to not require any cookie. In this case, leading spaces are permitted +in front of the JSON. No non-whitespace characters are permitted +after the JSON. If such is required, mmnormalize must be used. + + +useRawMsg +^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "none" + +Specifies if the raw message should be used for normalization (on) +or just the MSG part of the message (off). + + +container +^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "$!", "no", "none" + +Specifies the JSON container (path) under which parsed elements should be +placed. By default, all parsed properties are merged into root of +message properties. You can place them under a subtree, instead. You +can place them in local variables, also, by setting path="$.". + + +.. _mmjsonparse-parsing-result: + +Check parsing result +==================== + +You can check whether rsyslogd was able to successfully parse the +message by reading the $parsesuccess variable : + +.. code-block:: none + + action(type="mmjsonparse") + if $parsesuccess == "OK" then { + action(type="omfile" File="/tmp/output") + } + else if $parsesuccess == "FAIL" then { + action(type="omfile" File="/tmp/parsing_failure") + } + + +Examples +======== + +Apply default normalization +--------------------------- + +This activates the module and applies normalization to all messages. + +.. code-block:: none + + module(load="mmjsonparse") + action(type="mmjsonparse") + + +Permit parsing messages without cookie +-------------------------------------- + +To permit parsing messages without cookie, use this action statement + +.. code-block:: none + + action(type="mmjsonparse" cookie="") + |