DOC: config: document logformat item naming and typecasting features

The ability to give a name to a logformat_node (known as logformat item in
the documentation) implemented in 2ed6068f2a ("MINOR: log: custom name for
logformat node") wasn't documented.

The same goes for the ability to force the logformat_node's output type to
a specific type implemented in 1448478d62 ("MINOR: log: explicit
typecasting for logformat nodes")

Let's quickly describe such new usages at the start of the custom log
format section.
This commit is contained in:
Aurelien DARRAGON 2024-05-27 12:02:27 +02:00
parent 435a9da267
commit 141bc5ba0d
1 changed files with 11 additions and 0 deletions

View File

@ -25925,6 +25925,17 @@ Special alias "%o" may be used to propagate its flags to all other
logformat items on the same format string. This is particularly handy with
quoted ("Q") and escaped ("E") string formats.
Items can optionally be named using ('()'). The name must be provided right
after '%' (before arguments). It will automatically be used as key name when
encoding flag such as "json" or "cbor" is set. When no encoding flag is
specified (default), item name will be ignored. It is also possible to force
the item's output to a given type by appending ':type' after the name, like
this: %(itemname:itemtype)aliasname or %(itemname:itemtype)[expr] where
itemtype may be 'str', 'sint' or 'bool'. Specifying the type is only relevant
when an encoding method is used. Also, it is supported to provide an empty name
to force the output type on an anonymous item: %(:itemtype), ie: when encoding
is not set globally, see flags definitions below for more information.
Due to the original goal of custom log formats to be used for logging only,
there is a special case made of non-printable and unsafe characters (those
outside ASCII codes 32 to 126 plus a few other ones) depending where they are