diff options
Diffstat (limited to 'lib/kernel/doc/src/logger.xml')
| -rw-r--r-- | lib/kernel/doc/src/logger.xml | 184 |
1 files changed, 112 insertions, 72 deletions
diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index cac9c39f2a..f7e740e90d 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -33,23 +33,51 @@ <file>logger.xml</file> </header> <module>logger</module> - <modulesummary>API module for the logger.</modulesummary> + <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 logger API. It contains functions that allow - application to use a single log API and the system to manage those log - events independently. To log events the logger - <seealso marker="#macros">macros</seealso> should be used. For instance, - to log a new error log event:</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 will then be sent to the configured log handlers which - by default means that it will be printed to the console. If you want + <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 - have to configure the default handler to do so. The simplest way is + 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, @@ -63,7 +91,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro <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, + <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, @@ -129,8 +157,8 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro <c>update_process_metadata/1</c></seealso>.</p> <p>Logger merges all the metadata maps before forwarding the log event to the handlers. If the same keys occur, values - from the log call overwrites process metadata, which in turn - overwrites values set by Logger.</p> + from the log call overwrite process metadata, which in turn + overwrite values set by Logger.</p> </desc> </datatype> <datatype> @@ -165,7 +193,8 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro <datatype> <name name="filter"/> <desc> - <p>A filter which can be installed for logger or for a handler.</p> + <p>A filter which can be installed for the logger part of + Logger, or for a handler.</p> </desc> </datatype> <datatype> @@ -213,9 +242,9 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro <item><c>?LOG_DEBUG(FunOrFormat,Args[,Metadata])</c></item> </list> - <p>All macros expand to a call to logger, where <c>Level</c> is - taken from the macro name, and location data is added. See the - description of + <p>All macros expand to a call to Logger, where <c>Level</c> is + taken from the macro name, and location data is added to the + metadata. See the description of the <seealso marker="#type-metadata"><c>metadata()</c></seealso> type for more information about the location data.</p> @@ -335,23 +364,26 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro <func> <name name="get_logger_config" arity="0"/> - <fsummary>Lookup the current configuration for logger.</fsummary> + <fsummary>Look up the current configuration for the logger part + of Logger.</fsummary> <desc> - <p>Lookup the current configuration for logger.</p> + <p>Look up the current configuration for the logger part of + Logger.</p> </desc> </func> <func> <name name="get_handler_config" arity="1"/> - <fsummary>Lookup the current configuration for the given handler.</fsummary> + <fsummary>Look up the current configuration for the given + handler.</fsummary> <desc> - <p>Lookup the current configuration for the given handler.</p> + <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> + <fsummary>Get all Logger configurations</fsummary> <desc> <p>Same as <seealso marker="#i/1"><c>logger:i(term)</c></seealso></p> </desc> @@ -361,28 +393,28 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro <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> + <fsummary>Get all Logger configurations</fsummary> <desc> - <p>Display or return all current logger configuration.</p> + <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 + <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 inbetween releases. For a + <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>. - The same as calling <c>logger:i()</c>.</p> + <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 + <p>Pretty print all the current Logger configuration to standard out. Example:</p> <code><![CDATA[1> logger:i(print). Current logger configuration: @@ -423,9 +455,9 @@ Current logger configuration: <func> <name name="add_logger_filter" arity="2"/> - <fsummary>Add a filter to the logger.</fsummary> + <fsummary>Add a filter to the logger part of Logger.</fsummary> <desc> - <p>Add a filter to the logger.</p> + <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> @@ -436,8 +468,8 @@ Current logger configuration: <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 the - logger, where handler filters are applied.</p> + log event is forwarded to the handler part of Logger, + where handler filters are applied.</p> </item> <tag><c>stop</c></tag> <item> @@ -449,9 +481,9 @@ Current logger configuration: <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 specifies if the - log event shall be discarded or forwarded to the handler - part.</p> + 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#Filter"> @@ -505,10 +537,10 @@ Current logger configuration: <func> <name name="remove_logger_filter" arity="1"/> - <fsummary>Remove a filter from the logger.</fsummary> + <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.</p> + by <c><anno>FilterId</anno></c> from the logger part of Logger.</p> </desc> </func> @@ -548,21 +580,21 @@ Current logger configuration: <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 the logger for log event originating from the module in + 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 the - 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 + <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 set now set + <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 the logger, use + <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 @@ -572,9 +604,10 @@ Current logger configuration: <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 the logger API + 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.</p> + client must explicitly add this information if module + levels shall have any effect.</p> </note> </desc> </func> @@ -590,10 +623,11 @@ Current logger configuration: <func> <name name="add_handlers" arity="1" clause_i="1"/> - <fsummary>Setup logger handlers from the applications configuration parameters.</fsummary> + <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 it contents.</p> + calls <c>logger:add_handlers/1</c> with its contents.</p> </desc> </func> @@ -602,11 +636,12 @@ Current logger configuration: <fsummary>Setup logger handlers.</fsummary> <type name="config_handler"/> <desc> - <p>This function should be used by custom logger handlers to make + <p>This function should be used by custom Logger handlers to make configuration consistent no matter which handler the system uses. - Normal usage to to add a call to <c>logger:add_handlers/1</c> - just after the processes that the handler needs are started - and pass the applications logger config as an argument. Eg.</p> + Normal usage is to add a call to <c>logger:add_handlers/1</c> + just after the processes that the handler needs are started, + and pass the application's <c>logger</c> configuration as the argument. + For example:</p> <code> -behaviour(application). start(_, []) -> @@ -616,19 +651,20 @@ start(_, []) -> {ok, Pid, []}; Error -> Error end.</code> - <p>This will read the <c>logger</c> configuration parameter from - the handler application and start the configured handlers. The contents - of the configuration use the same rules as the + <p>This reads the <c>logger</c> configuration parameter from + the <c>my_all</c> application and starts the configured + handlers. The contents of the configuration use the same + rules as the <seealso marker="logger_chapter#handler-configuration">logger handler configuration</seealso>. </p> - <p>If the handler is meant to replace the default handler the kernels - default handlers have to be disabled before the new handler is added. - A <c>sys.config</c> file that disables the kernel handler and adds - a custom handler could looks like this:</p> + <p>If the handler is meant to replace the default handler, the Kernel's + default handler have to be disabled before the new handler is added. + A <c>sys.config</c> file that disables the Kernel handler and adds + a custom handler could look like this:</p> <code> [{kernel, [{logger, - %% Disable the default kernel handler + %% Disable the default Kernel handler [{handler,default,undefined}]}]}, {my_app, [{logger, @@ -640,10 +676,10 @@ start(_, []) -> <func> <name name="set_logger_config" arity="1"/> - <fsummary>Set configuration data for the logger.</fsummary> + <fsummary>Set configuration data for the logger part of Logger.</fsummary> <desc> - <p>Set configuration data for the logger. This overwrites the - current logger configuration.</p> + <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 @@ -658,21 +694,25 @@ start(_, []) -> <func> <name name="set_logger_config" arity="2"/> - <fsummary>Add or update configuration data for the logger.</fsummary> + <fsummary>Add or update configuration data for the logger part + of Logger.</fsummary> <desc> - <p>Add or update configuration data for the 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>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> </desc> </func> <func> <name name="update_logger_config" arity="1"/> - <fsummary>Update configuration data for the logger.</fsummary> + <fsummary>Update configuration data for the logger part of + Logger.</fsummary> <desc> - <p>Update configuration data for the logger. This function - behaves as if it was implemented as follows:</p> + <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)). @@ -697,7 +737,7 @@ logger:set_logger_config(maps:merge(Old,Config)). </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, - and the key is know by Logger, the default value is used. If + and the key is known by Logger, the default value is used. If it is a custom key, then it is up to the handler implementation if the value is removed or a default value is inserted.</p> |