From 395dbad6bcc38c3384840674f40657273b05b14a Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Tue, 8 May 2018 16:13:50 +0200 Subject: logger: Rework configuration of logger Most logger configuration that was possible through kernel application variables have been moved into a common 'logger' application environment in kernel. Now all the configuration possible through the logger API can be done as sys config. The handler started by kernel has been renamed to 'default' instead of logger_std_h. There is a new logger:setup_handlers/1 function that given an application name can be used to setup handlers in other applications. --- lib/kernel/doc/src/config.xml | 4 +- lib/kernel/doc/src/kernel_app.xml | 141 ++++++++----------------------- lib/kernel/doc/src/logger.xml | 103 ++++++++++++++++++++-- lib/kernel/doc/src/logger_chapter.xml | 101 +++++++++++++++++++++- lib/kernel/doc/src/logger_disk_log_h.xml | 8 +- lib/kernel/doc/src/logger_formatter.xml | 2 +- lib/kernel/doc/src/logger_std_h.xml | 11 ++- lib/kernel/doc/src/ref_man.xml | 4 +- 8 files changed, 243 insertions(+), 131 deletions(-) (limited to 'lib/kernel/doc/src') diff --git a/lib/kernel/doc/src/config.xml b/lib/kernel/doc/src/config.xml index fdb2d29f63..8850c1736b 100644 --- a/lib/kernel/doc/src/config.xml +++ b/lib/kernel/doc/src/config.xml @@ -37,10 +37,10 @@ data in the system configuration file Name.config.

Configuration parameter values in the configuration file override the values in the application resource files (see - app(4). + app(4)). The values in the configuration file can be overridden by command-line flags (see - erts:erl(1).

+ erts:erl(1)).

The value of a configuration parameter is retrieved by calling application:get_env/1,2.

diff --git a/lib/kernel/doc/src/kernel_app.xml b/lib/kernel/doc/src/kernel_app.xml index 7894600c21..ebc7962f29 100644 --- a/lib/kernel/doc/src/kernel_app.xml +++ b/lib/kernel/doc/src/kernel_app.xml @@ -165,78 +165,34 @@

Permissions are described in application:permit/2.

- logger_dest = Value + logger = [Config] -

Value is one of:

- - tty -

Installs the standard handler, - logger_std_h(3), with type set - to standard_io. This is the default - option.

 - {file, FileName} -

Installs the standard handler, - logger_std_h(3), with type set - to {file, FileName}, where FileName - is a string. The file is opened with encoding UTF-8.

 - {disk_log, FileName} -

Installs the disk_log handler, - logger_disk_log_h(3), with file set - to FileName (a string), and possibly other disk_log - parameters set by the environment variables - logger_disk_log_type, logger_disk_log_maxfiles and - logger_disk_log_maxbytes, - see below. The - file is opened with encoding UTF-8.

 - false - -

No standard handler is installed, but - the initial, primitive handler is kept, printing - raw event messages to tty.

- - silent - -

No standard handler is started, and the initial, - primitive handler is removed.

- - +

Specifies how logger should be + configured.

+

For more details and examples, see the + Configuration section in the + Logger User's Guide. +

- logger_level = Level + logger_level = Level -

Value = emergency | alert | critical | error | warning | +

Level = emergency | alert | critical | error | warning | notice | info | debug

This parameter specifies which log levels to log. The specified level, and all levels that are more severe, will be logged.

-

This configuration parameter is used both for the global - logger level, and for the standard handler started by - the Kernel application (see logger_dest variable above).

+

It is possible to change this variable at run-time + using + logger:set_logger_config(#{ level => error }). + .

The default value is info.

 - - logger_disk_log_type = halt | wrap - - logger_disk_log_maxfiles = integer() - - logger_disk_log_maxbytes = integer() - -

If logger_dest is set to {disk_log,File}, then these - parameters specify the configuration to use when opening the - disk log file. They specify the type of disk log, the - maximum number of files (if the type is wrap) and the - maximum size of each file, respectively.

-

The default values are:

- -logger_disk_log_type = wrap -logger_disk_log_maxfiles = 10 -logger_disk_log_maxbytes = 1048576 - logger_sasl_compatible = boolean() -

If this parameter is set to true, then the logger handler - started by kernel will not log any progress-, crash-, or - supervisor reports. If the SASL application is started, +

If this parameter is set to true, then the default logger handler + will not log any progress-, crash-, or supervisor reports. + If the SASL application is started, these log events will be sent to a second handler instance named sasl_h, according to values of the SASL environment variables sasl_error_logger @@ -247,6 +203,8 @@ logger_disk_log_maxbytes = 1048576

See chapter Backwards compatibility with error_logger for more information about handling of the so called SASL reports.

+

This configuration option only effects the default + and sasl handler. Any other handlers are uneffected.

 logger_log_progress = boolean() @@ -254,51 +212,13 @@ logger_disk_log_maxbytes = 1048576

If logger_sasl_compatible = false, then logger_log_progress specifies if progress reports from supervisor - and application_controller shall be logged or - not.

+ and application_controller shall be logged by the + default logger.

If logger_sasl_compatible = true, then logger_log_progress is ignored.

- - - logger_format_depth = Depth - -

Can be used to limit the size of the - formatted output from the logger handlers.

- -

Depth is a positive integer representing the maximum - depth to which terms are printed by the logger - handlers included in OTP. This - configuration parameter is used by the default formatter, - logger_formatter(3), - unless the formatter's depth parameter is explicitly set. - (If you have implemented your own formatter, this configuration - parameter has no effect on that.)

- -

Depth is used as follows: Format strings - received by the formatter are rewritten. - The format controls ~p and ~w are replaced with - ~P and ~W, respectively, and Depth is - used as the depth parameter. For details, see - io:format/2 - in STDLIB.

- -

A reasonable starting value for Depth is - 30. We recommend to test crashing various processes in your - application, examine the logs from the crashes, and then - increase or decrease the value.

 - - logger_max_size = integer() | unlimited - -

This parameter specifies a hard maximum size limit (number - of characters) each log event can have when printed by the - default logger formatter. If the resulting string after - formatting an event is bigger than this, it will be - truncated before printed to the handler's destination.

- - logger_utc = boolean() - -

If set to true, the default formatter will display - all dates in Universal Coordinated Time.

+

The default value is false

+

This configuration option only effects the default + and sasl handler. Any other handlers are uneffected.

 global_groups = [GroupTuple] @@ -572,9 +492,20 @@ MaxT = TickTime + TickTime / 4 variables are not set.

error_logger - Replaced by logger_dest + Replaced by setting the type of the default + logger_std_h + to the same value. Example: + +erl -kernel logger '[{handler,default,logger_std_h,#{logger_std_h=>#{type=>{file,"/tmp/erlang.log"}}}}]' + + error_logger_format_depth - Replaced by logger_format_depth + Replaced by setting the depth + parameter of the default handlers formatter. Example: + +erl -kernel logger '[{handler,default,logger_std_h,#{formatter=>{logger_formatter,#{legacy_header=>true,template=>[{logger_formatter,header},"\n",msg,"\n"],depth=>10}}}]' + +

See Backwards compatibility with error_logger for more diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index d901454e62..239b9553b1 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -33,10 +33,49 @@ logger.xml logger - API module for the logger application. + API module for the logger. - +

+ This module is the main logger API. It contains functions that allow + application to use a single log API and the system to manage those log + events independently. To log events the logger + macros should be used. For instance, + to log a new error log event:

+ +?LOG_ERROR("error happened because: ~p",[Reason]). %% With macro +logger:error("error happened because: ~p",[Reason]). %% Without macro + +

This log event will then be sent to the configured log handlers which + by default means that it will be printed to the console. If you want + your systems logs to be printed to a file instead of the console you + have to configure the default handler to do so. The simplest way is + to include the following in your sys.config.

+ +[{kernel, + [{logger, + [{handler,default,logger_std_h, + #{logger_std_h=>#{type=>{file,"path/to/file.log"}}}}]}]}]. + +

+ For more information about: +

+ + how to use the API, + see the User's Guide. + how to configure logger, + see the Configuration + section in the User's Guide. + the convinience macros in logger.hrl, + see the macro section. + what the builtin formatter can do, + see logger_formatter. + what the builtin handlers can do, + see logger_std_h and + logger_disk_log_h. + what builtin filters are available, + see logger_filters. + @@ -348,16 +387,16 @@ logger:i(print). Current logger configuration: Level: info - FilterDefault: log + Filter Default: log Filters: Handlers: - Id: logger_std_h + Id: default Module: logger_std_h Level: info Formatter: Module: logger_formatter - Config: #{template => [{logger_formatter,header},"\n",msg,"\n"], - legacy_header => true} + Config: #{legacy_header => true,single_line => false, + template => [{logger_formatter,header},"\n",msg,"\n"]} Filter Default: stop Filters: Id: stop_progress @@ -549,6 +588,56 @@ Current logger configuration: + + + Setup logger handlers from the applications configuration parameters. + +

Reads the application configuration parameter logger and + calls logger:add_handlers/1 with it contents.

+ + + + + + Setup logger handlers. + + +

This function should be used by custom logger handlers to make + configuration consistent no matter which handler the system uses. + Normal usage to to add a call to logger:add_handlers/1 + just after the processes that the handler needs are started + and pass the applications logger config as an argument. Eg.

+ +-behaviour(application). +start(_, []) -> + case supervisor:start_link({local, my_sup}, my_sup, []) of + {ok, Pid} -> + ok = logger:add_handlers(my_app), + {ok, Pid, []}; + Error -> Error + end. +

This will read the logger configuration parameter from + the handler application and start the configured handlers. The contents + of the configuration use the same rules as the + logger handler configuration. +

+

If the handler is meant to replace the default handler the kernels + default handlers have to be disabled before the new handler is added. + A sys.config file that disables the kernel handler and adds + a custom handler could looks like this:

+ +[{kernel, + [{logger, + %% Disable the default kernel handler + [{handler,default,undefined}]}]}, + {my_app, + [{logger, + %% Enable this handler as the default + [{handler,default,my_handler,#{}}]}]}]. + + + + Set configuration data for the logger. @@ -650,7 +739,7 @@ Current logger configuration:

If process metadata exists for the current process, this function behaves as if it was implemented as follows:

-logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)) +logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).

If no process metadata exists, the function behaves as diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml index 3150c5adb4..484358f392 100644 --- a/lib/kernel/doc/src/logger_chapter.xml +++ b/lib/kernel/doc/src/logger_chapter.xml @@ -248,11 +248,97 @@

Configuration +

Logger can be configured either when the system starts through + configuration parameters, + or at run-time by using the logger + API. The recommended approach is to do the initial configuration in + the sys.config file and then use the API when some configuration + has to be changed at run-time, such as the logging level.

+
- Application environment variables -

See Kernel(6) for - information about the application environment variables that can - be used for configuring logger.

+ Application configuration parameters +

Logger is best configured by using the configuration parameters + of kernel. There are three possible configuration parameters: + logger, + logger_level, + logger_sasl_compatible and + logger_log_progress. + logger_level, logger_sasl_compatible and logger_log_progress are described in the + Kernel Configuration, + while logger is described below.

+
+ + logger +

The logger application configuration parameter is used to configure + three different logger aspects; handlers, logger filters and module levels. + The configuration is a list containing tagged tuples that look like this:

+ + DisableHandler = {handler,default,undefined} + Disable the default handler. This will allow another application + to add its own default handler. See + logger:add_handlers/1 for more details. + AddHandler = {handler,HandlerId,Module,HandlerConfig} + Add a handler as if + logger:add_handler(HandlerId,Module,HandlerConfig) had been + called. + Filters = {filters, FilterDefault, [Filter]}
+ FilterDefault = log | stop
+ Filter = {FilterId, {FilterFun, FilterConfig}} + Add the specified + logger filters. Only one entry is allowed of this option. + ModuleLevel + {module_level, Level, [Module]}, + this option configures the + module log level to be used. It is possible to have multiple + module_level entries. + +

Examples:

+ + +

Output logs into a the file "logs/erlang.log"

+ +[{kernel, + [{logger, + [{handler, default, logger_std_h, + #{ logger_std_h => #{ type => {file,"log/erlang.log"}}}}]}]}]. + + + +

Output logs in single line format

+ +[{kernel, + [{logger, + [{handler, default, logger_std_h, + #{ formatter => { logger_formatter,#{ single_line => true}}}}]}]}]. + + + +

Add the pid to each log event

+ +[{kernel, + [{logger, + [{handler, default, logger_std_h, + #{ formatter => { logger_formatter, + #{ template => [time," ",pid," ",msg,"\n"]}} + }}]}]}]. + + + +

Use a different file for debug logging

+ +[{kernel, + [{logger, + [{handler, default, logger_std_h, + #{ level => error, + logger_std_h => #{ type => {file, "log/erlang.log"}}}}, + {handler, info, logger_std_h, + #{ level => debug, + logger_std_h => #{ type => {file, "log/debug.log"}}}} + ]}]}]. + + + +
@@ -330,6 +416,13 @@ logger_formatter, and Extra is it's configuration map.

+ HandlerConfig, term() = term() + + Any keys not listed above are considered to be handler specific + configuration. The configuration of the Kernel handlers can be found in + logger_std_h and + logger_disk_log_h. +

Note that level and filters are obeyed by diff --git a/lib/kernel/doc/src/logger_disk_log_h.xml b/lib/kernel/doc/src/logger_disk_log_h.xml index 90cc4fec30..440ae28e5d 100644 --- a/lib/kernel/doc/src/logger_disk_log_h.xml +++ b/lib/kernel/doc/src/logger_disk_log_h.xml @@ -121,11 +121,11 @@ logger:add_handler(my_disk_log_h, logger_disk_log_h, #{filesync_repeat_interval => 1000}}).

In order to use the disk_log handler instead of the default standard - handler when starting en Erlang node, use the kernel configuration parameter - logger_dest with - value {disk_log,FileName}. Example:

+ handler when starting en Erlang node, change the Kernel default logger to + use disk_log. Example:

-erl -kernel logger_dest '{disk_log,"./system_disk_log"}' +erl -kernel logger '[{handler,default,logger_disk_log_h, + #{ disk_log_opts => #{ file => "./system_disk_log"}}}]' diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml index 7df4c88f40..5f13e54365 100644 --- a/lib/kernel/doc/src/logger_formatter.xml +++ b/lib/kernel/doc/src/logger_formatter.xml @@ -66,7 +66,7 @@ be truncated by the max_size parameter.

- depth = pos_integer() | unlimited + depth = pos_integer() | unlimited

A positive integer representing the maximum depth to which terms shall be printed by this formatter. Format diff --git a/lib/kernel/doc/src/logger_std_h.xml b/lib/kernel/doc/src/logger_std_h.xml index fe9b9ca5a9..bf23d874c8 100644 --- a/lib/kernel/doc/src/logger_std_h.xml +++ b/lib/kernel/doc/src/logger_std_h.xml @@ -40,7 +40,7 @@ application. Multiple instances of this handler can be added to logger, and each instance will print logs to standard_io, standard_error or to file. The default instance that starts - with kernel is named logger_std_h - which is the name to be used + with kernel is named default - which is the name to be used for reconfiguration.

The handler has an overload protection mechanism that will keep the handler process and the kernel application alive during a high load of log @@ -57,7 +57,7 @@ are stored in a sub map with the key logger_std_h. The following keys and values may be specified:

- type + type

This will have the value standard_io, standard_error, {file,LogFileName}, or {file,LogFileName,LogFileOpts}, @@ -105,11 +105,10 @@ logger:add_handler(my_standard_h, logger_std_h,

In order to configure the default handler (that starts initially with the kernel application) to log to file instead of standard_io, - use the kernel configuration parameter - logger_dest with - value {file,FileName}. Example:

+ change the Kernel default logger to use a file. Example:

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

An example of how to replace the standard handler with a disk_log handler at startup can be found in the manual of diff --git a/lib/kernel/doc/src/ref_man.xml b/lib/kernel/doc/src/ref_man.xml index a633ae4832..b6c2714664 100644 --- a/lib/kernel/doc/src/ref_man.xml +++ b/lib/kernel/doc/src/ref_man.xml @@ -32,9 +32,11 @@ + + @@ -67,6 +69,4 @@ - - -- cgit v1.2.3