From 0d3b793ac551f9c69f9e1c0c5a76186386f3cd04 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Wed, 2 May 2018 11:50:49 +0200 Subject: Update logger documentation --- lib/kernel/doc/src/logger_formatter.xml | 217 +++++++++++++++++++------------- 1 file changed, 129 insertions(+), 88 deletions(-) (limited to 'lib/kernel/doc/src/logger_formatter.xml') diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml index 6a17e3641f..a0940100ee 100644 --- a/lib/kernel/doc/src/logger_formatter.xml +++ b/lib/kernel/doc/src/logger_formatter.xml @@ -37,116 +37,157 @@

Default formatter for the Logger application.

- - - - - - - - - - - - - - Formats the given message. - -

Formats the given message.

-

The template is a list of atoms, tuples and strings. Atoms - can be level or msg, which are placeholders - for the severity level and the log message, - repectively. Tuples are interpreted as placeholders for - metadata. Each element in the tuple must be an atom which - matches a key in the nested metadata map, e.g. the - tuple {key1,key2} will be replaced by the value of - the key2 field in this nested map (the value vill be - converted to a string):

- - -#{key1=>#{key2=>my_value, - ...}, - ...} - - -

Strings are printed literally.

- -

depth is a positive integer representing the maximum - depth to which terms shall be printed by this - formatter. Format strings passed to this formatter are - rewritten. The format controls ~p and ~w are replaced with - ~P and ~W, respectively, and the value is used as the depth - parameter. For details, see - io:format/2,3 - in STDLIB.

- -

chars_limit is a positive integer representing the - value of the option with the same name to be used when calling - io:format/3. This - value limits the total number of characters printed bu the - formatter. Notes that this is a soft limit. For a hard - truncation limit, see option max_size.

- -

max_size is a positive integer representing the - maximum size a string returned from this formatter can - have. If the formatted string is longer, after possibly - being limited by depth and/or chars_limit, it - will be truncated.

- -

utc is a boolean. If set to true, all dates are - displayed in Universal Coordinated Time. Default - is false.

-

report_cb must be a function with arity 1, - returning {Format,Args}. This function will replace - any report_cb found in metadata.

- -

If single_line=true, all newlines in the message are - replaced with ", ", and whitespaces following directly - after newlines are removed. Note that newlines added by the - formatter template are not replaced.

+ -

If legacy_header=true a header field is added to +

+ Configuration +

The following configuration parameters can be set + for logger_formatter:

+ + single_line = boolean() + +

If set to true, all newlines in the message are + replaced with ", ", and whitespaces following + directly after newlines are removed. Note that newlines + added by the formatter template are not replaced.

+

Default is true.

+ + legacy_header = boolen() + +

If set to true a header field is added to logger_formatter's part of Metadata. The value of this field is a string similar to the header created by the old error_logger event handlers. It can be included in the log event by adding the - tuple {logger_formatter,header} to the template.

- -

The default template when legacy_header=true is

- - [{logger_formatter,header},"\n",msg,"\n"] + tuple {logger_formatter,header} to the + template. See Default + Templates for more information

+

Default is false.

+ + report_cb = fun((logger:report()) -> {io:format(),[term()]}) + +

A function with arity 1, + returning {Format,Args}. This function will replace + any report_cb found in metadata.

+ + depth = pos_integer() | unlimited + +

A positive integer representing the maximum depth to + which terms shall be printed by this formatter. Format + strings passed to this formatter are rewritten. The format + controls ~p and ~w are replaced with ~P and ~W, + respectively, and the value is used as the depth + parameter. For details, see + io:format/2,3 + in STDLIB.

+

Default is unlimited.

+ + chars_limit = pos_integer() | unlimited + +

A positive integer representing the value of the option + with the same name to be used when calling + io_lib:format/3. + This value limits the total number of characters printed + for each log event. Note that this is a soft limit. For a + hard truncation limit, see option max_size.

+

Default is unlimited.

+ + max_size = pos_integer() | unlimited + +

A positive integer representing the absolute maximum size + a string returned from this formatter can have. If the + formatted string is longer, after possibly being limited + by depth and/or chars_limit, it will be + truncated.

+

Default is unlimited.

+ + template = template() + +

The template is a list of atoms, tuples and strings. The + atoms level or msg, are treated as + placeholders for the severity level and the log message, + repectively. Other atoms or tuples are interpreted as + placeholders for metadata, where atoms are expected to + match top level keys, and tuples represent paths to sub + keys in a nested map. For example the + tuple {key1,key2} will be replaced by the value of + the key2 field in the nested map below. The + atom key1 on its own would be replaced by the + complete value of the key1 field. The values are + converted to strings.

-

which will cause log entries like this:

+ +#{key1=>#{key2=>my_value, + ...} + ...} - =ERROR REPORT==== 29-Dec-2017::13:30:51.245123 === +

Strings are printed literally.

+

The default template differs depending on the values + of legacy_header + and single_line. See Default + Templates for more information

+ + utc = boolean() + +

If set to true, all dates are displayed in Universal + Coordinated Time. Default is false.

+ + +
+ +
+ + Default templates +

The default template when legacy_header=true is

+ + [{logger_formatter,header},"\n",msg,"\n"] + +

which will cause log entries like this:

+ + =ERROR REPORT==== 29-Dec-2017::13:30:51.245123 === process: <0.74.0> exit_reason: "Something went wrong" -

Note that all eight levels might occur here, not - only ERROR, WARNING or INFO. And also - that micro seconds are added at the end of the - timestamp.

+

Note that all eight levels might occur here, not + only ERROR, WARNING or INFO. And also that + micro seconds are added at the end of the timestamp.

-

The default template when single_line=true is

+

The default template when single_line=true is

- [time," ",level,": ",msg,"\n"] + [time," ",level,": ",msg,"\n"] -

which will cause log entries like this:

+

which will cause log entries like this:

- 2017-12-29 13:31:49.640317 error: process: <0.74.0>, exit_reason: "Something went wrong" + 2017-12-29 13:31:49.640317 error: process: <0.74.0>, exit_reason: "Something went wrong" -

The default template when both legacy_header and - single_line are set to false is:

+

The default template when both legacy_header and + single_line are set to false is:

- [time," ",level,":\n",msg,"\n"] + [time," ",level,":\n",msg,"\n"] -

which will cause log entries like this:

+

which will cause log entries like this:

- 2017-12-29 13:32:25.191925 error: + 2017-12-29 13:32:25.191925 error: process: <0.74.0> exit_reason: "Something went wrong" +
+ + + + + + + + + + + + Formats the given message. + +

This the callback function to be called from handlers. It + formats the given messages.

 -- cgit v1.2.3