diff options
Diffstat (limited to 'lib/kernel/doc/src/logger.xml')
| -rw-r--r-- | lib/kernel/doc/src/logger.xml | 883 |
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> |