diff options
Diffstat (limited to 'lib/kernel/doc/src/logger_formatter.xml')
| -rw-r--r-- | lib/kernel/doc/src/logger_formatter.xml | 148 |
1 files changed, 92 insertions, 56 deletions
diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml index 02f89b26be..59f5dbe367 100644 --- a/lib/kernel/doc/src/logger_formatter.xml +++ b/lib/kernel/doc/src/logger_formatter.xml @@ -36,12 +36,15 @@ <modulesummary>Default formatter for Logger.</modulesummary> <description> - <p>Each log handler has a configured formatter specified as a + <p>Each Logger handler has a configured formatter specified as a module and a configuration term. The purpose of the formatter is to translate the log events to a final printable string (<seealso marker="stdlib:unicode#type-chardata"><c>unicode:chardata()</c> - </seealso>) which can be written to the output - device of the handler.</p> + </seealso>) which can be written to the output device of the + handler. See + sections <seealso marker="logger_chapter#handlers">Handlers</seealso> + and <seealso marker="logger_chapter#formatters">Formatters</seealso> + in the Kernel User's Guide for more information.</p> <p><c>logger_formatter</c> is the default formatter used by Logger.</p> </description> @@ -55,7 +58,8 @@ <seealso marker="stdlib:maps">map</seealso>, and the following keys can be set as configuration parameters:</p> <taglist> - <tag><c>chars_limit = pos_integer() | unlimited</c></tag> + <tag><marker id="chars_limit"/> + <c>chars_limit = integer() > 0 | unlimited</c></tag> <item> <p>A positive integer representing the value of the option with the same name to be used when calling @@ -65,14 +69,8 @@ for each log event. Notice that this is a soft limit. For a hard truncation limit, see option <c>max_size</c>.</p> <p>Defaults to <c>unlimited</c>.</p> - <note> - <p><c>chars_limit</c> has no effect on log messages on - string form. These are expected to be short, but can - still be truncated by the <c>max_size</c> - parameter.</p> - </note> </item> - <tag><marker id="depth"/><c>depth = pos_integer() | unlimited</c></tag> + <tag><marker id="depth"/><c>depth = integer() > 0 | unlimited</c></tag> <item> <p>A positive integer representing the maximum depth to which terms shall be printed by this formatter. Format @@ -83,26 +81,23 @@ <seealso marker="stdlib:io#format-2">io:format/2,3</seealso> in STDLIB.</p> <p>Defaults to <c>unlimited</c>.</p> - <note> - <p><c>depth</c> has no effect on log messages on string - form. These are expected to be short, but can still be - truncated by the <c>max_size</c> parameter.</p> - </note> </item> <tag><c>legacy_header = boolean()</c></tag> <item> <p>If set to <c>true</c> a header field is added to logger_formatter's part of <c>Metadata</c>. The value of this field is a string similar to the header created by - the old <c>error_logger</c> event handlers. It can be - included in the log event by adding the - tuple <c>{logger_formatter,header}</c> to the + the + old <seealso marker="error_logger"><c>error_logger</c></seealso> + event handlers. It can be included in the log event by + adding the list <c>[logger_formatter,header]</c> to the template. See the description of the <seealso marker="#type-template"><c>template()</c></seealso> type for more information.</p> <p>Defaults to <c>false</c>.</p> </item> - <tag><c>max_size = pos_integer() | unlimited</c></tag> + <tag><marker id="max_size"/> + <c>max_size = integer() > 0 | unlimited</c></tag> <item> <p>A positive integer representing the absolute maximum size a string returned from this formatter can have. If the @@ -110,12 +105,12 @@ by <c>chars_limit</c> or <c>depth</c>, it is truncated.</p> <p>Defaults to <c>unlimited</c>.</p> </item> - <tag><c>report_cb = fun((</c><seealso marker="logger#type-report"><c>logger:report()</c></seealso><c>) -> {</c><seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso><c>,[term()]})</c></tag> + <tag><c>report_cb = fun((</c><seealso marker="logger#type-report"><c>logger:report()</c></seealso><c>) -> {</c><seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso><c>, [term()]})</c></tag> <item> <p>A report callback is used by the formatter to transform log messages on report form to a format string and arguments. The report callback can be specified in the - metadata for the log event. If no report callback exist + metadata for the log event. If no report callback exists in metadata, <c>logger_formatter</c> will use <seealso marker="logger#format_report-1"> <c>logger:format_report/1</c></seealso> as default @@ -131,12 +126,14 @@ <tag><c>single_line = boolean()</c></tag> <item> <p>If set to <c>true</c>, all newlines in the message are - replaced with <c>", "</c>, and whitespaces following - directly after newlines are removed. Note that newlines + replaced with <c>", "</c>, and white spaces following + directly after newlines are removed. Notice that newlines added by the <c>template</c> parameter are not replaced.</p> <p>Defaults to <c>true</c>.</p> </item> - <tag><c>template = </c><seealso marker="#type-template"><c>template()</c></seealso></tag> + <tag><marker id="template"/> + <c>template = </c><seealso marker="#type-template"><c>template()</c> + </seealso></tag> <item> <p>The template describes how the formatted string is composed by combining different data values from the log @@ -184,31 +181,42 @@ </desc> </datatype> <datatype> + <name name="metakey"/> + <desc> + <p></p> + </desc> + </datatype> + <datatype> <name name="template"/> <desc> - <p>The template is a list of atoms, tuples and strings. The + <p>The template is a list of atoms, atom lists, tuples and strings. The atoms <c>level</c> or <c>msg</c>, are treated as placeholders for the severity level and the log message, - respectively. Other atoms or tuples are interpreted as + respectively. Other atoms or atom lists are interpreted as placeholders for metadata, where atoms are expected to match - top level keys, and tuples represent paths to sub keys when + top level keys, and atom lists represent paths to sub keys when the metadata is a nested map. For example the - tuple <c>{key1,key2}</c> is replaced by the value of + list <c>[key1,key2]</c> is replaced by the value of the <c>key2</c> field in the nested map below. The atom <c>key1</c> on its own is replaced by the complete value of the <c>key1</c> field. The values are converted to strings.</p> -<code> -#{key1=>#{key2=>my_value, - ...} + <code> +#{key1 => #{key2 => my_value, + ...} ...}</code> - <p>Strings in the template are printed literally.</p> - <p>The default template differs depending on the values - of <c>legacy_header</c> - and <c>single_line</c>:</p> + <p>Tuples in the template express if-exist tests for metadata + keys. For example, the following tuple says that + if <c>key1</c> exists in the metadata map, + print <c>"key1=Value"</c>, where <c>Value</c> is the value + that <c>key1</c> is associated with in the metadata map. If + <c>key1</c> does not exist, print nothing.</p> + <code> +{key1, ["key1=",key1], []}</code> + <p>Strings in the template are printed literally.</p> <p>The default value for the <c>template</c> configuration parameter depends on the value of the <c>single_line</c> and <c>legacy_header</c> configuration parameters as @@ -216,13 +224,13 @@ <p>The log event used in the examples is:</p> <code> -?LOG_ERROR("name: ~p~nexit_reason: ~p",[my_name,"It crashed"])</code> +?LOG_ERROR("name: ~p~nexit_reason: ~p", [my_name, "It crashed"])</code> <taglist> - <tag><c>legacy_header=true, single_line=false</c></tag> + <tag><c>legacy_header = true, single_line = false</c></tag> <item> <p>Default - template: <c>[{logger_formatter,header},"\n",msg,"\n"]</c></p> + template: <c>[[logger_formatter,header],"\n",msg,"\n"]</c></p> <p>Example log entry:</p> <code type="none"> @@ -231,15 +239,16 @@ name: my_name exit_reason: "It crashed"</code> <p>Notice that all eight levels can occur in the heading, - not only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c> as the - old <c>error_logger</c> produced. And microseconds are - added at the end of the timestamp.</p> + not only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c> as + <seealso marker="error_logger"><c>error_logger</c></seealso> + produces. And microseconds are added at the end of the + timestamp.</p> </item> - <tag><c>legacy_header=true, single_line=true</c></tag> + <tag><c>legacy_header = true, single_line = true</c></tag> <item> <p>Default - template: <c>[{logger_formatter,header},"\n",msg,"\n"]</c></p> + template: <c>[[logger_formatter,header],"\n",msg,"\n"]</c></p> <p>Notice that the template is here the same as for <c>single_line=false</c>, but the resulting log entry @@ -250,7 +259,7 @@ exit_reason: "It crashed"</code> name: my_name, exit_reason: "It crashed"</code> </item> - <tag><c>legacy_header=false, single_line=true</c></tag> + <tag><c>legacy_header = false, single_line = true</c></tag> <item> <p>Default template: <c>[time," ",level,": ",msg,"\n"]</c></p> @@ -259,7 +268,7 @@ name: my_name, exit_reason: "It crashed"</code> 2018-05-17T18:31:31.152864+02:00 error: name: my_name, exit_reason: "It crashed"</code> </item> - <tag><c>legacy_header=false, single_line=false</c></tag> + <tag><c>legacy_header = false, single_line = false</c></tag> <item> <p>Default template: <c>[time," ",level,":\n",msg,"\n"]</c></p> @@ -279,10 +288,21 @@ exit_reason: "It crashed"</code> <name name="check_config" arity="1"/> <fsummary>Validates the given formatter configuration.</fsummary> <desc> - <p>This callback function is called by Logger when the - formatter configuration for a handler is set or modified. It + <p>The function is called by Logger when the formatter + configuration for a handler is set or modified. It returns <c>ok</c> if the configuration is valid, and <c>{error,term()}</c> if it is faulty.</p> + <p>The following Logger API functions can trigger this callback:</p> + <list> + <item><seealso marker="logger#add_handler-3"> + <c>logger:add_handler/3</c></seealso></item> + <item><seealso marker="logger#set_handler_config-2"> + <c>logger:set_handler_config/2,3</c></seealso></item> + <item><seealso marker="logger#update_handler_config-2"> + <c>logger:updata_handler_config/2</c></seealso></item> + <item><seealso marker="logger#update_formatter_config-2"> + <c>logger:update_formatter_config/2</c></seealso></item> + </list> </desc> </func> <func> @@ -293,22 +313,38 @@ exit_reason: "It crashed"</code> handlers. The log event is processed as follows:</p> <list> <item>If the message is on report form, it is converted to - <c>{Format,Args}</c> by calling the report - callback.</item> - <item>The size is limited according to the values of - configuration parameters <c>chars_limit</c> - and <c>depth</c>. Notice that this does not apply to - messages on string form.</item> + <c>{Format,Args}</c> by calling the report callback. See + section <seealso marker="logger_chapter#log_message">Log + Message</seealso> in the Kernel User's Guide for more + information about report callbacks and valid forms of log + messages.</item> + <item>The message size is limited according to the values of + configuration parameters <seealso marker="#chars_limit"> + <c>chars_limit</c></seealso> + and <seealso marker="#depth"><c>depth</c></seealso>.</item> <item>The full log entry is composed according to - the <c>template</c>.</item> + the <seealso marker="#template"><c>template</c></seealso>.</item> <item>If the final string is too long, it is truncated according to the value of configuration - parameter <c>max_size</c>.</item> + parameter <seealso marker="#max_size"><c>max_size</c></seealso>.</item> </list> </desc> </func> </funcs> + <section> + <title>See Also</title> + <p> + <seealso marker="stdlib:calendar"><c>calendar(3)</c></seealso>, + <seealso marker="error_logger"><c>error_logger(3)</c></seealso>, + <seealso marker="stdlib:io"><c>io(3)</c></seealso>, + <seealso marker="stdlib:io_lib"><c>io_lib(3)</c></seealso>, + <seealso marker="logger"><c>logger(3)</c></seealso>, + <seealso marker="stdlib:maps"><c>maps(3)</c></seealso>, + <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso>, + <seealso marker="stdlib:unicode"><c>unicode(3)</c></seealso> + </p> + </section> </erlref> |