diff options
| -rw-r--r-- | lib/kernel/doc/src/logger_chapter.xml | 128 | ||||
| -rw-r--r-- | lib/kernel/doc/src/logger_disk_log_h.xml | 33 | ||||
| -rw-r--r-- | lib/kernel/doc/src/logger_std_h.xml | 47 |
3 files changed, 101 insertions, 107 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> diff --git a/lib/kernel/doc/src/logger_disk_log_h.xml b/lib/kernel/doc/src/logger_disk_log_h.xml index c60cf14cc7..98439983cf 100644 --- a/lib/kernel/doc/src/logger_disk_log_h.xml +++ b/lib/kernel/doc/src/logger_disk_log_h.xml @@ -33,13 +33,13 @@ <file>logger_disk_log_h.xml</file> </header> <module>logger_disk_log_h</module> - <modulesummary>A disk_log based handler for the Logger.</modulesummary> + <modulesummary>A disk_log based handler for Logger</modulesummary> <description> <p>This is a handler for Logger that offers circular (wrapped) logs by using <seealso marker="disk_log"><c>disk_log</c></seealso>. Multiple instances of this handler can be added to Logger, and each instance - prints to its own disk_log file, created with the name and settings specified + prints to its own disk log file, created with the name and settings specified in the handler configuration.</p> <p>The default standard handler, <seealso marker="logger_std_h"><c>logger_std_h</c></seealso>, can be @@ -62,14 +62,14 @@ <taglist> <tag><c>file</c></tag> <item> - <p>This is the full name of the disk_log log file. The option + <p>This is the full name of the disk log file. The option corresponds to the <c>name</c> property in the <seealso marker="disk_log#open-1"><c>dlog_option()</c></seealso> datatype.</p> </item> <tag><c>type</c></tag> <item> - <p>This is the disk_log type, <c>wrap</c> or <c>halt</c>. The option + <p>This is the disk log type, <c>wrap</c> or <c>halt</c>. The option corresponds to the <c>type</c> property in the <seealso marker="disk_log#open-1"><c>dlog_option()</c></seealso> datatype.</p> @@ -77,18 +77,19 @@ </item> <tag><c>max_no_files</c></tag> <item> - <p>This is the maximum number of files that disk_log will use + <p>This is the maximum number of files that disk_log uses for its circular logging. The option 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>Defaults to <c>10</c>. (The setting has no effect on a halt log).</p> + <p>Defaults to <c>10</c>.</p> + <p>The setting has no effect on a halt log.</p> </item> <tag><c>max_no_bytes</c></tag> <item> - <p>This is the maximum number of bytes that will be written to - a log file before disk_log proceeds with the next file in order (or - generates an error in case of a full halt log). The option + <p>This is the maximum number of bytes that is written to + a log file before disk_log proceeds with the next file in order, or + generates an error in case of a full halt log. The option 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> @@ -113,17 +114,13 @@ standard handler and the disk_log handler, and are documented in the <seealso marker="logger_chapter#overload_protection"><c>User's Guide</c> </seealso>.</p> - <p>Note that when changing the configuration of the handler in runtime, by - calling - <seealso marker="logger#set_handler_config-2"><c>logger:set_handler_config/2 - or logger:set_handler_config/3</c></seealso>, the disk_log options (<c>file</c>, - <c>type</c>, <c>max_no_files</c>, <c>max_no_bytes</c>) must not be modified.</p> + <p>Notice that when changing the configuration of the handler in runtime, the + disk_log options (<c>file</c>, <c>type</c>, <c>max_no_files</c>, + <c>max_no_bytes</c>) must not be modified.</p> <p>Example of adding a disk_log handler:</p> <code type="none"> logger:add_handler(my_disk_log_h, logger_disk_log_h, - #{level => error, - filter_default => log, - config => #{file => "./my_disk_log", + #{config => #{file => "./my_disk_log", type => wrap, max_no_files => 4, max_no_bytes => 10000}, @@ -131,7 +128,7 @@ logger:add_handler(my_disk_log_h, logger_disk_log_h, </code> <p>To use the disk_log handler instead of the default standard handler when starting an Erlang node, change the Kernel default logger to - use disk_log. Example:</p> + use <c>logger_disk_log_h</c>. Example:</p> <code type="none"> erl -kernel logger '[{handler,default,logger_disk_log_h, #{config => #{file => "./system_disk_log"}}}]' diff --git a/lib/kernel/doc/src/logger_std_h.xml b/lib/kernel/doc/src/logger_std_h.xml index 08667ae7f9..95b4baf160 100644 --- a/lib/kernel/doc/src/logger_std_h.xml +++ b/lib/kernel/doc/src/logger_std_h.xml @@ -33,15 +33,13 @@ <file>logger_std_h.xml</file> </header> <module>logger_std_h</module> - <modulesummary>Default handler for Logger.</modulesummary> + <modulesummary>Standard handler for Logger.</modulesummary> <description> - <p>This is the default handler for Logger. + <p>This is the standard handler for Logger. Multiple instances of this handler can be added to Logger, and each instance prints logs to <c>standard_io</c>, - <c>standard_error</c> or to file. The default instance that starts - with Kernel is named <c>default</c>, which is the name to be used - for reconfiguration.</p> + <c>standard_error</c>, or to file.</p> <p>The handler has an overload protection mechanism that keeps the handler process and the Kernel application alive during high loads of log events. How overload protection works, and how to configure it, is @@ -62,12 +60,12 @@ <p>This has the value <c>standard_io</c>, <c>standard_error</c>, <c>{file,LogFileName}</c>, or <c>{file,LogFileName,LogFileOpts}</c>.</p> <p> Defaults to <c>standard_io</c>.</p> - <p>It is recommended to not specify <c>LogFileOpts</c>, unless absolutely - necessary. The default options used by the handler to open a file for logging are: - <c>raw</c>, <c>append</c> and <c>delayed_write</c>. Note that the standard - handler does not have support for circular logging. Use the - <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c> - </seealso> handler for this.</p> + <p>It is recommended not to specify <c>LogFileOpts</c> unless absolutely + necessary. The default options used by the handler to open a file for logging are + <c>raw</c>, <c>append</c>, and <c>delayed_write</c>. Notice that the standard + handler does not have support for circular logging. Use the disk_log handler, + <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso>, + for this.</p> </item> <tag><c>filesync_repeat_interval</c></tag> <item> @@ -77,8 +75,8 @@ actually been logged.</p> <p>Defaults to <c>5000</c> milliseconds.</p> <p>If <c>no_repeat</c> is set as value, the repeated file sync operation - is disabled, and it will be the operating system settings that determine - how quickly or slowly data gets written to disk. The user can also call + is disabled, and it is the operating system settings that determine + how quickly or slowly data is written to disk. The user can also call the <seealso marker="logger_std_h#filesync-1"><c>filesync/1</c></seealso> function to perform a file sync.</p> </item> @@ -88,32 +86,25 @@ standard handler and the disk_log handler, and are documented in the <seealso marker="logger_chapter#overload_protection"><c>User's Guide</c> </seealso>.</p> - <p>Note that if changing the configuration of the handler in runtime, by - calling - <seealso marker="logger#set_handler_config-2"><c>logger:set_handler_config/2</c> - </seealso>, or - <seealso marker="logger#set_handler_config-3"><c>logger:set_handler_config/3</c> - </seealso>, + <p>Notice that if changing the configuration of the handler in runtime, the <c>type</c> parameter must not be modified.</p> <p>Example of adding a standard handler:</p> <code type="none"> logger:add_handler(my_standard_h, logger_std_h, - #{level => info, - filter_default => log, - config => - #{type => {file,"./system_info.log"}, - filesync_repeat_interval => 1000}}). + #{config => #{type => {file,"./system_info.log"}, + filesync_repeat_interval => 1000}}). </code> - <p>To set the default handler (that starts initially with - the Kernel application) to log to file instead of <c>standard_io</c>, + <p>To set the default handler, that starts initially with + the Kernel application, to log to file instead of <c>standard_io</c>, change the Kernel default logger configuration. Example:</p> <code type="none"> erl -kernel logger '[{handler,default,logger_std_h, #{config => #{type => {file,"./log.log"}}}}]' </code> <p>An example of how to replace the standard handler with a disk_log handler - at start up can be found in the manual of - <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso>.</p> + at startup is found in the + <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso> + manual.</p> </description> <funcs> |