[logger] Correct documentation

1 files changed, 67 insertions, 61 deletions

diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 5eab48f63e..a4951022bb 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -97,6 +97,7 @@
       defined.</p>
   </section>
   <section>
+    <marker id="logger_api"/>
     <title>Logger API</title>
     <p>The API for logging consists of a set
       of <seealso marker="logger#macros">macros</seealso>, and a set
@@ -1107,7 +1108,7 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) ->
     <c>logger_std_h</c></seealso> and <seealso marker="logger_disk_log_h">
     <c>logger_disk_log_h</c></seealso>, feature an overload protection
     mechanism, which makes it possible for the handlers to survive,
-    and stay responsive, during periods of high load (i.e. when huge
+    and stay responsive, during periods of high load (when huge
     numbers of incoming log requests must be handled).
     The mechanism works as follows:</p>
     
@@ -1127,47 +1128,49 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) ->
 	<item>
 	  <p>As long as the length of the message queue is lower than this
 	  value, all log events are handled asynchronously. This means that
-	  the process sending the log event, by calling a log function in the
-	  Logger API, does not wait for a response from the handler, but
-	  continues executing immediately after the event is sent (that is, it
-	  is not affected by the time it takes the handler to print the event
-	  to the log device). If the message queue grows larger than this value,
+	  the client process sending the log event, by calling a log function
+	  in the <seealso marker="logger_chapter#logger_api">Logger API</seealso>,
+	  does not wait for a response from the handler but continues
+	  executing immediately after the event is sent. It is not affected
+	  by the time it takes the handler to print the event to the log
+	  device. If the message queue grows larger than this value,
 	  the handler starts handling log events synchronously instead,
-	  meaning that the process sending the event, must wait for a
+	  meaning that the client process sending the event must wait for a
 	  response. When the handler reduces the message queue to a
 	  level below the <c>sync_mode_qlen</c> threshold, asynchronous
 	  operation is resumed. The switch from asynchronous to synchronous
 	  mode can slow down the logging tempo of one, or a few, busy senders,
 	  but cannot protect the handler sufficiently in a situation of many
 	  busy concurrent senders.</p>
-	  <p>Default value of the threshold: <c>10</c> messages.</p>
+	  <p>Defaults to <c>10</c> messages.</p>
 	</item>
 	<tag><c>drop_mode_qlen</c></tag>
 	<item>
 	  <p>When the message queue grows larger than this threshold, the
 	  handler switches to a mode in which it drops all new events that
-	  senders want to send. Dropping an event in ths mode, means that the
-	  log function never sends a message to the handler, but returns
-	  without taking any action. The handler keeps logging events already
-	  in the message queue, and when the length of the message queue is
-	  reduced to a level below the threshold, synchronous or asynchronous
-	  mode is resumed. Note that when the handler activates, or deactivates,
-	  drop mode, information about it is printed to the log.</p>
-	  <p>Default value of the threshold: <c>200</c> messages.</p>
+	  senders want to log. Dropping an event in this mode means that the
+	  call to the log function never results in a message being sent to
+	  the handler, but the function returns without taking any action.
+	  The handler keeps logging the events that are already in its message
+	  queue, and when the length of the message queue is reduced to a level
+	  below the threshold, synchronous or asynchronous mode is resumed.
+	  Notice that when the handler activates or deactivates drop mode,
+	  information about it is printed in the log.</p>
+	  <p>Defaults to <c>200</c> messages.</p>
 	</item>
 	<tag><c>flush_qlen</c></tag>
 	<item>
 	  <p>If the length of the message queue grows larger than this threshold,
-	  a flush (delete) operation takes place. To flush events, the handler receives
-	  the messages in the process mailbox in a loop without logging (that is, the
-	  handler deletes the events). Processes waiting for a response from a
-	  synchronous log request will receive a reply from the handler indicating
-	  that the request has been dropped. The handler process will set its own priority
-	  to high during the flush loop to make sure that no new events come in
-	  during the operation. Note that after the flush operation is performed,
-	  the handler prints information in the log about how many events have been
-	  deleted</p>
-	  <p>Default value of the threshold: <c>1000</c> messages.</p>
+	  a flush (delete) operation takes place. To flush events, the handler
+	  discards the messages in the message queue by receiving them in a
+	  loop without logging. Client processes waiting for a response from a
+	  synchronous log request receive a reply from the handler indicating
+	  that the request is dropped. The handler process increases its
+	  priority during the flush loop to make sure that no new events
+	  are received during the operation. Notice that after the flush operation
+	  is performed, the handler prints information in the log about how many
+	  events have been deleted.</p>
+	  <p>Defaults to <c>1000</c> messages.</p>
 	</item>
       </taglist>
 
@@ -1186,15 +1189,15 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) ->
 	synchronously. That is, asynchronous logging is disabled.</item>
 	<item>If <c>sync_mode_qlen</c> is set to the same value as
 	<c>drop_mode_qlen</c>, synchronous mode is disabled. That is, the handler
-	always runs in asychronous mode, unless dropping or flushing is invoked.</item>
+	always runs in asynchronous mode, unless dropping or flushing is invoked.</item>
 	<item>If <c>drop_mode_qlen</c> is set to the same value as <c>flush_qlen</c>,
 	drop mode is disabled and can never occur.</item>
       </list>
 
       <p>During high load scenarios, the length of the handler message queue
       rarely grows in a linear and predictable way. Instead, whenever the
-      handler process gets scheduled in, it can have an almost arbitrary number
-      of messages waiting in the mailbox. It's for this reason that the overload
+      handler process is scheduled in, it can have an almost arbitrary number
+      of messages waiting in the message queue. It is for this reason that the overload
       protection mechanism is focused on acting quickly, and quite drastically,
       such as immediately dropping or flushing messages, when a large queue length
       is detected.</p>
@@ -1202,38 +1205,36 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) ->
       <p>The values of the previously listed thresholds can be specified by the user.
       This way, a handler can be configured to, for example, not drop or flush
       messages unless the message queue length of the handler process grows extremely
-      large. Note that large amounts of memory can be required for the node under such
+      large. Notice that large amounts of memory can be required for the node under such
       circumstances. Another example of user configuration is when, for performance
-      reasons, the logging processes must never get blocked by synchronous log requests.
-      It's possible, perhaps, that dropping or flushing events is still acceptable (since
-      it does not affect the performance of the processes sending the log events).</p>
+      reasons, the client processes must never be blocked by synchronous log requests.
+      It is possible, perhaps, that dropping or flushing events is still acceptable, since
+      it does not affect the performance of the client processes sending the log events.</p>
 
       <p>A configuration example:</p>
       <code type="none">
 logger:add_handler(my_standard_h, logger_std_h,
-                   #{config =>
-                         #{type => {file,"./system_info.log"},
-                           sync_mode_qlen => 100,
-                           drop_mode_qlen => 1000,
-                           flush_qlen => 2000}}).
+                   #{config => #{type => {file,"./system_info.log"},
+                                 sync_mode_qlen => 100,
+                                 drop_mode_qlen => 1000,
+                                 flush_qlen => 2000}}).
     </code>
     </section>
 
     <section>
       <title>Controlling Bursts of Log Requests</title>
-      <p>Large bursts of log events (that is, many events received by the handler
-      under a short period of time), can potentially cause problems, such as:</p>
+      <p>Large bursts of log events - many events received by the handler
+      under a short period of time - can potentially cause problems, such as:</p>
       <list>
 	<item>Log files grow very large, very quickly.</item>
-	<item>Circular logs wrap too quickly so that important data gets overwritten.</item>
+	<item>Circular logs wrap too quickly so that important data is overwritten.</item>
 	<item>Write buffers grow large, which slows down file sync operations.</item>
       </list>
 
       <p>For this reason, both built-in handlers offer the possibility to specify the
       maximum number of events to be handled within a certain time frame.
       With this burst control feature enabled, the handler can avoid choking the log with
-      massive amounts of printouts. These are the configuration parameters:</p>
-      
+      massive amounts of printouts. The configuration parameters are:</p>
       <taglist>
 	<tag><c>burst_limit_enable</c></tag>
 	<item>
@@ -1243,13 +1244,13 @@ logger:add_handler(my_standard_h, logger_std_h,
 	<tag><c>burst_limit_max_count</c></tag>
 	<item>
 	  <p>This is the maximum number of events to handle within a
-	  <c>burst_limit_window_time</c> time frame. After the limit has been
-	  reached, successive events get dropped until the end of the time frame.</p>
+	  <c>burst_limit_window_time</c> time frame. After the limit is
+	  reached, successive events are dropped until the end of the time frame.</p>
 	  <p>Defaults to <c>500</c> events.</p>
 	</item>
 	<tag><c>burst_limit_window_time</c></tag>
 	<item>
-	  <p>See the previous description of <c>burst_limit_window_time</c>.</p>
+	  <p>See the previous description of <c>burst_limit_max_count</c>.</p>
 	  <p>Defaults to <c>1000</c> milliseconds.</p>
 	</item>
       </taglist>
@@ -1257,11 +1258,10 @@ logger:add_handler(my_standard_h, logger_std_h,
       <p>A configuration example:</p>
       <code type="none">
 logger:add_handler(my_disk_log_h, logger_disk_log_h,
-                   #{config =>
-                         #{file => "./my_disk_log",
-                           burst_limit_enable => true,
-                           burst_limit_max_count => 20,
-                           burst_limit_window_time => 500}}).
+                   #{config => #{file => "./my_disk_log",
+                                 burst_limit_enable => true,
+                                 burst_limit_max_count => 20,
+                                 burst_limit_window_time => 500}}).
     </code>
     </section>
 
@@ -1271,7 +1271,7 @@ logger:add_handler(my_disk_log_h, logger_disk_log_h,
       of high load without crashing, can build up a large message queue, or use a
       large amount of memory. The overload protection mechanism includes an
       automatic termination and restart feature for the purpose of guaranteeing
-      that a handler does not grow out of bounds. The feature can be configured
+      that a handler does not grow out of bounds. The feature is configured
       with the following parameters:</p>
       <taglist>
 	<tag><c>overload_kill_enable</c></tag>
@@ -1281,27 +1281,33 @@ logger:add_handler(my_disk_log_h, logger_disk_log_h,
 	</item>
 	<tag><c>overload_kill_qlen</c></tag>
 	<item>
-	  <p>This is the maximum allowed queue length. If the mailbox grows larger
-	  than this, the handler process gets terminated.</p>
+	  <p>This is the maximum allowed queue length. If the message queue grows
+	  larger than this, the handler process is terminated.</p>
 	  <p>Defaults to <c>20000</c> messages.</p>
 	</item>
 	<tag><c>overload_kill_mem_size</c></tag>
 	<item>
 	  <p>This is the maximum memory size that the handler process is allowed to use.
-	  If the handler grows larger than this, the process gets terminated.</p>
+	  If the handler grows larger than this, the process is terminated.</p>
 	  <p>Defaults to <c>3000000</c> bytes.</p>
 	</item>
 	<tag><c>overload_kill_restart_after</c></tag>
 	<item>
-	  <p>If the handler gets terminated, it can restart automatically after a
-	  delay, specified in milliseconds. The value <c>infinity</c> can also be set,
-	  which prevents restarts.</p>
+	  <p>If the handler is terminated, it restarts automatically after a
+	  delay specified in milliseconds. The value <c>infinity</c> prevents
+	  restarts.</p>
 	  <p>Defaults to <c>5000</c> milliseconds.</p>
 	</item>
       </taglist>
-      <p>If the handler process gets terminated because of overload, information about
-      this event is printed in the log. Information about when a restart has taken
-      place, and the handler is back in action, is also printed.</p>
+      <p>If the handler process is terminated because of overload, it prints
+      information about it in the log. It also prints information about when a
+      restart has taken place, and the handler is back in action.</p>
+      <note>
+	<p>The sizes of the log events affect the memory needs of the handler.
+	For information about how to limit the size of log events, see the
+	<seealso marker="logger_formatter"><c>logger_formatter(3)</c></seealso>
+	manual page.</p>
+      </note>
     </section>
   </section>