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