Merge pull request #1975 from sirihansen/siri/logger/config-set-or-update

Forward set/update indicator to handler callback changing_config
OTP-15364

4 files changed, 119 insertions, 17 deletions

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 464c65ba76..2bcf137299 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -748,6 +748,14 @@ start(_, []) ->
           exists, its associated value will be changed
           to the given value. If it does not exist, it will
           be added.</p>
+	<p>If the value is incomplete, which for example can be the
+	  case for the <c>config</c> key, it is up to the handler
+	  implementation how the unspecified parts are set. For all
+	  handlers in the Kernel application, unspecified data for
+	  the <c>config</c> key is set to default values. To update
+	  only specified data, and keep the existing configuration for
+	  the rest, use <seealso marker="#update_handler_config-3">
+	    <c>update_handler_config/3</c></seealso>.</p>
 	<p>See the definition of
 	  the <seealso marker="#type-handler_config">
 	    <c>handler_config()</c></seealso> type for more
@@ -933,6 +941,42 @@ logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
     </func>
 
     <func>
+      <name name="update_handler_config" arity="3" clause_i="1"/>
+      <name name="update_handler_config" arity="3" clause_i="2"/>
+      <name name="update_handler_config" arity="3" clause_i="3"/>
+      <name name="update_handler_config" arity="3" clause_i="4"/>
+      <name name="update_handler_config" arity="3" clause_i="5"/>
+      <fsummary>Add or update configuration data for the specified
+        handler.</fsummary>
+      <type variable="HandlerId"/>
+      <type variable="Level" name_i="1"/>
+      <type variable="FilterDefault" name_i="2"/>
+      <type variable="Filters" name_i="3"/>
+      <type variable="Formatter" name_i="4"/>
+      <type variable="Config" name_i="5"/>
+      <type variable="Return"/>
+      <desc>
+        <p>Add or update configuration data for the specified
+          handler. If the given <c><anno>Key</anno></c> already
+          exists, its associated value will be changed
+          to the given value. If it does not exist, it will
+          be added.</p>
+	<p>If the value is incomplete, which for example can be the
+	  case for the <c>config</c> key, it is up to the handler
+	  implementation how the unspecified parts are set. For all
+	  handlers in the Kernel application, unspecified data for
+	  the <c>config</c> key is not changed. To reset unspecified
+	  data to default values,
+	  use <seealso marker="#set_handler_config-3">
+	    <c>set_handler_config/3</c></seealso>.</p>
+	<p>See the definition of
+	  the <seealso marker="#type-handler_config">
+	    <c>handler_config()</c></seealso> type for more
+	  information about the different parameters.</p>
+      </desc>
+    </func>
+
+    <func>
       <name name="update_primary_config" arity="1"/>
       <fsummary>Update primary configuration data for Logger.</fsummary>
       <desc>
@@ -1041,10 +1085,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
     </func>
 
     <func>
-      <name>HModule:changing_config(Config1, Config2) -> {ok, Config3} | {error, Reason}</name>
+      <name>HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Config} | {error, Reason}</name>
       <fsummary>The configuration for this handler is about to change.</fsummary>
       <type>
-	<v>Config1 = Config2 = Config3 =
+	<v>SetOrUpdate = set | update</v>
+	<v>OldConfig = NewConfig = Config =
 	  <seealso marker="#type-handler_config">handler_config()</seealso></v>
 	<v>Reason = term()</v>
       </type>
@@ -1053,18 +1098,51 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
 	<p>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.</p>
-	<p><c>Config1</c> is the existing configuration
-	  and <c>Config2</c> is the new configuration.</p>
+	<p><c>OldConfig</c> is the existing configuration
+	  and <c>NewConfig</c> is the new configuration.</p>
 	<p>The handler identity is associated with the <c>id</c> key
-	  in <c>Config1</c>.</p>
+	  in <c>OldConfig</c>.</p>
+	<p><c>SetOrUpdate</c> has the value <c>set</c> if the
+	  configuration change originates from a call to
+	  <seealso marker="#set_handler_config-2">
+	    <c>set_handler_config/2,3</c></seealso>, and <c>update</c>
+	  if it originates from <seealso marker="#update_handler_config-2">
+	    <c>update_handler_config/2,3</c></seealso>. The handler can
+	  use this parameteter to decide how to update the value of
+	  the <c>config</c> field, that is, the handler specific
+	  configuration data. Typically, if <c>SetOrUpdate</c>
+	  equals <c>set</c>, values that are not specified must be
+	  given their default values. If <c>SetOrUpdate</c>
+	  equals <c>update</c>, the values found in <c>OldConfig</c>
+	  must be used instead.</p>
 	<p>If everything succeeds, the callback function must return a
-	  possibly adjusted configuration in <c>{ok,Config3}</c>.</p>
+	  possibly adjusted configuration in <c>{ok,Config}</c>.</p>
 	<p>If the configuration is faulty, the callback function must
 	  return <c>{error,Reason}</c>.</p>
       </desc>
     </func>
 
     <func>
+      <name>HModule:filter_config(Config) -> FilteredConfig</name>
+      <fsummary>Remove internal data from configuration.</fsummary>
+      <type>
+	<v>Config = FilteredConfig =
+	  <seealso marker="#type-handler_config">handler_config()</seealso></v>
+      </type>
+      <desc>
+	<p>This callback function is optional.</p>
+	<p>The function is called when one of the Logger API functions
+	  for fetching the handler configuration is called, for
+	  example
+	  <seealso marker="#get_handler_config-1">
+	    <c>logger:get_handler_config/1</c></seealso>.</p>
+	<p>It allows the handler to remove internal data fields from
+	  its configuration data before it is returned to the
+	  caller.</p>
+      </desc>
+    </func>
+
+    <func>
       <name>HModule:log(LogEvent, Config) -> void()</name>
       <fsummary>Log the given log event.</fsummary>
       <type>
@@ -1136,7 +1214,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
 	  <item><seealso marker="logger#set_handler_config-2">
 	      <c>logger:set_handler_config/2,3</c></seealso></item>
 	  <item><seealso marker="logger#update_handler_config-2">
-	      <c>logger:updata_handler_config/2</c></seealso></item>
+	      <c>logger:updata_handler_config/2,3</c></seealso></item>
 	  <item><seealso marker="logger#update_formatter_config-2">
 	      <c>logger:update_formatter_config/2</c></seealso></item>
 	</list>
diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 4a81cfa34a..1870d2ab79 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -384,8 +384,8 @@ logger:debug(#{got => connection_request, id => Id, state => State},
 
     <p>In addition to the mandatory callback function <c>log/2</c>, a
       handler module can export the optional callback
-      functions <c>adding_handler/1</c>, <c>changing_config/2</c>
-      and <c>removing_handler/1</c>. See
+      functions <c>adding_handler/1</c>, <c>changing_config/3</c>,
+      <c>filter_config/1</c>, and <c>removing_handler/1</c>. See
       section <seealso marker="logger#handler_callback_functions">Handler
       Callback Functions</seealso> in the logger(3) manual page for
       more information about these function.</p>
@@ -555,7 +555,7 @@ logger:debug(#{got => connection_request, id => Id, state => State},
 	<item><seealso marker="logger#set_handler_config-2">
 	    <c>set_handler_config/2,3</c></seealso></item>
 	<item><seealso marker="logger#update_handler_config-2">
-	    <c>update_handler_config/2</c></seealso></item>
+	    <c>update_handler_config/2,3</c></seealso></item>
 	<item><seealso marker="logger#add_handler_filter-3">
 	    <c>add_handler_filter/3</c></seealso></item>
 	<item><seealso marker="logger#remove_handler_filter-2">
@@ -704,9 +704,13 @@ logger:debug(#{got => connection_request, id => Id, state => State},
           <item>
 	    <p>If <c>HandlerId</c> is <c>default</c>, then this entry
 	      modifies the default handler, equivalent to calling</p>
-	    <pre><seealso marker="logger#set_handler_config-2">
-		logger:set_handler_config(default, Module, HandlerConfig)
-	      </seealso></pre>
+	    <pre><seealso marker="logger#remove_handler-1">
+		logger:remove_handler(default)
+	    </seealso></pre>
+	    <p>followed by</p>
+	    <pre><seealso marker="logger#add_handler-3">
+		logger:add_handler(default, Module, HandlerConfig)
+	    </seealso></pre>
 	    <p>For all other values of <c>HandlerId</c>, this entry
 	      adds a new handler, equivalent to calling</p>
 	    <pre><seealso marker="logger:add_handler/3">
@@ -1024,7 +1028,8 @@ ok</pre>
     <list>
       <item><c>adding_handler(Config)</c></item>
       <item><c>removing_handler(Config)</c></item>
-      <item><c>changing_config(OldConfig, NewConfig)</c></item>
+      <item><c>changing_config(SetOrUpdate, OldConfig, NewConfig)</c></item>
+      <item><c>filter_config(Config)</c></item>
     </list>
     <p>When a handler is added, by for example a call
       to <seealso marker="logger#add_handler-3">
@@ -1043,11 +1048,18 @@ ok</pre>
     <p>When <seealso marker="logger#set_handler_config-2">
 	<c>logger:set_handler_config/2,3</c></seealso>
       or <seealso marker="logger#update_handler_config/2">
-	<c>logger:update_handler_config/2</c></seealso> is called,
+	<c>logger:update_handler_config/2,3</c></seealso> is called,
       Logger
-      calls <c>HModule:changing_config(OldConfig, NewConfig)</c>. If
+      calls <c>HModule:changing_config(SetOrUpdate, OldConfig, NewConfig)</c>. If
       this function returns <c>{ok,NewConfig1}</c>, Logger
       writes <c>NewConfig1</c> to the configuration database.</p>
+    <p>When <seealso marker="logger#get_config-0">
+	<c>logger:get_config/0</c></seealso> or
+      <seealso marker="logger#get_handler_config-0">
+	<c>logger:get_handler_config/0,1</c></seealso> is called,
+      Logger calls <c>HModule:filter_config(Config)</c>. This function
+      must return the handler configuration where internal data is
+      removed.</p>
 
     <p>A simple handler that prints to the terminal can be implemented
       as follows:</p>
diff --git a/lib/kernel/doc/src/logger_disk_log_h.xml b/lib/kernel/doc/src/logger_disk_log_h.xml
index dfe2ab3275..d9b941a0a9 100644
--- a/lib/kernel/doc/src/logger_disk_log_h.xml
+++ b/lib/kernel/doc/src/logger_disk_log_h.xml
@@ -66,6 +66,10 @@
 	corresponds to the <c>name</c> property in the
 	<seealso marker="disk_log#open-1"><c>dlog_option()</c></seealso>
 	datatype.</p>
+	<p>The value is set when the handler is added, and it can not
+	  be changed in runtime.</p>
+	<p>Defaults to the same name as the handler identity, in the
+	  current directory.</p>
       </item>
       <tag><c>type</c></tag>
       <item>
@@ -73,6 +77,8 @@
 	corresponds to the <c>type</c> property in the
 	<seealso marker="disk_log#open-1"><c>dlog_option()</c></seealso>
 	datatype.</p>
+	<p>The value is set when the handler is added, and it can not
+	  be changed in runtime.</p>
 	<p>Defaults to <c>wrap</c>.</p>
       </item>
       <tag><c>max_no_files</c></tag>
@@ -82,6 +88,8 @@
 	corresponds to the <c>MaxNoFiles</c> element in the <c>size</c> property in the
 	<seealso marker="disk_log#open-1"><c>dlog_option()</c></seealso>
 	datatype.</p>
+	<p>The value is set when the handler is added, and it can not
+	  be changed in runtime.</p>
 	<p>Defaults to <c>10</c>.</p>
 	<p>The setting has no effect on a halt log.</p>
       </item>
@@ -93,6 +101,8 @@
 	corresponds to the <c>MaxNoBytes</c> element in the <c>size</c> property in the
 	<seealso marker="disk_log#open-1"><c>dlog_option()</c></seealso>
 	datatype.</p>
+	<p>The value is set when the handler is added, and it can not
+	  be changed in runtime.</p>
 	<p>Defaults to <c>1048576</c> bytes for a wrap log, and
 	<c>infinity</c> for a halt log.</p>
       </item>
diff --git a/lib/kernel/doc/src/logger_std_h.xml b/lib/kernel/doc/src/logger_std_h.xml
index fcd8189bae..e156f5719b 100644
--- a/lib/kernel/doc/src/logger_std_h.xml
+++ b/lib/kernel/doc/src/logger_std_h.xml
@@ -74,7 +74,9 @@
 	  circular logging. Use the disk_log handler,
 	  <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso>,
 	  for this.</p>
-	<p> Defaults to <c>standard_io</c>.</p>
+	<p>The value is set when the handler is added, and it can not
+	  be changed in runtime.</p>
+	<p>Defaults to <c>standard_io</c>.</p>
       </item>
       <tag><c>filesync_repeat_interval</c></tag>
       <item>