aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src
diff options
context:
space:
mode:
authorSiri Hansen <[email protected]>2018-05-02 11:50:49 +0200
committerSiri Hansen <[email protected]>2018-05-03 11:52:37 +0200
commit0d3b793ac551f9c69f9e1c0c5a76186386f3cd04 (patch)
tree0996d5b5f6c4e5f6b6ccb57063d6ea50bfadd0f3 /lib/kernel/doc/src
parent2ea3d7b972141ac73a1dd7f0ac1a3ccbde342f6d (diff)
downloadotp-0d3b793ac551f9c69f9e1c0c5a76186386f3cd04.tar.gz
otp-0d3b793ac551f9c69f9e1c0c5a76186386f3cd04.tar.bz2
otp-0d3b793ac551f9c69f9e1c0c5a76186386f3cd04.zip
Update logger documentation
Diffstat (limited to 'lib/kernel/doc/src')
-rw-r--r--lib/kernel/doc/src/kernel_app.xml30
-rw-r--r--lib/kernel/doc/src/logger.xml6
-rw-r--r--lib/kernel/doc/src/logger_chapter.xml5
-rw-r--r--lib/kernel/doc/src/logger_formatter.xml217
4 files changed, 146 insertions, 112 deletions
diff --git a/lib/kernel/doc/src/kernel_app.xml b/lib/kernel/doc/src/kernel_app.xml
index 554d675383..f96d946a5d 100644
--- a/lib/kernel/doc/src/kernel_app.xml
+++ b/lib/kernel/doc/src/kernel_app.xml
@@ -226,7 +226,7 @@
<p>This configuration parameter is used both for the global
logger level, and for the standard handler started by
the Kernel application (see <c>logger_dest</c> variable above).</p>
- <p>The default value is <c>info</c></p>
+ <p>The default value is <c>info</c>.</p>
</item>
<tag><marker id="disk_log_vars"/>
<c>logger_disk_log_type = halt | wrap</c></tag>
@@ -251,14 +251,14 @@ logger_disk_log_maxbytes = 1048576</code>
<item>
<p>If this parameter is set to true, then the logger handler
started by kernel will not log any progress-, crash-, or
- supervisor reports. If the SASL application is starated,
+ supervisor reports. If the SASL application is started,
these log events will be sent to a second handler instance
- named sasl_h, according to values of the SASL environment
- variables <c>sasl_error_logger</c>
+ named <c>sasl_h</c>, according to values of the SASL
+ environment variables <c>sasl_error_logger</c>
and <c>sasl_errlog_type</c>, see
<seealso marker="sasl:sasl_app#configuration">SASL(6)
</seealso></p>
- <p>The default value is <c>false</c></p>
+ <p>The default value is <c>false</c>.</p>
<p>See chapter <seealso marker="logger_chapter#compatibility">Backwards
compatibility with error_logger</seealso> for more
information about handling of the so called SASL reports.</p>
@@ -271,7 +271,7 @@ logger_disk_log_maxbytes = 1048576</code>
reports from <c>supervisor</c>
and <c>application_controller</c> shall be logged or
not.</p>
- <p>If <c>logger_sasl_compatible = false</c>,
+ <p>If <c>logger_sasl_compatible = true</c>,
then <c>logger_log_progress</c> is ignored.</p>
</item>
<tag><marker id="logger_format_depth"/>
@@ -280,14 +280,6 @@ logger_disk_log_maxbytes = 1048576</code>
<p>Can be used to limit the size of the
formatted output from the logger handlers.</p>
- <note><p>This configuration parameter was introduced in OTP 18.1
- and is experimental. Based on user feedback, it
- can be changed or improved in future releases, for example,
- to gain better control over how to limit the size of the
- formatted output. We have no plans to remove this
- new feature entirely, unless it turns out to be
- useless.</p></note>
-
<p><c>Depth</c> is a positive integer representing the maximum
depth to which terms are printed by the logger
handlers included in OTP. This
@@ -312,11 +304,11 @@ logger_disk_log_maxbytes = 1048576</code>
</item>
<tag><c>logger_max_size = integer() | unlimited</c></tag>
<item>
- <p>This parameter specifies the maximum size (bytes) each
- log event can have when printed by the standard logger
- handler. If the resulting string after formatting an event
- is bigger than this, it will be truncated before printed
- to the handler's destination.</p>
+ <p>This parameter specifies a hard maximum size limit (number
+ of characters) each log event can have when printed by the
+ default logger formatter. If the resulting string after
+ formatting an event is bigger than this, it will be
+ truncated before printed to the handler's destination.</p>
</item>
<tag><c>logger_utc = boolean()</c></tag>
<item>
diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 66e6e5c689..ded9c1fb37 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -131,8 +131,8 @@
<code>
#{mfa=>{?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY},
- file=>?FILE,
- line=>?LINE}
+ file=>?FILE,
+ line=>?LINE}
</code>
<p>The call is wrapped in a case statement and will be evaluated
@@ -297,7 +297,7 @@
<tag>print</tag>
<item>Pretty print all the current logger configuration to
standard out. Example:
- <code><![CDATA[1> logger:i().
+ <code><![CDATA[1> logger:i(print).
Current logger configuration:
Level: info
FilterDefault: log
diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 88dcfbe8d9..78d6f46c95 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -488,8 +488,9 @@ error_logger:add_report_handler/1,2.
level => debug}
2> <input>logger:add_handler(debug_handler,logger_std_h,Config).</input>
ok</pre>
- <p>By default, the handler receives all events, so we need to add a filter
- to stop all non-debug events:</p>
+ <p>By default, the handler receives all events
+ (<c>filter_defalt=log</c>), so we need to add a filter to stop
+ all non-debug events:</p>
<pre>
3> <input>Fun = fun(#{level:=debug}=Log,_) -> Log; (_,_) -> stop end.</input>
#Fun&lt;erl_eval.12.98642416>
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 @@
<description>
<p>Default formatter for the Logger application.</p>
- </description>
-
- <datatypes>
- <datatype>
- <name name="template"/>
- <desc>
- </desc>
- </datatype>
- </datatypes>
-
- <funcs>
- <func>
- <name name="format" arity="2"/>
- <fsummary>Formats the given message.</fsummary>
- <desc>
- <p>Formats the given message.</p>
- <p>The template is a list of atoms, tuples and strings. Atoms
- can be <c>level</c> or <c>msg</c>, 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 <c>{key1,key2}</c> will be replaced by the value of
- the key2 field in this nested map (the value vill be
- converted to a string):</p>
-
-<code>
-#{key1=>#{key2=>my_value,
- ...},
- ...}</code>
-
-
- <p> Strings are printed literally.</p>
-
- <p><c>depth</c> 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
- <seealso marker="stdlib:io#format-2">io:format/2,3</seealso>
- in STDLIB.</p>
-
- <p><c>chars_limit</c> is a positive integer representing the
- value of the option with the same name to be used when calling
- <seealso marker="stdlib:io#format-3">io:format/3</seealso>. 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 <c>max_size</c>.</p>
-
- <p><c>max_size</c> 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 <c>depth</c> and/or <c>chars_limit</c>, it
- will be truncated.</p>
-
- <p><c>utc</c> is a boolean. If set to true, all dates are
- displayed in Universal Coordinated Time. Default
- is <c>false</c>.</p>
- <p><c>report_cb</c> must be a function with arity 1,
- returning <c>{Format,Args}</c>. This function will replace
- any <c>report_cb</c> found in metadata.</p>
-
- <p>If <c>single_line=true</c>, all newlines in the message are
- replaced with <c>", "</c>, and whitespaces following directly
- after newlines are removed. Note that newlines added by the
- formatter template are not replaced.</p>
+ </description>
- <p>If <c>legacy_header=true</c> a header field is added to
+ <section>
+ <title>Configuration</title>
+ <p>The following configuration parameters can be set
+ for <c>logger_formatter</c>:</p>
+ <taglist>
+ <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
+ added by the formatter template are not replaced.</p>
+ <p>Default is <c>true</c>.</p>
+ </item>
+ <tag><c>legacy_header = boolen()</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 template.</p>
-
- <p>The default template when <c>legacy_header=true</c> is</p>
-
- <code>[{logger_formatter,header},"\n",msg,"\n"]</code>
+ tuple <c>{logger_formatter,header}</c> to the
+ template. See <seealso marker="#default_templates">Default
+ Templates</seealso> for more information</p>
+ <p>Default is <c>false</c>.</p>
+ </item>
+ <tag><c>report_cb = fun((logger:report()) -> {io:format(),[term()]})</c></tag>
+ <item>
+ <p>A function with arity 1,
+ returning <c>{Format,Args}</c>. This function will replace
+ any <c>report_cb</c> found in metadata.</p>
+ </item>
+ <tag><c>depth = pos_integer() | unlimited</c></tag>
+ <item>
+ <p>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
+ <seealso marker="stdlib:io#format-2">io:format/2,3</seealso>
+ in STDLIB.</p>
+ <p>Default is <c>unlimited</c>.</p>
+ </item>
+ <tag><c>chars_limit = pos_integer() | unlimited</c></tag>
+ <item>
+ <p>A positive integer representing the value of the option
+ with the same name to be used when calling
+ <seealso marker="stdlib:io_lib#format-3">io_lib:format/3</seealso>.
+ 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 <c>max_size</c>.</p>
+ <p>Default is <c>unlimited</c>.</p>
+ </item>
+ <tag><c>max_size = pos_integer() | unlimited</c></tag>
+ <item>
+ <p>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 <c>depth</c> and/or <c>chars_limit</c>, it will be
+ truncated.</p>
+ <p>Default is <c>unlimited</c>.</p>
+ </item>
+ <tag><c>template = </c><seealso marker="#type-template"><c>template()</c></seealso></tag>
+ <item>
+ <p>The template is a list of atoms, tuples and strings. The
+ atoms <c>level</c> or <c>msg</c>, 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 <c>{key1,key2}</c> will be replaced by the value of
+ the <c>key2</c> field in the nested map below. The
+ atom <c>key1</c> on its own would be replaced by the
+ complete value of the <c>key1</c> field. The values are
+ converted to strings.</p>
- <p>which will cause log entries like this:</p>
+<code>
+#{key1=>#{key2=>my_value,
+ ...}
+ ...}</code>
- <code>=ERROR REPORT==== 29-Dec-2017::13:30:51.245123 ===
+ <p>Strings are printed literally.</p>
+ <p>The default template differs depending on the values
+ of <c>legacy_header</c>
+ and <c>single_line</c>. See <seealso marker="#default_templates">Default
+ Templates</seealso> for more information</p>
+ </item>
+ <tag><c>utc = boolean()</c></tag>
+ <item>
+ <p>If set to <c>true</c>, all dates are displayed in Universal
+ Coordinated Time. Default is <c>false</c>.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <marker id="default_templates"/>
+ <title>Default templates</title>
+ <p>The default template when <c>legacy_header=true</c> is</p>
+
+ <code>[{logger_formatter,header},"\n",msg,"\n"]</code>
+
+ <p>which will cause log entries like this:</p>
+
+ <code>=ERROR REPORT==== 29-Dec-2017::13:30:51.245123 ===
process: &lt;0.74.0&gt;
exit_reason: "Something went wrong"</code>
- <p>Note that all eight levels might occur here, not
- only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c>. And also
- that micro seconds are added at the end of the
- timestamp.</p>
+ <p>Note that all eight levels might occur here, not
+ only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c>. And also that
+ micro seconds are added at the end of the timestamp.</p>
- <p>The default template when <c>single_line=true</c> is</p>
+ <p>The default template when <c>single_line=true</c> is</p>
- <code>[time," ",level,": ",msg,"\n"]</code>
+ <code>[time," ",level,": ",msg,"\n"]</code>
- <p>which will cause log entries like this:</p>
+ <p>which will cause log entries like this:</p>
- <code>2017-12-29 13:31:49.640317 error: process: &lt;0.74.0&gt;, exit_reason: "Something went wrong"</code>
+ <code>2017-12-29 13:31:49.640317 error: process: &lt;0.74.0&gt;, exit_reason: "Something went wrong"</code>
- <p>The default template when both <c>legacy_header</c> and
- <c>single_line</c> are set to false is:</p>
+ <p>The default template when both <c>legacy_header</c> and
+ <c>single_line</c> are set to false is:</p>
- <code>[time," ",level,":\n",msg,"\n"]</code>
+ <code>[time," ",level,":\n",msg,"\n"]</code>
- <p>which will cause log entries like this:</p>
+ <p>which will cause log entries like this:</p>
- <code>2017-12-29 13:32:25.191925 error:
+ <code>2017-12-29 13:32:25.191925 error:
process: &lt;0.74.0&gt;
exit_reason: "Something went wrong"</code>
+ </section>
+
+ <datatypes>
+ <datatype>
+ <name name="template"/>
+ <desc>
+ </desc>
+ </datatype>
+ </datatypes>
+ <funcs>
+ <func>
+ <name name="format" arity="2"/>
+ <fsummary>Formats the given message.</fsummary>
+ <desc>
+ <p>This the callback function to be called from handlers. It
+ formats the given messages.</p>
</desc>
</func>