From 343298ef2ef349e7b74265751fd6151ada224470 Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Wed, 13 Jun 2018 23:56:38 +0200 Subject: [logger] Correct documentation --- lib/kernel/doc/src/logger_chapter.xml | 128 ++++++++++++++++--------------- lib/kernel/doc/src/logger_disk_log_h.xml | 33 ++++---- lib/kernel/doc/src/logger_std_h.xml | 47 +++++------- 3 files changed, 101 insertions(+), 107 deletions(-) (limited to 'lib/kernel/doc/src') 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.

+ Logger API

The API for logging consists of a set of macros, and a set @@ -1107,7 +1108,7 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) -> logger_std_h and logger_disk_log_h, 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:

@@ -1127,47 +1128,49 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) ->

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 Logger API, + 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 sync_mode_qlen 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.

-

Default value of the threshold: 10 messages.

+

Defaults to 10 messages.

 drop_mode_qlen

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.

-

Default value of the threshold: 200 messages.

+ 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.

+

Defaults to 200 messages.

 flush_qlen

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

-

Default value of the threshold: 1000 messages.

+ 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.

+

Defaults to 1000 messages.

 @@ -1186,15 +1189,15 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) -> synchronously. That is, asynchronous logging is disabled. If sync_mode_qlen is set to the same value as drop_mode_qlen, synchronous mode is disabled. That is, the handler - always runs in asychronous mode, unless dropping or flushing is invoked. + always runs in asynchronous mode, unless dropping or flushing is invoked. If drop_mode_qlen is set to the same value as flush_qlen, drop mode is disabled and can never occur.

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.

@@ -1202,38 +1205,36 @@ do_log(Fd, LogEvent, #{formatter := {FModule, FConfig}}) ->

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).

+ 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.

A configuration example:

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}}).
Controlling Bursts of Log Requests -

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:

+

Large bursts of log events - many events received by the handler + under a short period of time - can potentially cause problems, such as:

Log files grow very large, very quickly. - Circular logs wrap too quickly so that important data gets overwritten. + Circular logs wrap too quickly so that important data is overwritten. Write buffers grow large, which slows down file sync operations.

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:

- + massive amounts of printouts. The configuration parameters are:

burst_limit_enable @@ -1243,13 +1244,13 @@ logger:add_handler(my_standard_h, logger_std_h, burst_limit_max_count

This is the maximum number of events to handle within a - burst_limit_window_time time frame. After the limit has been - reached, successive events get dropped until the end of the time frame.

+ burst_limit_window_time time frame. After the limit is + reached, successive events are dropped until the end of the time frame.

Defaults to 500 events.

 burst_limit_window_time -

See the previous description of burst_limit_window_time.

+

See the previous description of burst_limit_max_count.

Defaults to 1000 milliseconds.

 @@ -1257,11 +1258,10 @@ logger:add_handler(my_standard_h, logger_std_h,

A configuration example:

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}}).
@@ -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:

overload_kill_enable @@ -1281,27 +1281,33 @@ logger:add_handler(my_disk_log_h, logger_disk_log_h, overload_kill_qlen -

This is the maximum allowed queue length. If the mailbox grows larger - than this, the handler process gets terminated.

+

This is the maximum allowed queue length. If the message queue grows + larger than this, the handler process is terminated.

Defaults to 20000 messages.

 overload_kill_mem_size

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.

+ If the handler grows larger than this, the process is terminated.

Defaults to 3000000 bytes.

 overload_kill_restart_after -

If the handler gets terminated, it can restart automatically after a - delay, specified in milliseconds. The value infinity can also be set, - which prevents restarts.

+

If the handler is terminated, it restarts automatically after a + delay specified in milliseconds. The value infinity prevents + restarts.

Defaults to 5000 milliseconds.

 -

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.

+

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.

+ +

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 + logger_formatter(3) + manual page.

+ 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 @@ logger_disk_log_h.xml logger_disk_log_h - A disk_log based handler for the Logger. + A disk_log based handler for Logger

This is a handler for Logger that offers circular (wrapped) logs by using disk_log. 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.

The default standard handler, logger_std_h, can be @@ -62,14 +62,14 @@ file -

This is the full name of the disk_log log file. The option +

This is the full name of the disk log file. The option corresponds to the name property in the dlog_option() datatype.

type -

This is the disk_log type, wrap or halt. The option +

This is the disk log type, wrap or halt. The option corresponds to the type property in the dlog_option() datatype.

@@ -77,18 +77,19 @@ max_no_files -

This is the maximum number of files that disk_log will use +

This is the maximum number of files that disk_log uses for its circular logging. The option corresponds to the MaxNoFiles element in the size property in the dlog_option() datatype.

-

Defaults to 10. (The setting has no effect on a halt log).

+

Defaults to 10.

+

The setting has no effect on a halt log.

 max_no_bytes -

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 +

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 MaxNoBytes element in the size property in the dlog_option() datatype.

@@ -113,17 +114,13 @@ standard handler and the disk_log handler, and are documented in the User's Guide .

-

Note that when changing the configuration of the handler in runtime, by - calling - logger:set_handler_config/2 - or logger:set_handler_config/3, the disk_log options (file, - type, max_no_files, max_no_bytes) must not be modified.

+

Notice that when changing the configuration of the handler in runtime, the + disk_log options (file, type, max_no_files, + max_no_bytes) must not be modified.

Example of adding a disk_log handler:

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,

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:

+ use logger_disk_log_h. Example:

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 @@ logger_std_h.xml logger_std_h - Default handler for Logger. + Standard handler for Logger. -

This is the default handler for Logger. +

This is the standard handler for Logger. Multiple instances of this handler can be added to Logger, and each instance prints logs to standard_io, - standard_error or to file. The default instance that starts - with Kernel is named default, which is the name to be used - for reconfiguration.

+ standard_error, or to file.

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 @@

This has the value standard_io, standard_error, {file,LogFileName}, or {file,LogFileName,LogFileOpts}.

Defaults to standard_io.

-

It is recommended to not specify LogFileOpts, unless absolutely - necessary. The default options used by the handler to open a file for logging are: - raw, append and delayed_write. Note that the standard - handler does not have support for circular logging. Use the - logger_disk_log_h - handler for this.

+

It is recommended not to specify LogFileOpts unless absolutely + necessary. The default options used by the handler to open a file for logging are + raw, append, and delayed_write. Notice that the standard + handler does not have support for circular logging. Use the disk_log handler, + logger_disk_log_h, + for this.

 filesync_repeat_interval @@ -77,8 +75,8 @@ actually been logged.

Defaults to 5000 milliseconds.

If no_repeat 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 filesync/1 function to perform a file sync.

 @@ -88,32 +86,25 @@ standard handler and the disk_log handler, and are documented in the User's Guide .

-

Note that if changing the configuration of the handler in runtime, by - calling - logger:set_handler_config/2 - , or - logger:set_handler_config/3 - , +

Notice that if changing the configuration of the handler in runtime, the type parameter must not be modified.

Example of adding a standard handler:

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}}). -

To set the default handler (that starts initially with - the Kernel application) to log to file instead of standard_io, +

To set the default handler, that starts initially with + the Kernel application, to log to file instead of standard_io, change the Kernel default logger configuration. Example:

erl -kernel logger '[{handler,default,logger_std_h, #{config => #{type => {file,"./log.log"}}}}]'

An example of how to replace the standard handler with a disk_log handler - at start up can be found in the manual of - logger_disk_log_h.

+ at startup is found in the + logger_disk_log_h + manual.

 -- cgit v1.2.3