aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/logger.xml
diff options
context:
space:
mode:
authorSiri Hansen <[email protected]>2018-05-20 09:21:10 +0200
committerSiri Hansen <[email protected]>2018-05-23 11:11:35 +0200
commite484181ecc5c3e2928d10632138837eba3c3229e (patch)
tree93114d97f494bc628c4b041ff35d8246081cfe1f /lib/kernel/doc/src/logger.xml
parent6342a95bdaa8681bf24f2dc8fba261d21b75c9e4 (diff)
downloadotp-e484181ecc5c3e2928d10632138837eba3c3229e.tar.gz
otp-e484181ecc5c3e2928d10632138837eba3c3229e.tar.bz2
otp-e484181ecc5c3e2928d10632138837eba3c3229e.zip
Update Logger documentation
Diffstat (limited to 'lib/kernel/doc/src/logger.xml')
-rw-r--r--lib/kernel/doc/src/logger.xml140
1 files changed, 89 insertions, 51 deletions
diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 13d3e182d4..e2f3dd6e83 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -36,33 +36,6 @@
<modulesummary>API module for logging in Erlang/OTP.</modulesummary>
<description>
-
-<!-- From old error_logger ref man:
- Errors, warnings, and info events
- are sent to the error logger from the Erlang runtime system and
- the different Erlang/OTP applications. The events are, by default,
- logged to the terminal. Notice that an event from a process <c>P</c> is
- logged at the node of the group leader of <c>P</c>. This means
- that log output is directed to the node from which a process was
- created, which not necessarily is the same node as where it is
- executing.</p>
- <p>Initially, <c>error_logger</c> has only a primitive event
- handler, which buffers and prints the raw event messages. During
- system startup, the Kernel application replaces this with a
- <em>standard event handler</em>, by default one that writes
- nicely formatted output to the terminal. Kernel can also be
- configured so that events are logged to a file instead, or not logged at all,
- see <seealso marker="kernel_app"><c>kernel(6)</c></seealso>.</p>
- <p>Also the SASL application, if started, adds its own event
- handler, which by default writes supervisor, crash, and progress
- reports to the terminal. See
- <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso>.</p>
- <p>It is recommended that user-defined applications report
- errors through the error logger to get uniform reports.
--->
-
-
-
<p>
This module is the main API for logging in Erlang/OTP. It
contains functions that allow applications to use a single log
@@ -217,6 +190,15 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
<c>erlang:system_time(microsecond)</c></seealso>.</p>
</desc>
</datatype>
+ <datatype>
+ <name name="formatter_config"/>
+ <desc>
+ <p>Configuration data for the
+ formatter. See <seealso marker="logger_formatter">
+ <c>logger_formatter(3)</c></seealso>
+ for an example of a formatter implementation.</p>
+ </desc>
+ </datatype>
</datatypes>
<section>
@@ -486,8 +468,8 @@ Current logger configuration:
handler part.</p>
</item>
</taglist>
- <p>See section <seealso marker="logger_chapter#Filter">
- Filter</seealso> in the User's Guide for more information
+ <p>See section <seealso marker="logger_chapter#filters">
+ Filters</seealso> in the User's Guide for more information
about filters.</p>
<p>Some built-in filters exist. These are defined
in <seealso marker="logger_filters"><c>logger_filters</c></seealso>.</p>
@@ -528,7 +510,7 @@ Current logger configuration:
</item>
</taglist>
<p>See
- section <seealso marker="logger_chapter#Filter">Filter</seealso>
+ section <seealso marker="logger_chapter#filters">Filters</seealso>
in the User's Guide for more information about filters.</p>
<p>Some built-in filters exist. These are defined in
<seealso marker="logger_filters"><c>logger_filters</c></seealso>.</p>
@@ -891,14 +873,15 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
</funcs>
<section>
- <title>Callback Functions</title>
+ <marker id="handler_callback_functions"/>
+ <title>Handler Callback Functions</title>
<p>The following functions are to be exported from a handler
callback module.</p>
</section>
<funcs>
<func>
- <name>Module:adding_handler(HandlerId,Config1) -> {ok,Config2} | {error,Reason}</name>
+ <name>HModule:adding_handler(HandlerId,Config1) -> {ok,Config2} | {error,Reason}</name>
<fsummary>An instance of this handler is about to be added.</fsummary>
<type>
<v>HandlerId =
@@ -911,7 +894,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
<p>This callback function is optional.</p>
<p>The function is called when an new handler is about to be
added, and the purpose is to verify the configuration and
- initiate all resourced needed by the handler.</p>
+ initiate all resources needed by the handler.</p>
<p>If everything succeeds, the callback function can add
possible default values or internal state values to the
configuration, and return the adjusted map
@@ -922,24 +905,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
</func>
<func>
- <name>Module:removing_handler(HandlerId,Config) -> ok</name>
- <fsummary>The given handler is about to be removed.</fsummary>
- <type>
- <v>HandlerId =
- <seealso marker="#type-handler_id">handler_id()</seealso></v>
- <v>Config =
- <seealso marker="#type-config">config()</seealso></v>
- </type>
- <desc>
- <p>This callback function is optional.</p>
- <p>The function is called when a handler is about to be
- removed, and the purpose is to release all resources used by
- the handler. The return value is ignored by Logger.</p>
- </desc>
- </func>
-
- <func>
- <name>Module:changing_config(HandlerId,Config1,Config2) -> {ok,Config3} | {error,Reason}</name>
+ <name>HModule:changing_config(HandlerId,Config1,Config2) -> {ok,Config3} | {error,Reason}</name>
<fsummary>The configuration for this handler is about to change.</fsummary>
<type>
<v>HandlerId =
@@ -961,6 +927,78 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
return <c>{error,Reason}</c>.</p>
</desc>
</func>
+
+ <func>
+ <name>HModule:log(Log,Config) -> void()</name>
+ <fsummary>Log the given log event.</fsummary>
+ <type>
+ <v>Log =
+ <seealso marker="#type-log">log()</seealso></v>
+ <v>Config =
+ <seealso marker="#type-config">config()</seealso></v>
+ </type>
+ <desc>
+ <p>This callback function is mandatory.</p>
+ <p>The function is called when all global filters and all
+ handler filters for the handler in question have passed for
+ the given log event.</p>
+ <p>The handler must log the event.</p>
+ <p>The return value from this function is ignored by
+ Logger.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>HModule:removing_handler(HandlerId,Config) -> ok</name>
+ <fsummary>The given handler is about to be removed.</fsummary>
+ <type>
+ <v>HandlerId =
+ <seealso marker="#type-handler_id">handler_id()</seealso></v>
+ <v>Config =
+ <seealso marker="#type-config">config()</seealso></v>
+ </type>
+ <desc>
+ <p>This callback function is optional.</p>
+ <p>The function is called when a handler is about to be
+ removed, and the purpose is to release all resources used by
+ the handler. The return value is ignored by Logger.</p>
+ </desc>
+ </func>
+
+ </funcs>
+
+ <section>
+ <marker id="formatter_callback_functions"/>
+ <title>Formatter Callback Functions</title>
+ <p>The following functions are to be exported from a formatter
+ callback module.</p>
+ </section>
+
+ <funcs>
+ <func>
+ <name>FModule:format(Log,FConfig) -> FormattedLogEntry</name>
+ <fsummary>Format the given log event.</fsummary>
+ <type>
+ <v>Log =
+ <seealso marker="#type-log">log()</seealso></v>
+ <v>FConfig =
+ <seealso marker="#type-formatter_config">formatter_config()</seealso></v>
+ <v>FormattedLogEntry =
+ <seealso marker="unicode#type-chardata">unicode:chardata()</seealso></v>
+ </type>
+ <desc>
+ <p>This callback function is mandatory.</p>
+ <p>The function can be called by a log handler to convert a
+ log event term to a printable string. The returned value
+ can, for example, be printed as a log entry to the console
+ or a file using <seealso marker="stdlib:io#put_chars-1">
+ <c>io:put_chars/1,2</c></seealso>.</p>
+ <p>See <seealso marker="logger_formatter">
+ <c>logger_formatter(3)</c></seealso>
+ for an example implementation. <c>logger_formatter</c> is the
+ default formatter used by Logger.</p>
+ </desc>
+ </func>
</funcs>
</erlref>