File 1984-kernel-Add-callback-attributes-for-logger-... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 1984-kernel-Add-callback-attributes-for-logger-handler-an.patch of Package erlang (Revision 2f15b05a39d64e5cba90e927e8665465)

Currently displaying revision 2f15b05a39d64e5cba90e927e8665465 , Show latest

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.
 </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>
- The following functions are to be exported from a formatter
- callback module.
- </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>
-	This callback function is optional.
-	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.
-	The following Logger API functions can trigger this callback:
-	<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>
-	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.
- </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>
-	This callback function is mandatory.
-	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>.
-	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.
- </desc>
- </func>
- </funcs>
-
 <section>
 <title>See Also</title>
 
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},
 A handler is defined as a module exporting at least the
 following callback function:
 
- <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>
 
 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>.
 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:
- <pre><seemfa marker="logger#FModule:format/2">format(LogEvent,FConfig)
+ <pre><seemfa marker="logger_formatter#Module:format/2">format(LogEvent,FConfig)
 	-> FormattedLogEntry</seemfa></pre>
 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.
 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.
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>
+ The following functions are to be exported from a formatter
+ callback module.
+ </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>
+	This callback function is optional.
+	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.
+	The following Logger API functions can trigger this callback:
+	<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>
+	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.
+ </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>
+	This callback function is mandatory.
+	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>.
+	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.
+ </desc>
+ </func>
+ </funcs>
+
 <section>
 <title>See Also</title>
 
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

Places

File 1984-kernel-Add-callback-attributes-for-logger-handler-an.patch of Package erlang (Revision 2f15b05a39d64e5cba90e927e8665465)

Places