Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:Ledest:erlang
erlang
3744-kernel-Add-callback-attributes-for-logger-...
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File 3744-kernel-Add-callback-attributes-for-logger-handler-an.patch of Package erlang
From d4960c6c8a1419ad54bcb8ffa8a9e25c1d028903 Mon Sep 17 00:00:00 2001 From: Lukas Larsson <lukas@erlang.org> Date: Wed, 27 Sep 2023 16:50:23 +0200 Subject: [PATCH 04/10] kernel: Add callback attributes for logger handler and formatter --- lib/kernel/doc/src/logger.xml | 76 ++----------------------- lib/kernel/doc/src/logger_chapter.xml | 10 ++-- lib/kernel/doc/src/logger_formatter.xml | 64 +++++++++++++++++++++ lib/kernel/src/logger.erl | 25 ++++++++ lib/kernel/src/logger_formatter.erl | 11 ++++ 5 files changed, 110 insertions(+), 76 deletions(-) diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index 647c970b10..0c2a963e6e 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -1213,7 +1213,7 @@ logger:set_proxy_config(maps:merge(Old, Config)). callback module.</p> </fsdescription> <func> - <name since="OTP 21.0">HModule:adding_handler(Config1) -> {ok, Config2} | {error, + <name since="OTP 21.0">Module:adding_handler(Config1) -> {ok, Config2} | {error, Reason}</name> <fsummary>An instance of this handler is about to be added.</fsummary> <type> @@ -1239,7 +1239,7 @@ logger:set_proxy_config(maps:merge(Old, Config)). </func> <func> - <name since="OTP 21.2">HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Config} | {error, Reason}</name> + <name since="OTP 21.2">Module:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Config} | {error, Reason}</name> <fsummary>The configuration for this handler is about to change.</fsummary> <type> <v>SetOrUpdate = set | update</v> @@ -1277,7 +1277,7 @@ logger:set_proxy_config(maps:merge(Old, Config)). </func> <func> - <name since="OTP 21.2">HModule:filter_config(Config) -> FilteredConfig</name> + <name since="OTP 21.2">Module:filter_config(Config) -> FilteredConfig</name> <fsummary>Remove internal data from configuration.</fsummary> <type> <v>Config = FilteredConfig = @@ -1297,7 +1297,7 @@ logger:set_proxy_config(maps:merge(Old, Config)). </func> <func> - <name since="OTP 21.0">HModule:log(LogEvent, Config) -> void()</name> + <name since="OTP 21.0">Module:log(LogEvent, Config) -> void()</name> <fsummary>Log the given log event.</fsummary> <type> <v>LogEvent = @@ -1320,7 +1320,7 @@ logger:set_proxy_config(maps:merge(Old, Config)). </func> <func> - <name since="OTP 21.0">HModule:removing_handler(Config) -> ok</name> + <name since="OTP 21.0">Module:removing_handler(Config) -> ok</name> <fsummary>The given handler is about to be removed.</fsummary> <type> <v>Config = @@ -1339,72 +1339,6 @@ logger:set_proxy_config(maps:merge(Old, Config)). </funcs> - - - <funcs> - <fsdescription> - <marker id="formatter_callback_functions"/> - <title>Formatter Callback Functions</title> - <p>The following functions are to be exported from a formatter - callback module.</p> - </fsdescription> - <func> - <name since="OTP 21.0">FModule:check_config(FConfig) -> ok | {error, Reason}</name> - <fsummary>Validate the given formatter configuration.</fsummary> - <type> - <v>FConfig = - <seetype marker="#formatter_config">formatter_config()</seetype></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,Reason}</c> if it is faulty.</p> - <p>The following Logger API functions can trigger this callback:</p> - <list> - <item><seemfa marker="logger#add_handler/3"> - <c>logger:add_handler/3</c></seemfa></item> - <item><seemfa marker="logger#set_handler_config/2"> - <c>logger:set_handler_config/2,3</c></seemfa></item> - <item><seemfa marker="logger#update_handler_config/2"> - <c>logger:update_handler_config/2,3</c></seemfa></item> - <item><seemfa marker="logger#update_formatter_config/2"> - <c>logger:update_formatter_config/2</c></seemfa></item> - </list> - <p>See <seeerl marker="logger_formatter"> - <c>logger_formatter(3)</c></seeerl> - for an example implementation. <c>logger_formatter</c> is the - default formatter used by Logger.</p> - </desc> - </func> - <func> - <name since="OTP 21.0">FModule:format(LogEvent, FConfig) -> FormattedLogEntry</name> - <fsummary>Format the given log event.</fsummary> - <type> - <v>LogEvent = - <seetype marker="#log_event">log_event()</seetype></v> - <v>FConfig = - <seetype marker="#formatter_config">formatter_config()</seetype></v> - <v>FormattedLogEntry = - <seetype marker="unicode#chardata">unicode:chardata()</seetype></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 <seemfa marker="stdlib:io#put_chars/1"> - <c>io:put_chars/1,2</c></seemfa>.</p> - <p>See <seeerl marker="logger_formatter"> - <c>logger_formatter(3)</c></seeerl> - for an example implementation. <c>logger_formatter</c> is the - default formatter used by Logger.</p> - </desc> - </func> - </funcs> - <section> <title>See Also</title> <p> diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml index 39308fcbdd..d35cef3465 100644 --- a/lib/kernel/doc/src/logger_chapter.xml +++ b/lib/kernel/doc/src/logger_chapter.xml @@ -390,7 +390,7 @@ logger:debug(#{got => connection_request, id => Id, state => State}, <p>A handler is defined as a module exporting at least the following callback function:</p> - <pre><seemfa marker="logger#HModule:log/2">log(LogEvent, Config) -> void()</seemfa></pre> + <pre><seemfa marker="logger#Module:log/2">log(LogEvent, Config) -> void()</seemfa></pre> <p>This function is called when a log event has passed through all primary filters, and all handler filters attached to the handler @@ -453,25 +453,25 @@ logger:debug(#{got => connection_request, id => Id, state => State}, handler's destination. The handler callback receives the formatter information as part of the handler configuration, which is passed as the second argument - to <seemfa marker="logger#HModule:log/2"> + to <seemfa marker="logger#Module:log/2"> <c>HModule:log/2</c></seemfa>.</p> <p>The formatter information consist of a formatter module, <c>FModule</c> and its configuration, <c>FConfig</c>. <c>FModule</c> must export the following function, which can be called by the handler:</p> - <pre><seemfa marker="logger#FModule:format/2">format(LogEvent,FConfig) + <pre><seemfa marker="logger_formatter#Module:format/2">format(LogEvent,FConfig) -> FormattedLogEntry</seemfa></pre> <p>The formatter information for a handler is set as a part of its configuration when the handler is added. It can also be changed during runtime with <seemfa marker="logger#set_handler_config/3"> - <c>logger:set_handler_config(HandlerId,formatter,{FModule,FConfig})</c> + <c>logger:set_handler_config(HandlerId,formatter,{Module,FConfig})</c> </seemfa>, which overwrites the current formatter information, or with <seemfa marker="logger#update_formatter_config/2"> <c>logger:update_formatter_config/2,3</c></seemfa>, which only modifies the formatter configuration.</p> <p>If the formatter module exports the optional callback - function <seemfa marker="logger#FModule:check_config/1"> + function <seemfa marker="logger_formatter#Module:check_config/1"> <c>check_config(FConfig)</c></seemfa>, Logger calls this function when the formatter information is set or modified, to verify the validity of the formatter configuration.</p> diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml index 527d2d0364..d8611c62e9 100644 --- a/lib/kernel/doc/src/logger_formatter.xml +++ b/lib/kernel/doc/src/logger_formatter.xml @@ -336,6 +336,70 @@ exit_reason: "It crashed"</code> </func> </funcs> + <funcs> + <fsdescription> + <marker id="formatter_callback_functions"/> + <title>Formatter Callback Functions</title> + <p>The following functions are to be exported from a formatter + callback module.</p> + </fsdescription> + <func> + <name since="OTP 21.0">Module:check_config(FConfig) -> ok | {error, Reason}</name> + <fsummary>Validate the given formatter configuration.</fsummary> + <type> + <v>FConfig = + <seetype marker="logger#formatter_config">formatter_config()</seetype></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,Reason}</c> if it is faulty.</p> + <p>The following Logger API functions can trigger this callback:</p> + <list> + <item><seemfa marker="logger#add_handler/3"> + <c>logger:add_handler/3</c></seemfa></item> + <item><seemfa marker="logger#set_handler_config/2"> + <c>logger:set_handler_config/2,3</c></seemfa></item> + <item><seemfa marker="logger#update_handler_config/2"> + <c>logger:update_handler_config/2,3</c></seemfa></item> + <item><seemfa marker="logger#update_formatter_config/2"> + <c>logger:update_formatter_config/2</c></seemfa></item> + </list> + <p>See <seeerl marker="logger_formatter"> + <c>logger_formatter(3)</c></seeerl> + for an example implementation. <c>logger_formatter</c> is the + default formatter used by Logger.</p> + </desc> + </func> + <func> + <name since="OTP 21.0">Module:format(LogEvent, FConfig) -> FormattedLogEntry</name> + <fsummary>Format the given log event.</fsummary> + <type> + <v>LogEvent = + <seetype marker="logger#log_event">log_event()</seetype></v> + <v>FConfig = + <seetype marker="logger#formatter_config">formatter_config()</seetype></v> + <v>FormattedLogEntry = + <seetype marker="unicode#chardata">unicode:chardata()</seetype></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 <seemfa marker="stdlib:io#put_chars/1"> + <c>io:put_chars/1,2</c></seemfa>.</p> + <p>See <seeerl marker="logger_formatter"> + <c>logger_formatter(3)</c></seeerl> + for an example implementation. <c>logger_formatter</c> is the + default formatter used by Logger.</p> + </desc> + </func> + </funcs> + <section> <title>See Also</title> <p> diff --git a/lib/kernel/src/logger.erl b/lib/kernel/src/logger.erl index 73a86dd3ca..83f7aeba2a 100644 --- a/lib/kernel/src/logger.erl +++ b/lib/kernel/src/logger.erl @@ -161,6 +161,31 @@ olp_config/0, timestamp/0]). +%%%----------------------------------------------------------------- +%%% Callbacks +-callback adding_handler(Config1) -> {ok, Config2} | {error, Reason} when + Config1 :: handler_config(), + Config2 :: handler_config(), + Reason :: term(). + +-callback changing_config(SetOrUpdate, OldConfig, NewConfig) -> + {ok, Config} | {error, Reason} when + SetOrUpdate :: set | update, + OldConfig :: handler_config(), + NewConfig :: handler_config(), + Config :: handler_config(), + Reason :: term(). + +-callback filter_config(Config) -> FilteredConfig when + Config :: handler_config(), + FilteredConfig :: handler_config(). + +-callback log(LogEvent, Config) -> term() when + LogEvent :: log_event(), Config :: handler_config(). + +-callback removing_handler(Config) -> ok when + Config :: handler_config(). + %%%----------------------------------------------------------------- %%% API diff --git a/lib/kernel/src/logger_formatter.erl b/lib/kernel/src/logger_formatter.erl index 75d85de744..1e71eced41 100644 --- a/lib/kernel/src/logger_formatter.erl +++ b/lib/kernel/src/logger_formatter.erl @@ -38,6 +38,17 @@ -type template() :: [metakey() | {metakey(),template(),template()} | unicode:chardata()]. -type metakey() :: atom() | [atom()]. +%%%----------------------------------------------------------------- +%%% Callbacks +-callback check_config(FConfig) -> ok | {error, Reason} when + FConfig :: logger:formatter_config(), + Reason :: term(). + +-callback format(LogEvent, FConfig) -> FormattedLogEntry when + LogEvent :: logger:log_event(), + FConfig :: logger:formatter_config(), + FormattedLogEntry :: unicode:chardata(). + %%%----------------------------------------------------------------- %%% API -spec format(LogEvent,Config) -> unicode:chardata() when -- 2.35.3
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
