aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/logger_formatter.xml
diff options
context:
space:
mode:
authorSiri Hansen <[email protected]>2018-06-08 14:18:36 +0200
committerSiri Hansen <[email protected]>2018-06-11 15:01:42 +0200
commitb9d2cb688e562d200663bdbedfa65adc5a29aeae (patch)
treefea56acc2fb931629b6a1ff80990b49eaabedbae /lib/kernel/doc/src/logger_formatter.xml
parent98371223a4056459957552f1243f499c4003628e (diff)
downloadotp-b9d2cb688e562d200663bdbedfa65adc5a29aeae.tar.gz
otp-b9d2cb688e562d200663bdbedfa65adc5a29aeae.tar.bz2
otp-b9d2cb688e562d200663bdbedfa65adc5a29aeae.zip
[logger] Update documentation
Diffstat (limited to 'lib/kernel/doc/src/logger_formatter.xml')
-rw-r--r--lib/kernel/doc/src/logger_formatter.xml148
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>