File 4744-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
