aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/logger.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.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.xml')
-rw-r--r--lib/kernel/doc/src/logger.xml883
1 files changed, 472 insertions, 411 deletions
diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 911eb158da..7f35a5d752 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -33,73 +33,150 @@
<file>logger.xml</file>
</header>
<module>logger</module>
- <modulesummary>API module for logging in Erlang/OTP.</modulesummary>
+ <modulesummary>API module for Logger, the standard logging facility
+ in Erlang/OTP.</modulesummary>
<description>
- <p>
- This module is the main API for logging in Erlang/OTP. It
- contains functions that allow applications to use a single log
- API and the system to manage those log events independently. Use
- the <seealso marker="#emergency-1">API functions</seealso> or the log
- <seealso marker="#macros">macros</seealso> to log events. For instance,
- to log a new error event:</p>
- <code>
-?LOG_ERROR("error happened because: ~p",[Reason]). %% With macro
-logger:error("error happened because: ~p",[Reason]). %% Without macro
- </code>
- <p>This log event is then sent to the configured log handlers which
- by default means that it is be printed to the console. If you want
- your systems logs to be printed to a file instead of the console you
- must configure the default handler to do so. The simplest way is
- to include the following in your <seealso marker="config"><c>sys.config</c></seealso>.</p>
+ <p>This module implements the main API for logging in
+ Erlang/OTP. To create a log event, use the
+ <seealso marker="#logging_API">API functions</seealso> or the
+ log
+ <seealso marker="#macros">macros</seealso>, for example:</p>
+ <code>
+?LOG_ERROR("error happened because: ~p", [Reason]). % With macro
+logger:error("error happened because: ~p", [Reason]). % Without macro
+ </code>
+ <p>To configure the Logger backend,
+ use <seealso marker="kernel_app#logger">Kernel configuration
+ parameters</seealso>
+ or <seealso marker="#configuration_API">configuration
+ functions</seealso> in the Logger API.</p>
+
+ <p>By default, the Kernel application installs one log handler at
+ system start. This handler is named <c>default</c>. It receives
+ and processes standard log events produced by the Erlang runtime
+ system, standard behaviours and different Erlang/OTP
+ applications. The log events are by default printed to the
+ terminal.</p>
+ <p>If you want your systems logs to be printed to a file instead,
+ you must configure the default handler to do so. The simplest
+ way is to include the following in
+ your <seealso marker="config"><c>sys.config</c></seealso>:</p>
<code>
[{kernel,
[{logger,
- [{handler,default,logger_std_h,
- #{logger_std_h=>#{type=>{file,"path/to/file.log"}}}}]}]}].
+ [{handler, default, logger_std_h,
+ #{config => #{type => {file, "path/to/file.log"}}}}]}]}].
</code>
<p>
For more information about:
</p>
<list type="bulleted">
- <item>how to use the API,
- see <seealso marker="logger_chapter">the User's Guide</seealso>.</item>
- <item>how to configure Logger,
- see the <seealso marker="logger_chapter#configuration">Configuration</seealso>
+ <item>the Logger facility in general, see
+ the <seealso marker="logger_chapter">User's
+ Guide</seealso>.</item>
+ <item>how to configure Logger, see
+ the <seealso marker="logger_chapter#configuration">Configuration</seealso>
section in the User's Guide.</item>
- <item>the convinience macros in logger.hrl,
- see <seealso marker="#macros">the macro section</seealso>.</item>
- <item>what the builtin formatter can do,
- see <seealso marker="logger_formatter">logger_formatter</seealso>.</item>
- <item>what the builtin handlers can do,
+ <item>the built-in handlers,
see <seealso marker="logger_std_h">logger_std_h</seealso> and
<seealso marker="logger_disk_log_h">logger_disk_log_h</seealso>.</item>
- <item>what builtin filters are available,
+ <item>the built-in formatter,
+ see <seealso marker="logger_formatter">logger_formatter</seealso>.</item>
+ <item>built-in filters,
see <seealso marker="logger_filters">logger_filters</seealso>.</item>
</list>
</description>
<datatypes>
<datatype>
- <name name="level"/>
+ <name name="primary_config"/>
<desc>
- <p>The severity level for the message to be logged.</p>
+ <p>Primary configuration data for Logger. The following
+ default values apply:</p>
+ <list>
+ <item><c>level => info</c></item>
+ <item><c>filter_default => log</c></item>
+ <item><c>filters => []</c></item>
+ </list>
</desc>
</datatype>
<datatype>
- <name name="log_event"/>
+ <name name="handler_config"/>
<desc>
- <p></p>
+ <p>Handler configuration data for Logger. The following
+ default values apply:</p>
+ <list>
+ <item><c>level => all</c></item>
+ <item><c>filter_default => log</c></item>
+ <item><c>filters => []</c></item>
+ <item><c>formatter => {logger_formatter, DefaultFormatterConfig</c>}</item>
+ </list>
+ <p>In addition to these, the following fields are
+ automatically inserted by Logger, values taken from the
+ two first parameters
+ to <seealso marker="#add_handler-3"><c>add_handler/3</c></seealso>:</p>
+ <list>
+ <item><c>id => HandlerId</c></item>
+ <item><c>module => Module</c></item>
+ </list>
+ <p>Handler specific configuration data is inserted by the
+ handler callback itself, in a sub structure associated with
+ the field named <c>config</c>.</p>
+ <p>See the <seealso marker="logger_formatter#type-config">
+ <c>logger_formatter(3)</c></seealso> manual page for
+ information about the default configuration for this
+ formatter.</p>
</desc>
</datatype>
<datatype>
- <name name="report"/>
+ <name name="filter"/>
<desc>
- <p></p>
+ <p>A filter which can be installed as a handler filter, or as
+ a primary filter in Logger.</p>
</desc>
</datatype>
<datatype>
- <name name="msg_fun"/>
+ <name name="filter_arg"/>
+ <desc>
+ <p>The second argument to the filter fun.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="filter_id"/>
+ <desc>
+ <p>A unique identifier for a filter.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="filter_return"/>
+ <desc>
+ <p>The return value from the filter fun.</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>
+ <datatype>
+ <name name="handler_id"/>
+ <desc>
+ <p>A unique identifier for a handler instance.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="level"/>
+ <desc>
+ <p>The severity level for the message to be logged.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="log_event"/>
<desc>
<p></p>
</desc>
@@ -117,7 +194,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
<p>When a log macro is used, Logger also inserts location
information:</p>
<list>
- <item><c>mfa => {?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY}</c></item>
+ <item><c>mfa => {?MODULE, ?FUNCTION_NAME, ?FUNCTION_ARITY}</c></item>
<item><c>file => ?FILE</c></item>
<item><c>line => ?LINE</c></item>
</list>
@@ -158,51 +235,15 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
</desc>
</datatype>
<datatype>
- <name name="config"/>
- <desc>
- <p>Configuration data for the logger part of Logger, or for a handler.</p>
- <p>The following default values apply:</p>
- <list>
- <item><c>level => info</c></item>
- <item><c>filter_default => log</c></item>
- <item><c>filters => []</c></item>
- <item><c>formatter => {logger_formatter,DefaultFormatterConfig</c>}</item>
- </list>
- <p>See the <seealso marker="logger_formatter#type-config">
- <c>logger_formatter(3)</c></seealso> manual page for
- information about the default configuration for this
- formatter.</p>
- </desc>
- </datatype>
- <datatype>
- <name name="handler_id"/>
- <desc>
- <p>A unique identifier for a handler instance.</p>
- </desc>
- </datatype>
- <datatype>
- <name name="filter_id"/>
- <desc>
- <p>A unique identifier for a filter.</p>
- </desc>
- </datatype>
- <datatype>
- <name name="filter"/>
- <desc>
- <p>A filter which can be installed for the logger part of
- Logger, or for a handler.</p>
- </desc>
- </datatype>
- <datatype>
- <name name="filter_arg"/>
+ <name name="msg_fun"/>
<desc>
- <p>The second argument to the filter fun.</p>
+ <p></p>
</desc>
</datatype>
<datatype>
- <name name="filter_return"/>
+ <name name="report"/>
<desc>
- <p>The return value from the filter fun.</p>
+ <p></p>
</desc>
</datatype>
<datatype>
@@ -213,15 +254,6 @@ 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>
@@ -258,6 +290,10 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
level.</p>
</section>
+ <section>
+ <marker id="logging_API"/>
+ <title>Logging API functions</title>
+ </section>
<funcs>
<func>
<name>emergency(StringOrReport[,Metadata])</name>
@@ -317,7 +353,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
<func>
<name>notice(StringOrReport[,Metadata])</name>
<name>notice(Format,Args[,Metadata])</name>
- <name>notice(Fun,FunArgs[,Metadata])</name>
+ <name>notice(Fun,FunArgs[,Metadata])</name>
<fsummary>Logs the given message as level <c>notice</c>.</fsummary>
<desc>
<p>Equivalent to
@@ -366,136 +402,21 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
<p>Log the given message.</p>
</desc>
</func>
+ </funcs>
+ <section>
+ <marker id="configuration_API"/>
+ <title>Configuration API functions</title>
+ </section>
+ <funcs>
<func>
- <name name="get_logger_config" arity="0"/>
- <fsummary>Look up the current configuration for the logger part
- of Logger.</fsummary>
- <desc>
- <p>Look up the current configuration for the logger part of
- Logger.</p>
- </desc>
- </func>
-
- <func>
- <name name="get_handler_config" arity="1"/>
- <fsummary>Look up the current configuration for the given
- handler.</fsummary>
- <desc>
- <p>Look up the current configuration for the given handler.</p>
- </desc>
- </func>
-
- <func>
- <name name="i" arity="0"/>
- <fsummary>Get all Logger configurations</fsummary>
- <desc>
- <p>Same as <seealso marker="#i/1"><c>logger:i(term)</c></seealso></p>
- </desc>
- </func>
-
- <func>
- <name name="i" arity="1" clause_i="1"/>
- <name name="i" arity="1" clause_i="2"/>
- <name name="i" arity="1" clause_i="3"/>
- <fsummary>Get all Logger configurations</fsummary>
- <desc>
- <p>Display or return all current Logger configurations.</p>
- <taglist>
- <tag><c><anno>Action</anno> = string</c></tag>
- <item>
- <p>Return the pretty printed current Logger configuration
- as iodata.</p>
- </item>
- <tag><c><anno>Action</anno> = term</c></tag>
- <item>
- <p>Return the current Logger configuration as a term. The
- format of this term may change between releases. For a
- stable format use <seealso marker="#get_handler_config/1">
- <c>logger:get_handler_config/1</c></seealso>
- and <seealso marker="#get_logger_config/0">
- <c>logger:get_logger_config/0</c></seealso>.</p>
- <p>The same as calling <c>logger:i()</c>.</p>
- </item>
- <tag><c><anno>Action</anno> = print</c></tag>
- <item>
- <p>Pretty print all the current Logger configuration to
- standard out. Example:</p>
- <code><![CDATA[1> logger:i(print).
-Current logger configuration:
- Level: info
- Filter Default: log
- Filters:
- Handlers:
- Id: default
- Module: logger_std_h
- Level: info
- Formatter:
- Module: logger_formatter
- Config: #{legacy_header => true,single_line => false,
- template => [{logger_formatter,header},"\n",msg,"\n"]}
- Filter Default: stop
- Filters:
- Id: stop_progress
- Fun: fun logger_filters:progress/2
- Config: stop
- Id: remote_gl
- Fun: fun logger_filters:remote_gl/2
- Config: stop
- Id: domain
- Fun: fun logger_filters:domain/2
- Config: {log,super,[beam,erlang,otp,sasl]}
- Id: no_domain
- Fun: fun logger_filters:domain/2
- Config: {log,undefined,[]}
- Handler Config:
- logger_std_h: #{type => standard_io}
- Level set per module:
- Module: my_module
- Level: debug]]></code>
- </item>
- </taglist>
- </desc>
- </func>
-
- <func>
- <name name="add_logger_filter" arity="2"/>
- <fsummary>Add a filter to the logger part of Logger.</fsummary>
+ <name name="add_handler" arity="3"/>
+ <fsummary>Add a handler with the given configuration.</fsummary>
<desc>
- <p>Add a filter to the logger part of Logger.</p>
- <p>The filter fun is called with the log event as the first
- parameter, and the specified <c>filter_args()</c> as the
- second parameter.</p>
- <p>The return value of the fun specifies if a log event is to
- be discarded or forwarded to the handlers:</p>
- <taglist>
- <tag><c>log_event()</c></tag>
- <item>
- <p>The filter <em>passed</em>. The next logger filter, if
- any, is applied. If no more logger filters exist, the
- log event is forwarded to the handler part of Logger,
- where handler filters are applied.</p>
- </item>
- <tag><c>stop</c></tag>
- <item>
- <p>The filter <em>did not pass</em>, and the log event is
- immediately discarded.</p>
- </item>
- <tag><c>ignore</c></tag>
- <item>
- <p>The filter has no knowledge of the log event. The next
- logger filter, if any, is applied. If no more logger
- filters exist, the value of the <c>filter_default</c>
- configuration parameter for the logger part specifies if
- the log event shall be discarded or forwarded to the
- handler part.</p>
- </item>
- </taglist>
- <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>
+ <p>Add a handler with the given configuration.</p>
+ <p><c><anno>HandlerId</anno></c> is a unique identifier which
+ must be used in all subsequent calls referring to this
+ handler.</p>
</desc>
</func>
@@ -541,98 +462,12 @@ Current logger configuration:
</func>
<func>
- <name name="remove_logger_filter" arity="1"/>
- <fsummary>Remove a filter from the logger part of Logger.</fsummary>
- <desc>
- <p>Remove the filter identified
- by <c><anno>FilterId</anno></c> from the logger part of Logger.</p>
- </desc>
- </func>
-
- <func>
- <name name="remove_handler_filter" arity="2"/>
- <fsummary>Remove a filter from the specified handler.</fsummary>
- <desc>
- <p>Remove the filter identified
- by <c><anno>FilterId</anno></c> from the handler identified
- by <c><anno>HandlerId</anno></c>.</p>
- </desc>
- </func>
-
- <func>
- <name name="add_handler" arity="3"/>
- <fsummary>Add a handler with the given configuration.</fsummary>
- <desc>
- <p>Add a handler with the given configuration.</p>
- <p><c><anno>HandlerId</anno></c> is a unique identifier which
- must be used in all subsequent calls referring to this
- handler.</p>
- </desc>
- </func>
-
- <func>
- <name name="remove_handler" arity="1"/>
- <fsummary>Remove the handler with the specified identity.</fsummary>
- <desc>
- <p>Remove the handler identified by <c><anno>HandlerId</anno></c>.</p>
- </desc>
- </func>
-
- <func>
- <name name="set_module_level" arity="2"/>
- <fsummary>Set the log level for the specified module.</fsummary>
- <desc>
- <p>Set the log level for the
- specified <c><anno>Module</anno></c>.</p>
- <p>The log level for a module overrides the global log level
- of Logger for log events originating from the module in
- question. Notice, however, that it does not override the
- level configuration for any handler.</p>
- <p>For example: Assume that the global log level for Logger
- is <c>info</c>, and there is one handler, <c>h1</c>, with
- level <c>info</c> and one handler, <c>h2</c>, with
- level <c>debug</c>.</p>
- <p>With this configuration, no debug messages will be logged,
- since they are all stopped by the global log level.</p>
- <p>If the level for <c>mymodule</c> is now set
- to <c>debug</c>, then debug events from this module will be
- logged by the handler <c>h2</c>, but not by
- handler <c>h1</c>.</p>
- <p>Debug events from other modules are still not logged.</p>
- <p>To change the global log level for Logger, use
- <seealso marker="#set_logger_config/2">
- <c>logger:set_logger_config(level,Level)</c></seealso>.</p>
- <p>To change the log level for a handler, use
- <seealso marker="#set_handler_config/3">
- <c>logger:set_handler_config(HandlerId,level,Level)</c></seealso>.</p>
- <note>
- <p>The originating module for a log event is only detected
- if <c>mfa=>{Module,Function,Arity}</c> exists in the
- metadata. When log macros are used, this association is
- automatically added to all log events. If an API function
- is called directly, without using a macro, the logging
- client must explicitly add this information if module
- levels shall have any effect.</p>
- </note>
- </desc>
- </func>
-
- <func>
- <name name="unset_module_level" arity="1"/>
- <fsummary>Remove a module specific log setting.</fsummary>
- <desc>
- <p>Remove a module specific log setting. After this, the
- global log level is used for the specified module.</p>
- </desc>
- </func>
-
- <func>
<name name="add_handlers" arity="1" clause_i="1"/>
<fsummary>Set up log handlers from the application's
configuration parameters.</fsummary>
<desc>
<p>Reads the application configuration parameter <c>logger</c> and
- calls <c>logger:add_handlers/1</c> with its contents.</p>
+ calls <c>add_handlers/1</c> with its contents.</p>
</desc>
</func>
@@ -670,61 +505,158 @@ start(_, []) ->
[{kernel,
[{logger,
%% Disable the default Kernel handler
- [{handler,default,undefined}]}]},
+ [{handler, default, undefined}]}]},
{my_app,
[{logger,
%% Enable this handler as the default
- [{handler,default,my_handler,#{}}]}]}].
+ [{handler, default, my_handler, #{}}]}]}].
</code>
</desc>
</func>
<func>
- <name name="set_logger_config" arity="1"/>
- <fsummary>Set configuration data for the logger part of Logger.</fsummary>
+ <name name="add_primary_filter" arity="2"/>
+ <fsummary>Add a primary filter to Logger.</fsummary>
<desc>
- <p>Set configuration data for the logger part of Logger. This
- overwrites the current logger configuration.</p>
- <p>To modify the existing configuration,
- use <seealso marker="#update_logger_config-1">
- <c>update_logger_config/1</c></seealso>, or, if a more
- complex merge is needed, read the current configuration
- with <seealso marker="#get_logger_config-0"><c>get_logger_config/0</c>
- </seealso>, then do the merge before writing the new
- configuration back with this function.</p>
- <p>If a key is removed compared to the current configuration,
- the default value is used.</p>
+ <p>Add a primary filter to Logger.</p>
+ <p>The filter fun is called with the log event as the first
+ parameter, and the specified <c>filter_args()</c> as the
+ second parameter.</p>
+ <p>The return value of the fun specifies if a log event is to
+ be discarded or forwarded to the handlers:</p>
+ <taglist>
+ <tag><c>log_event()</c></tag>
+ <item>
+ <p>The filter <em>passed</em>. The next primary filter, if
+ any, is applied. If no more primary filters exist, the
+ log event is forwarded to the handler part of Logger,
+ where handler filters are applied.</p>
+ </item>
+ <tag><c>stop</c></tag>
+ <item>
+ <p>The filter <em>did not pass</em>, and the log event is
+ immediately discarded.</p>
+ </item>
+ <tag><c>ignore</c></tag>
+ <item>
+ <p>The filter has no knowledge of the log event. The next
+ primary filter, if any, is applied. If no more primary
+ filters exist, the value of the
+ primary <c>filter_default</c> configuration parameter
+ specifies if the log event shall be discarded or
+ forwarded to the handler part.</p>
+ </item>
+ </taglist>
+ <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>
</desc>
</func>
<func>
- <name name="set_logger_config" arity="2"/>
- <fsummary>Add or update configuration data for the logger part
- of Logger.</fsummary>
+ <name name="get_config" arity="0"/>
+ <fsummary>Look up the current Logger configuration</fsummary>
<desc>
- <p>Add or update configuration data for the logger part of
- Logger. If the given <c><anno>Key</anno></c> already exists,
- its associated value will be changed
- to <c><anno>Value</anno></c>. If it does not exist, it will
- be added.</p>
+ <p>Look up all current Logger configuration, including primary
+ and handler configuration, and module level settings.</p>
</desc>
</func>
<func>
- <name name="update_logger_config" arity="1"/>
- <fsummary>Update configuration data for the logger part of
- Logger.</fsummary>
+ <name name="get_handler_config" arity="0"/>
+ <fsummary>Look up the current configuration for all handlers.</fsummary>
<desc>
- <p>Update configuration data for the logger part of
- Logger. This function behaves as if it was implemented as
- follows:</p>
- <code type="erl">
-{ok,Old} = logger:get_logger_config(),
-logger:set_logger_config(maps:merge(Old,Config)).
- </code>
- <p>To overwrite the existing configuration without any merge,
- use <seealso marker="#set_logger_config-1"><c>set_logger_config/1</c>
- </seealso>.</p>
+ <p>Look up the current configuration for all handlers.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_handler_config" arity="1"/>
+ <fsummary>Look up the current configuration for the given
+ handler.</fsummary>
+ <desc>
+ <p>Look up the current configuration for the given handler.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_handler_ids" arity="0"/>
+ <fsummary>Look up the identities for all installed handlers.</fsummary>
+ <desc>
+ <p>Look up the identities for all installed handlers.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_primary_config" arity="0"/>
+ <fsummary>Look up the current primary configuration for Logger.</fsummary>
+ <desc>
+ <p>Look up the current primary configuration for Logger.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_module_level" arity="0"/>
+ <fsummary>Look up all current module levels.</fsummary>
+ <desc>
+ <p>Look up all current module levels. Returns a list
+ containing one <c>{Module,Level}</c> element for each module
+ for which the module level was previously set
+ with <seealso marker="#set_module_level-2">
+ <c>set_module_level/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_module_level" arity="1"/>
+ <fsummary>Look up the current level for the given modules.</fsummary>
+ <desc>
+ <p>Look up the current level for the given modules. Returns a
+ list containing one <c>{Module,Level}</c> element for each
+ of the given modules for which the module level was
+ previously set with <seealso marker="#set_module_level-2">
+ <c>set_module_level/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="get_process_metadata" arity="0"/>
+ <fsummary>Retrieve data set with set_process_metadata/1.</fsummary>
+ <desc>
+ <p>Retrieve data set
+ with <seealso marker="#set_process_metadata-1">
+ <c>set_process_metadata/1</c></seealso> or
+ <seealso marker="#update_process_metadata-1">
+ <c>update_process_metadata/1</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="remove_handler" arity="1"/>
+ <fsummary>Remove the handler with the specified identity.</fsummary>
+ <desc>
+ <p>Remove the handler identified by <c><anno>HandlerId</anno></c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="remove_handler_filter" arity="2"/>
+ <fsummary>Remove a filter from the specified handler.</fsummary>
+ <desc>
+ <p>Remove the filter identified
+ by <c><anno>FilterId</anno></c> from the handler identified
+ by <c><anno>HandlerId</anno></c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="remove_primary_filter" arity="1"/>
+ <fsummary>Remove a primary filter from Logger.</fsummary>
+ <desc>
+ <p>Remove the primary filter identified
+ by <c><anno>FilterId</anno></c> from Logger.</p>
</desc>
</func>
@@ -763,18 +695,122 @@ logger:set_logger_config(maps:merge(Old,Config)).
</func>
<func>
- <name name="update_handler_config" arity="2"/>
- <fsummary>Update configuration data for the specified handler.</fsummary>
+ <name name="set_primary_config" arity="1"/>
+ <fsummary>Set primary configuration data for Logger.</fsummary>
<desc>
- <p>Update configuration data for the specified handler. This function
- behaves as if it was implemented as follows:</p>
- <code type="erl">
-{ok,{_,Old}} = logger:get_handler_config(HandlerId),
-logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
- </code>
- <p>To overwrite the existing configuration without any merge,
- use <seealso marker="#set_handler_config-2"><c>set_handler_config/2</c>
+ <p>Set primary configuration data for Logger. This
+ overwrites the current configuration.</p>
+ <p>To modify the existing configuration,
+ use <seealso marker="#update_primary_config-1">
+ <c>update_primary_config/1</c></seealso>, or, if a more
+ complex merge is needed, read the current configuration
+ with <seealso marker="#get_primary_config-0"><c>get_primary_config/0</c>
+ </seealso>, then do the merge before writing the new
+ configuration back with this function.</p>
+ <p>If a key is removed compared to the current configuration,
+ the default value is used.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="set_primary_config" arity="2"/>
+ <fsummary>Add or update primary configuration data for Logger.</fsummary>
+ <desc>
+ <p>Add or update primary configuration data for Logger. If the
+ given <c><anno>Key</anno></c> already exists, its associated
+ value will be changed to <c><anno>Value</anno></c>. If it
+ does not exist, it will be added.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="set_module_level" arity="2"/>
+ <fsummary>Set the log level for the specified modules.</fsummary>
+ <desc>
+ <p>Set the log level for the
+ specified modules.</p>
+ <p>The log level for a module overrides the primary log level
+ of Logger for log events originating from the module in
+ question. Notice, however, that it does not override the
+ level configuration for any handler.</p>
+ <p>For example: Assume that the primary log level for Logger
+ is <c>info</c>, and there is one handler, <c>h1</c>, with
+ level <c>info</c> and one handler, <c>h2</c>, with
+ level <c>debug</c>.</p>
+ <p>With this configuration, no debug messages will be logged,
+ since they are all stopped by the primary log level.</p>
+ <p>If the level for <c>mymodule</c> is now set
+ to <c>debug</c>, then debug events from this module will be
+ logged by the handler <c>h2</c>, but not by
+ handler <c>h1</c>.</p>
+ <p>Debug events from other modules are still not logged.</p>
+ <p>To change the primary log level for Logger, use
+ <seealso marker="#set_primary_config/2">
+ <c>set_primary_config(level, Level)</c></seealso>.</p>
+ <p>To change the log level for a handler, use
+ <seealso marker="#set_handler_config/3">
+ <c>set_handler_config(HandlerId, level, Level)</c>
</seealso>.</p>
+ <note>
+ <p>The originating module for a log event is only detected
+ if the key <c>mfa</c> exists in the metadata, and is
+ associated with <c>{Module, Function, Arity}</c>. When log
+ macros are used, this association is automatically added
+ to all log events. If an API function is called directly,
+ without using a macro, the logging client must explicitly
+ add this information if module levels shall have any
+ effect.</p>
+ </note>
+ </desc>
+ </func>
+
+ <func>
+ <name name="set_process_metadata" arity="1"/>
+ <fsummary>Set metadata to use when logging from current process.</fsummary>
+ <desc>
+ <p>Set metadata which Logger shall automatically insert in
+ all log events produced on the current process.</p>
+ <p>Location data produced by the log macros, and/or metadata
+ given as argument to the log call (API function or macro),
+ are merged with the process metadata. If the same keys
+ occur, values from the metadata argument to the log call
+ overwrite values from the process metadata, which in turn
+ overwrite values from the location data.</p>
+ <p>Subsequent calls to this function overwrites previous data
+ set. To update existing data instead of overwriting it,
+ see <seealso marker="#update_process_metadata-1">
+ <c>update_process_metadata/1</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="unset_module_level" arity="0"/>
+ <fsummary>Remove module specific log settings for all modules.</fsummary>
+ <desc>
+ <p>Remove module specific log settings. After this, the
+ primary log level is used for all modules.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="unset_module_level" arity="1"/>
+ <fsummary>Remove module specific log settings for the given
+ modules.</fsummary>
+ <desc>
+ <p>Remove module specific log settings. After this, the
+ primary log level is used for the specified modules.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="unset_process_metadata" arity="0"/>
+ <fsummary>Delete data set with set_process_metadata/1.</fsummary>
+ <desc>
+ <p>Delete data set
+ with <seealso marker="#set_process_metadata-1">
+ <c>set_process_metadata/1</c></seealso> or
+ <seealso marker="#update_process_metadata-1">
+ <c>update_process_metadata/1</c></seealso>.</p>
</desc>
</func>
@@ -786,9 +822,10 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
<p>The new configuration is merged with the existing formatter
configuration.</p>
<p>To overwrite the existing configuration without any merge,
- use <seealso marker="#set_handler_config-3">
- <c>set_handler_config(HandlerId,formatter,
- {FormatterModule,FormatterConfig})</c></seealso>.</p>
+ use</p>
+ <pre>
+<seealso marker="#set_handler_config-3">set_handler_config(HandlerId, formatter,
+ {FormatterModule, FormatterConfig})</seealso>.</pre>
</desc>
</func>
@@ -797,39 +834,41 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
<fsummary>Update the formatter configuration for the specified handler.</fsummary>
<desc>
<p>Update the formatter configuration for the specified handler.</p>
- <p>This is equivalent
- to <br/><seealso marker="#update_formatter_config-2">
- <c>update_formatter_config(<anno>HandlerId</anno>,#{<anno>Key</anno>=><anno>Value</anno>})</c></seealso></p>
+ <p>This is equivalent to</p>
+ <pre>
+<seealso marker="#update_formatter_config-2">update_formatter_config(<anno>HandlerId</anno>, #{<anno>Key</anno> => <anno>Value</anno>})</seealso></pre>
</desc>
</func>
<func>
- <name name="compare_levels" arity="2"/>
- <fsummary>Compare the severity of two log levels.</fsummary>
+ <name name="update_handler_config" arity="2"/>
+ <fsummary>Update configuration data for the specified handler.</fsummary>
<desc>
- <p>Compare the severity of two log levels. Returns <c>gt</c>
- if <c>Level1</c> is more severe than
- <c>Level2</c>, <c>lt</c> if <c>Level1</c> is less severe,
- and <c>eq</c> if the levels are equal.</p>
+ <p>Update configuration data for the specified handler. This function
+ behaves as if it was implemented as follows:</p>
+ <code type="erl">
+{ok, {_, Old}} = logger:get_handler_config(HandlerId),
+logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
+ </code>
+ <p>To overwrite the existing configuration without any merge,
+ use <seealso marker="#set_handler_config-2"><c>set_handler_config/2</c>
+ </seealso>.</p>
</desc>
</func>
<func>
- <name name="set_process_metadata" arity="1"/>
- <fsummary>Set metadata to use when logging from current process.</fsummary>
+ <name name="update_primary_config" arity="1"/>
+ <fsummary>Update primary configuration data for Logger.</fsummary>
<desc>
- <p>Set metadata which Logger shall automatically insert in
- all log events produced on the current process.</p>
- <p>Location data produced by the log macros, and/or metadata
- given as argument to the log call (API function or macro),
- are merged with the process metadata. If the same keys
- occur, values from the metadata argument to the log call
- overwrite values from the process metadata, which in turn
- overwrite values from the location data.</p>
- <p>Subsequent calls to this function overwrites previous data
- set. To update existing data instead of overwriting it,
- see <seealso marker="#update_process_metadata-1">
- <c>update_process_metadata/1</c></seealso>.</p>
+ <p>Update primary configuration data for Logger. This function
+ behaves as if it was implemented as follows:</p>
+ <code type="erl">
+Old = logger:get_primary_config(),
+logger:set_primary_config(maps:merge(Old, Config)).
+ </code>
+ <p>To overwrite the existing configuration without any merge,
+ use <seealso marker="#set_primary_config-1"><c>set_primary_config/1</c>
+ </seealso>.</p>
</desc>
</func>
@@ -843,7 +882,7 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
<p>If process metadata exists for the current process, this
function behaves as if it was implemented as follows:</p>
<code type="erl">
-logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
+logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
</code>
<p>If no process metadata exists, the function behaves as
<seealso marker="#set_process_metadata-1">
@@ -851,48 +890,44 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
</seealso>.</p>
</desc>
</func>
+ </funcs>
+ <section>
+ <marker id="misc_API"/>
+ <title>Miscellaneous API functions</title>
+ </section>
+ <funcs>
<func>
- <name name="get_process_metadata" arity="0"/>
- <fsummary>Retrieve data set with set_process_metadata/1.</fsummary>
- <desc>
- <p>Retrieve data set
- with <seealso marker="#set_process_metadata-1">
- <c>set_process_metadata/1</c></seealso> or
- <seealso marker="#update_process_metadata-1">
- <c>update_process_metadata/1</c></seealso>.</p>
- </desc>
- </func>
-
- <func>
- <name name="unset_process_metadata" arity="0"/>
- <fsummary>Delete data set with set_process_metadata/1.</fsummary>
+ <name name="compare_levels" arity="2"/>
+ <fsummary>Compare the severity of two log levels.</fsummary>
<desc>
- <p>Delete data set
- with <seealso marker="#set_process_metadata-1">
- <c>set_process_metadata/1</c></seealso> or
- <seealso marker="#update_process_metadata-1">
- <c>update_process_metadata/1</c></seealso>.</p>
+ <p>Compare the severity of two log levels. Returns <c>gt</c>
+ if <c>Level1</c> is more severe than
+ <c>Level2</c>, <c>lt</c> if <c>Level1</c> is less severe,
+ and <c>eq</c> if the levels are equal.</p>
</desc>
</func>
<func>
<name name="format_report" arity="1"/>
- <fsummary>Convert a log message on report form to {Format,Args}.</fsummary>
+ <fsummary>Convert a log message on report form to {Format, Args}.</fsummary>
<desc>
- <p>Convert a log message on report form to <c>{Format,Args}</c>.</p>
- <p>This is the default report callback used
+ <p>Convert a log message on report form to <c>{Format,
+ Args}</c>. This is the default report callback used
by <seealso marker="logger_formatter">
<c>logger_formatter</c></seealso> when no custom report
- callback is found.</p>
+ callback is found. See
+ section <seealso marker="logger_chapter#log_message">Log
+ Message</seealso> in the Kernel User's Guide for
+ information about report callbacks and valid forms of log
+ messages.</p>
<p>The function produces lines of <c>Key: Value</c> from
key-value lists. Strings are printed with <c>~ts</c> and
other terms with <c>~tp</c>.</p>
- <p>If the <c><anno>Report</anno></c> is a map, it is
- converted to a key-value list before formatting as such.</p>
+ <p>If <c><anno>Report</anno></c> is a map, it is converted to
+ a key-value list before formatting as such.</p>
</desc>
</func>
-
</funcs>
<section>
@@ -904,11 +939,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
<funcs>
<func>
- <name>HModule:adding_handler(Config1) -> {ok,Config2} | {error,Reason}</name>
+ <name>HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}</name>
<fsummary>An instance of this handler is about to be added.</fsummary>
<type>
<v>Config1 = Config2 =
- <seealso marker="#type-config">config()</seealso></v>
+ <seealso marker="#type-handler_config">handler_config()</seealso></v>
<v>Reason = term()</v>
</type>
<desc>
@@ -928,11 +963,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
</func>
<func>
- <name>HModule:changing_config(Config1,Config2) -> {ok,Config3} | {error,Reason}</name>
+ <name>HModule:changing_config(Config1, Config2) -> {ok, Config3} | {error, Reason}</name>
<fsummary>The configuration for this handler is about to change.</fsummary>
<type>
<v>Config1 = Config2 = Config3 =
- <seealso marker="#type-config">config()</seealso></v>
+ <seealso marker="#type-handler_config">handler_config()</seealso></v>
<v>Reason = term()</v>
</type>
<desc>
@@ -952,17 +987,17 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
</func>
<func>
- <name>HModule:log(LogEvent,Config) -> void()</name>
+ <name>HModule:log(LogEvent, Config) -> void()</name>
<fsummary>Log the given log event.</fsummary>
<type>
<v>LogEvent =
<seealso marker="#type-log_event">log_event()</seealso></v>
<v>Config =
- <seealso marker="#type-config">config()</seealso></v>
+ <seealso marker="#type-handler_config">handler_config()</seealso></v>
</type>
<desc>
<p>This callback function is mandatory.</p>
- <p>The function is called when all global filters and all
+ <p>The function is called when all primary filters and all
handler filters for the handler in question have passed for
the given log event.</p>
<p>The handler identity is associated with the <c>id</c> key
@@ -978,7 +1013,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
<fsummary>The given handler is about to be removed.</fsummary>
<type>
<v>Config =
- <seealso marker="#type-config">config()</seealso></v>
+ <seealso marker="#type-handler_config">handler_config()</seealso></v>
</type>
<desc>
<p>This callback function is optional.</p>
@@ -1002,18 +1037,30 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
<funcs>
<func>
- <name>FModule:check_config(FConfig) -> ok | {error,term()}</name>
+ <name>FModule:check_config(FConfig) -> ok | {error, Reason}</name>
<fsummary>Validate the given formatter configuration.</fsummary>
<type>
<v>FConfig =
<seealso marker="#type-formatter_config">formatter_config()</seealso></v>
+ <v>Reason = term()</v>
</type>
<desc>
<p>This callback function is optional.</p>
<p>The function is called by a Logger when formatter
configuration is set or modified. The formatter must
validate the given configuration and return <c>ok</c> if it
- is correct, and <c>{error,term()}</c> if it is faulty.</p>
+ is correct, and <c>{error,Reason}</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>
<p>See <seealso marker="logger_formatter">
<c>logger_formatter(3)</c></seealso>
for an example implementation. <c>logger_formatter</c> is the
@@ -1021,7 +1068,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
</desc>
</func>
<func>
- <name>FModule:format(LogEvent,FConfig) -> FormattedLogEntry</name>
+ <name>FModule:format(LogEvent, FConfig) -> FormattedLogEntry</name>
<fsummary>Format the given log event.</fsummary>
<type>
<v>LogEvent =
@@ -1045,6 +1092,20 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
</desc>
</func>
</funcs>
+
+ <section>
+ <title>See Also</title>
+ <p>
+ <seealso marker="config"><c>config(4)</c></seealso>,
+ <seealso marker="erts:erlang"><c>erlang(3)</c></seealso>,
+ <seealso marker="stdlib:io"><c>io(3)</c></seealso>,
+ <seealso marker="logger_disk_log_h"><c>logger_disk_log_h(3)</c></seealso>,
+ <seealso marker="logger_filters"><c>logger_filters(3)</c></seealso>,
+ <seealso marker="logger_formatter"><c>logger_formatter(3)</c></seealso>,
+ <seealso marker="logger_std_h"><c>logger_std_h(3)</c></seealso>,
+ <seealso marker="stdlib:unicode"><c>unicode(3)</c></seealso>
+ </p>
+ </section>
</erlref>