From 5e23103186cb71c64f7f2fa28cbfd8c62d7ee21b Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Wed, 13 Jun 2018 11:48:58 +0200 Subject: [logger] Update documentation --- lib/kernel/doc/src/logger.xml | 33 +++++--- lib/kernel/doc/src/logger_arch.png | Bin 32407 -> 32187 bytes lib/kernel/doc/src/logger_chapter.xml | 137 +++++++++++++++------------------- 3 files changed, 84 insertions(+), 86 deletions(-) (limited to 'lib/kernel/doc/src') diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index 7f35a5d752..8940c89ab8 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -86,6 +86,14 @@ logger:error("error happened because: ~p", [Reason]). % Without macro built-in filters, see logger_filters. + + +

Since Logger is new in Erlang/OTP 21.0, we do reserve the right + to introduce changes to the Logger API and functionality in + patches following this release. These changes might or might not + be backwards compatible with the initial version.

+ + @@ -939,7 +947,8 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)). - HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason} + HModule:adding_handler(Config1) -> {ok, Config2} | {error, + Reason} An instance of this handler is about to be added. Config1 = Config2 = @@ -948,9 +957,10 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).

This callback function is optional.

-

The function is called when an new handler is about to be - added, and the purpose is to verify the configuration and - initiate all resources needed by the handler.

+

The function is called on a temporary process when an new + handler is about to be added. The purpose is to verify the + configuration and initiate all resources needed by the + handler.

The handler identity is associated with the id key in Config1.

If everything succeeds, the callback function can add @@ -972,9 +982,9 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).

This callback function is optional.

-

The function is called when the configuration for a handler - is about to change, and the purpose is to verify and act on - the new configuration.

+

The function is called on a temporary process when the + configuration for a handler is about to change. The purpose + is to verify and act on the new configuration.

Config1 is the existing configuration and Config2 is the new configuration.

The handler identity is associated with the id key @@ -999,7 +1009,8 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).

This callback function is mandatory.

The function is called when all primary filters and all handler filters for the handler in question have passed for - the given log event.

+ the given log event. It is called on the client process, that + is, the process that issued the log event.

The handler identity is associated with the id key in Config.

The handler must log the event.

@@ -1017,9 +1028,9 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).

This callback function is optional.

-

The function is called when a handler is about to be - removed, and the purpose is to release all resources used by - the handler.

+

The function is called on a temporary process when a + handler is about to be removed. The purpose is to release + all resources used by the handler.

The handler identity is associated with the id key in Config.

The return value is ignored by Logger.

diff --git a/lib/kernel/doc/src/logger_arch.png b/lib/kernel/doc/src/logger_arch.png index a9b9a658b4..a3a863c511 100644 Binary files a/lib/kernel/doc/src/logger_arch.png and b/lib/kernel/doc/src/logger_arch.png differ diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml index f7df0a3e6e..6e1eab8a8e 100644 --- a/lib/kernel/doc/src/logger_chapter.xml +++ b/lib/kernel/doc/src/logger_chapter.xml @@ -48,6 +48,13 @@ handler, replace it by a custom handler, and install additional handlers.

+ +

Since Logger is new in Erlang/OTP 21.0, we do reserve the right + to introduce changes to the Logger API and functionality in + patches following this release. These changes might or might not + be backwards compatible with the initial version.

+ +
Overview

A log event consists of a log level, the @@ -84,11 +91,11 @@ section Filters for more details.

If a log event passes through all primary filters and all - handler filters for a specific handler, Logger forwards the event - to the handler callback. The handler formats and prints the - event to its destination. See - section Handlers for - more details.

+ handler filters for a specific handler, Logger forwards the + event to the handler callback. The handler formats and + prints the event to its destination. See + section Handlers for more + details.

Everything up to and including the call to the handler callbacks is executed on the client process, that is, the process where the log event was issued. It is up to the handler @@ -113,10 +120,11 @@ Log Level

The log level indicates the severity of a event. In - accordance with the Syslog protocol, RFC-5424, eight log - levels can be specified. The following table lists all - possible log levels by name (atom), integer value, and - description:

+ accordance with the Syslog protocol, + RFC + 5424, eight log levels can be specified. The following + table lists all possible log levels by name (atom), integer + value, and description:

@@ -337,7 +345,7 @@ logger:debug(#{got => connection_request, id => Id, state => State}, Handlers

A handler is defined as a module exporting at least the - following function:

+ following callback function:

log(LogEvent, Config) -> void()
@@ -934,50 +942,50 @@ error_logger:add_report_handler/1,2.
- Example: Add a handler to log debug events to file + Example: Add a handler to log info events to file

When starting an Erlang node, the default behaviour is that all - log events on level info or more severe, are logged to the - terminal via the default handler. To also log debug events, you - can either change the primary log level to debug:

+ log events on level notice or more severe, are logged to + the terminal via the default handler. To also log info events, + you can either change the primary log level to info:

-1> logger:set_primary_config(level, debug).
+1> logger:set_primary_config(level, info).
 ok

or set the level for one or a few modules only:

-2> logger:set_module_level(mymodule, debug).
+2> logger:set_module_level(mymodule, info).
 ok
-

This allows debug events to pass through to the default handler, - and be printed to the terminal as well. If there are many debug +

This allows info events to pass through to the default handler, + and be printed to the terminal as well. If there are many info events, it can be useful to print these to a file instead.

-

First, set the log level of the default handler to info, - preventing it from printing debug events to the terminal:

+

First, set the log level of the default handler + to notice, preventing it from printing info events to the + terminal:

-3> logger:set_handler_config(default, level, info).
+3> logger:set_handler_config(default, level, notice).
 ok

Then, add a new handler which prints to file. You can use the handler module logger_std_h, - and specify type {file,File}. The default handler level - is all, so you don't need to specify that:

+ and specify type {file,File}.:

-4> Config = #{config => #{type => {file,"./debug.log"}}}.
-#{config => #{type => {file,"./debug.log"}}}
-5> logger:add_handler(debugger, logger_std_h, Config).
+4> Config = #{config => #{type => {file,"./info.log"}}, level => info}.
+#{config => #{type => {file,"./info.log"}},level => info}
+5> logger:add_handler(myhandler, logger_std_h, Config).
 ok

Since filter_default defaults to log, this - handler now receives all log events. If you want debug events - only in the file, you must add a filter to stop all non-debug + handler now receives all log events. If you want info events + only in the file, you must add a filter to stop all non-info events. The built-in filter logger_filters:level/2 can do this:

-6> logger:add_handler_filter(debugger, stop_non_debug,
-                             {fun logger_filters:level/2, {stop, neq, debug}}).
+6> logger:add_handler_filter(myhandler, stop_non_info,
+                             {fun logger_filters:level/2, {stop, neq, info}}).
 ok

See section Filters for - more information about the filters and the filter_default - configuration parameter.

+ more information about the filters and the filter_default + configuration parameter.

@@ -1023,63 +1031,42 @@ ok

A simple handler that prints to the terminal can be implemented as follows:

--module(myhandler). +-module(myhandler1). -export([log/2]). -log(LogEvent, #{formatter := {FModule, FConfig}) -> +log(LogEvent, #{formatter := {FModule, FConfig}}) -> io:put_chars(FModule:format(LogEvent, FConfig)). -

A simple handler which prints to file can be implemented like - this:

- --module(myhandler). --export([adding_handler/1, removing_handler/1, log/2]). --export([init/1, handle_call/3, handle_cast/2, terminate/2]). - -adding_handler(Config) -> - {ok, Fd} = file:open(File, [append, {encoding, utf8}]), - {ok, Config#{myhandler_fd => Fd}}. - -removing_handler(#{myhandler_fd := Fd}) -> - _ = file:close(Fd), - ok. - -log(LogEvent,#{myhandler_fd := Fd, formatter := {FModule, FConfig}}) -> - io:put_chars(Fd, FModule:format(LogEvent, FConfig)). - - - -

The above handlers do not have any overload - protection, and all log events are printed directly from the - client process.

-

For information and examples of overload protection, please - refer to - section Protecting the - Handler from Overload, and the implementation - of logger_std_h - and logger_disk_log_h - .

- - -

Below is a simpler example of a handler which logs through one - single process.

+

Notice that the above handler does not have any overload + protection, and all log events are printed directly from the + client process.

+

For information and examples of overload protection, please + refer to + section Protecting the + Handler from Overload, and the implementation + of logger_std_h + and logger_disk_log_h + .

+

The following is a simpler example of a handler which logs to a + file through one single process:

--module(myhandler). +-module(myhandler2). -export([adding_handler/1, removing_handler/1, log/2]). -export([init/1, handle_call/3, handle_cast/2, terminate/2]). adding_handler(Config) -> - {ok, Pid} = gen_server:start(?MODULE, Config), - {ok, Config#{myhandler_pid => Pid}}. + MyConfig = maps:get(config,Config,#{file => "myhandler2.log"}), + {ok, Pid} = gen_server:start(?MODULE, MyConfig, []), + {ok, Config#{config => MyConfig#{pid => Pid}}}. -removing_handler(#{myhandler_pid := Pid}) -> +removing_handler(#{config := #{pid := Pid}}) -> gen_server:stop(Pid). -log(LogEvent,#{myhandler_pid := Pid} = Config) -> +log(LogEvent,#{config := #{pid := Pid}} = Config) -> gen_server:cast(Pid, {log, LogEvent, Config}). -init(#{myhandler_file := File}) -> +init(#{file := File}) -> {ok, Fd} = file:open(File, [append, {encoding, utf8}]), {ok, #{file => File, fd => Fd}}. @@ -1090,7 +1077,7 @@ handle_cast({log, LogEvent, Config}, #{fd := Fd} = State) -> do_log(Fd, LogEvent, Config), {noreply, State}. -terminate(Reason, #{fd := Fd}) -> +terminate(_Reason, #{fd := Fd}) -> _ = file:close(Fd), ok. -- cgit v1.2.3