[logger] Add API function for configuring logger proxy

2 files changed, 112 insertions, 4 deletions

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index e09c5db5e3..0668676096 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -245,6 +245,12 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
       </desc>
     </datatype>
     <datatype>
+      <name name="olp_config"/>
+      <desc>
+	<p></p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="primary_config"/>
       <desc>
 	<p>Primary configuration data for Logger. The following
@@ -597,8 +603,8 @@ start(_, []) ->
       <name name="get_config" arity="0" since="OTP 21.0"/>
       <fsummary>Look up the current Logger configuration</fsummary>
       <desc>
-        <p>Look up all current Logger configuration, including primary
-          and handler configuration, and module level settings.</p>
+        <p>Look up all current Logger configuration, including primary,
+          handler, and proxy configuration, and module level settings.</p>
       </desc>
     </func>
 
@@ -636,6 +642,17 @@ start(_, []) ->
     </func>
 
     <func>
+      <name name="get_proxy_config" arity="0" since="OTP 21.3"/>
+      <fsummary>Look up the current configuration for the Logger proxy.</fsummary>
+      <desc>
+        <p>Look up the current configuration for the Logger proxy.</p>
+	<p>For more information about the proxy, see
+	  section <seealso marker="logger_chapter#proxy">Logger
+	  Proxy</seealso> in the Kernel User's Guide.</p>
+      </desc>
+    </func>
+
+    <func>
       <name name="get_module_level" arity="0" since="OTP 21.0"/>
       <fsummary>Look up all current module levels.</fsummary>
       <desc>
@@ -801,6 +818,27 @@ start(_, []) ->
     </func>
 
     <func>
+      <name name="set_proxy_config" arity="1" since="OTP 21.3"/>
+      <fsummary>Set configuration data for the Logger proxy.</fsummary>
+      <desc>
+        <p>Set configuration data for the Logger proxy. This
+          overwrites the current proxy configuration. Keys that are not
+          specified in the <c><anno>Config</anno></c> map gets default
+          values.</p>
+	<p>To modify the existing configuration,
+	  use <seealso marker="#update_proxy_config-1">
+	    <c>update_proxy_config/1</c></seealso>, or, if a more
+	  complex merge is needed, read the current configuration
+	  with <seealso marker="#get_proxy_config-0"><c>get_proxy_config/0</c>
+	  </seealso>, then do the merge before writing the new
+	  configuration back with this function.</p>
+	<p>For more information about the proxy, see
+	  section <seealso marker="logger_chapter#proxy">Logger
+	  Proxy</seealso> in the Kernel User's Guide.</p>
+      </desc>
+    </func>
+
+    <func>
       <name name="set_module_level" arity="2" since="OTP 21.0"/>
       <fsummary>Set the log level for the specified modules.</fsummary>
       <desc>
@@ -1013,6 +1051,25 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
 	  </seealso>.</p>
       </desc>
     </func>
+
+    <func>
+      <name name="update_proxy_config" arity="1" since="OTP 21.3"/>
+      <fsummary>Update configuration data for the Logger proxy.</fsummary>
+      <desc>
+        <p>Update configuration data for the Logger proxy. This function
+          behaves as if it was implemented as follows:</p>
+	<code type="erl">
+Old = logger:get_proxy_config(),
+logger:set_proxy_config(maps:merge(Old, Config)).
+	</code>
+	<p>To overwrite the existing configuration without any merge,
+	  use <seealso marker="#set_proxy_config-1"><c>set_proxy_config/1</c>
+	  </seealso>.</p>
+	<p>For more information about the proxy, see
+	  section <seealso marker="logger_chapter#proxy">Logger
+	  Proxy</seealso> in the Kernel User's Guide.</p>
+      </desc>
+    </func>
   </funcs>
 
   <section>
diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 458e61cef5..5ed7397135 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -693,8 +693,10 @@ logger:debug(#{got => connection_request, id => Id, state => State},
 	  with <seealso marker="#logger_sasl_compatible">
 	    <c>logger_sasl_compatible</c></seealso>.</p>
 	<p>With this parameter, you can modify or disable the default
-	  handler, add custom handlers and primary logger filters, and
-	  set log levels per module.</p>
+	  handler, add custom handlers and primary logger filters, set
+	  log levels per module, and modify
+	  the <seealso marker="#proxy">proxy</seealso>
+	  configuration.</p>
 	<p><c>Config</c> is any (zero or more) of the following:</p>
 	<taglist>
           <tag><c>{handler, default, undefined}</c></tag>
@@ -746,6 +748,14 @@ logger:debug(#{got => connection_request, id => Id, state => State},
 	    <p>for each <c>Module</c>.</p>
 	    <p>Multiple entries of this type are allowed.</p>
 	  </item>
+	  <tag><c>{proxy, ProxyConfig}</c></tag>
+	  <item>
+	    <p>Sets the proxy configuration, equivalent to calling</p>
+	    <pre><seealso marker="logger#set_proxy_config/1">
+		logger:set_proxy_config(ProxyConfig)
+	    </seealso></pre>
+	    <p>Only one entry of this type is allowed.</p>
+	  </item>
 	</taglist>
 	<p>See
 	  section <seealso marker="#config_examples">Configuration
@@ -1334,9 +1344,50 @@ logger:add_handler(my_disk_log_h, logger_disk_log_h,
   </section>
 
   <section>
+    <marker id="proxy"/>
+    <title>Logger Proxy</title>
+    <p>The Logger proxy is an Erlang process which is part of the
+      Kernel application's supervision tree. During startup, the proxy
+      process registers itself as the <c>system_logger</c>, meaning
+      that log events produced by the emulator are sent to this
+      process.</p>
+    <p>When a log event is issued on a process which has its group
+      leader on a remote node, Logger automatically forwards the log
+      event to the group leader's node. To achieve this, it first
+      sends the log event as an Erlang message from the original
+      client process to the proxy on the local node, and the proxy in
+      turn forwards the event to the proxy on the remote node.</p>
+    <p>When receiving a log event, either from the emulator or from a
+      remote node, the proxy calls the Logger API to log the event.</p>
+    <p>The proxy process is overload protected in the same way as
+      described in
+      section <seealso marker="#overload_protection">Protecting the
+      Handler from Overload</seealso>, but with the following default
+      values:</p>
+    <code>
+    #{sync_mode_qlen => 500,
+      drop_mode_qlen => 1000,
+      flush_qlen => 5000,
+      burst_limit_enable => false,
+      overload_kill_enable => false}</code>
+    <p>For log events from the emulator, synchronous message passing
+      mode is not applicable, since all messages are passed
+      asynchronously by the emulator. Drop mode is achieved by setting
+      the <c>system_logger</c> to <c>undefined</c>, forcing the
+      emulator to drop events until it is set back to the proxy pid
+      again.</p>
+    <p>The proxy uses <seealso marker="erts:erlang#send_nosuspend/2">
+	<c>erlang:send_nosuspend/2</c></seealso> when sending log
+      events to a remote node. If the message could not be sent
+      without suspending the sender, it is dropped. This is to avoid
+      blocking the proxy process.</p>
+  </section>
+
+  <section>
     <title>See Also</title>
     <p>
       <seealso marker="disk_log"><c>disk_log(3)</c></seealso>,
+      <seealso marker="erts:erlang"><c>erlang(3)</c></seealso>,
       <seealso marker="error_logger"><c>error_logger(3)</c></seealso>,
       <seealso marker="logger"><c>logger(3)</c></seealso>,
       <seealso marker="logger_disk_log_h"><c>logger_disk_log_h(3)</c></seealso>,