From 53539ee751da408029c9dfae80384fdec6c7a552 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Tue, 22 May 2018 13:22:55 +0200 Subject: Update documentation of logger and error_logger --- lib/kernel/doc/src/error_logger.xml | 233 ++++++++++------ lib/kernel/doc/src/kernel_app.xml | 8 +- lib/kernel/doc/src/logger.xml | 44 ++- lib/kernel/doc/src/logger_chapter.xml | 477 ++++++++++++++++++++------------ lib/kernel/doc/src/logger_formatter.xml | 370 +++++++++++++------------ 5 files changed, 682 insertions(+), 450 deletions(-) (limited to 'lib/kernel/doc/src') diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml index e91fc734a4..f418aa5bbe 100644 --- a/lib/kernel/doc/src/error_logger.xml +++ b/lib/kernel/doc/src/error_logger.xml @@ -33,9 +33,10 @@ -

In OTP-21, a new API for logging was added to Erlang/OTP. The +

In Erlang/OTP 21.0, a new API for logging was added. The old error_logger module can still be used by legacy - code, but new code should use the new API instead.

+ code, but log events are redirected to the new Logger API. New + code should use the Logger API directly.

error_logger is no longer started by default, but is automatically started when an event handler is added with error_logger:add_report_handler/1,2. The error_logger @@ -89,6 +90,9 @@ The function returns ok if successful.

The event handler must be able to handle the events in this module, see section Events.

+

The first time this function is called, + error_logger is added as a Logger handler, and + the error_logger process is started.

@@ -98,37 +102,40 @@

Deletes an event handler from the error logger by calling gen_event:delete_handler(error_logger, Handler, []), see gen_event(3).

+

If no more event handlers exist after the deletion, + error_logger is removed as a Logger handler, and + the error_logger process is stopped.

 - Send a standard error event to the error logger. + Log a standard error event. -

Sends a standard error event to the error logger. - The Format and Data arguments - are the same as the arguments of +

Log a standard error event. The Format + and Data arguments are the same as the + arguments of io:format/2 - in STDLIB. - The event is handled by the standard event handler.

+ in STDLIB.

+

Error logger forwards the event to Logger, including + metadata that allows backwards compatibility with legacy + error logger event handlers.

+

The event is handled by the default Logger handler.

+

These functions are kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_ERROR macro or + logger:error/1,2,3 + instead.

Example:

-1> error_logger:error_msg("An error occurred in ~p~n", [a_module]).
-
-=ERROR REPORT==== 11-Aug-2005::14:03:19 ===
+1> error_logger:error_msg("An error occurred in ~p", [a_module]).
+=ERROR REPORT==== 22-May-2018::11:18:43.376917 ===
 An error occurred in a_module
 ok
- -

If called with bad arguments, this function can crash - the standard event handler, meaning no further events are - logged. When in doubt, use - error_report/1 - instead.

-

If the Unicode translation modifier (t) is used in - the format string, all error handlers must ensure that the + the format string, all event handlers must ensure that the formatted output is correctly encoded for the I/O device.

 @@ -136,36 +143,51 @@ ok - Send a standard error report event to the error logger. + Log a standard error event. -

Sends a standard error report event to the error logger. - The event is handled by the standard event handler.

+

Log a standard error event. Error logger forwards the event + to Logger, including metadata that allows backwards + compatibility with legacy error logger event handlers.

+

The event is handled by the default Logger handler.

+

This functions is kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_ERROR macro or + logger:error/1,2,3 + instead.

Example:

 2> error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).
-
-=ERROR REPORT==== 11-Aug-2005::13:45:41 ===
+=ERROR REPORT==== 22-May-2018::11:24:23.699306 ===
     tag1: data1
     a_term
     tag2: data
 ok
 3> error_logger:error_report("Serious error in my module").
-
-=ERROR REPORT==== 11-Aug-2005::13:45:49 ===
+=ERROR REPORT==== 22-May-2018::11:24:45.972445 ===
 Serious error in my module
 ok
 - Send a user-defined error report event to the error logger. + Log a user-defined error event. -

Sends a user-defined error report event to the error logger. - An event handler to handle the event is supposed to have been - added. The event is ignored by the standard event handler.

+

Log a user-defined error event. Error logger forwards the + event to Logger, including metadata that allows backwards + compatibility with legacy error logger event handlers.

+

Error logger also adds a domain field with + value [Type] to this event's metadata, + causing the filters of the default Logger handler to discard + the event. A different Logger handler, or an error logger + event handler, must be added to handle this event.

It is recommended that Report follows the same structure as for error_report/1.

+

This functions is kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_ERROR macro or + logger:error/1,2,3 + instead.

 @@ -181,38 +203,41 @@ ok

The error_logger_format_depth variable is deprecated since - the logging API was - introduced in OTP-21. The variable, and this function, are - kept for backwards compatibility since they still might be - used by legacy report handlers.

+ the Logger API was + introduced in Erlang/OTP 21.0. The variable, and this + function, are kept for backwards compatibility since they + still might be used by legacy report handlers.

 - Send a standard information event to the error logger. + Log a standard information event. -

Sends a standard information event to the error logger. - The Format and Data arguments - are the same as the arguments of +

Log a standard information event. The Format + and Data arguments are the same as the + arguments of io:format/2 - in STDLIB. The event is handled by the standard event handler.

+ in STDLIB.

+

Error logger forwards the event to Logger, including + metadata that allows backwards compatibility with legacy + error logger event handlers.

+

The event is handled by the default Logger handler.

+

These functions are kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_INFO macro or + logger:info/1,2,3 + instead.

Example:

-1> error_logger:info_msg("Something happened in ~p~n", [a_module]).
-
-=INFO REPORT==== 11-Aug-2005::14:06:15 ===
+1> error_logger:info_msg("Something happened in ~p", [a_module]).
+=INFO REPORT==== 22-May-2018::12:03:32.612462 ===
 Something happened in a_module
 ok
- -

If called with bad arguments, this function can crash - the standard event handler, meaning no further events are - logged. When in doubt, use info_report/1 instead.

-

If the Unicode translation modifier (t) is used in - the format string, all error handlers must ensure that the + the format string, all event handlers must ensure that the formatted output is correctly encoded for the I/O device.

 @@ -220,37 +245,52 @@ ok - Send a standard information report event to the error logger. + Log a standard information event. -

Sends a standard information report event to the error - logger. The event is handled by the standard event handler.

+

Log a standard information event. Error logger forwards the + event to Logger, including metadata that allows backwards + compatibility with legacy error logger event handlers.

+

The event is handled by the default Logger handler.

+

This functions is kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_INFO macro or + logger:info/1,2,3 + instead.

Example:

 2> error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).
-
-=INFO REPORT==== 11-Aug-2005::13:55:09 ===
+=INFO REPORT==== 22-May-2018::12:06:35.994440 ===
     tag1: data1
     a_term
     tag2: data
 ok
 3> error_logger:info_report("Something strange happened").
-
-=INFO REPORT==== 11-Aug-2005::13:55:36 ===
+=INFO REPORT==== 22-May-2018::12:06:49.066872 ===
 Something strange happened
 ok
 - Send a user-defined information report event to the error logger. + Log a user-defined information event. -

Sends a user-defined information report event to the error - logger. An event handler to handle the event is supposed to - have been added. The event is ignored by the standard event - handler.

+

Log a user-defined information event. Error logger forwards + the event to Logger, including metadata that allows + backwards compatibility with legacy error logger event + handlers.

+

Error logger also adds a domain field with + value [Type] to this event's metadata, + causing the filters of the default Logger handler to discard + the event. A different Logger handler, or an error logger + event handler, must be added to handle this event.

It is recommended that Report follows the same structure as for info_report/1.

+

This functions is kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_INFO macro or + logger:info/1,2,3 + instead.

 @@ -349,24 +389,27 @@ ok - Send a standard warning event to the error logger. + Log a standard warning event. -

Sends a standard warning event to the error logger. - The Format and Data arguments - are the same as the arguments of +

Log a standard warning event. The Format + and Data arguments are the same as the + arguments of io:format/2 - in STDLIB. - The event is handled by the standard event handler. It is tagged - as an error, warning, or info, see + in STDLIB.

+

Error logger forwards the event to Logger, including + metadata that allows backwards compatibility with legacy + error logger event handlers.

+

The event is handled by the default Logger handler. The log + level can be changed to error or info, see warning_map/0.

- -

If called with bad arguments, this function can crash - the standard event handler, meaning no further events are - logged. When in doubt, use warning_report/1 instead.

- +

These functions are kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_WARNING macro or + logger:warning/1,2,3 + instead.

If the Unicode translation modifier (t) is used in - the format string, all error handlers must ensure that the + the format string, all event handlers must ensure that the formatted output is correctly encoded for the I/O device.

 @@ -374,24 +417,43 @@ ok - Send a standard warning report event to the error logger. + Log a standard warning event. -

Sends a standard warning report event to the error logger. - The event is handled by the standard event handler. It is - tagged as an error, warning, or info, see +

Log a standard warning event. Error logger forwards the event + to Logger, including metadata that allows backwards + compatibility with legacy error logger event handlers.

+

The event is handled by the default Logger handler. The log + level can be changed to error or info, see warning_map/0.

+

This functions is kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_WARNING macro or + logger:warning/1,2,3 + instead.

 - Send a user-defined warning report event to the error logger. + Log a user-defined warning event. -

Sends a user-defined warning report event to the error - logger. An event handler to handle the event is supposed to - have been added. The event is ignored by the standard event - handler. It is tagged as an error, warning, or info, - depending on the value of +

Log a user-defined warning event. Error logger forwards the + event to Logger, including metadata that allows backwards + compatibility with legacy error logger event handlers.

+

Error logger also adds a domain field with + value [Type] to this event's metadata, + causing the filters of the default Logger handler to discard + the event. A different Logger handler, or an error logger + event handler, must be added to handle this event.

+

The log level can be changed to error or info, see warning_map/0.

+

It is recommended that Report follows the same + structure as for + warning_report/1.

+

This functions is kept for backwards compatibility and + must not be used by new code. Use the + ?LOG_WARNING macro or + logger:warning/1,2,3 + instead.

 @@ -455,8 +517,9 @@ ok
See Also

gen_event(3), - log_mf_h(3) - kernel(6) + logger(3), + log_mf_h(3), + kernel(6), sasl(6)

diff --git a/lib/kernel/doc/src/kernel_app.xml b/lib/kernel/doc/src/kernel_app.xml index 0f7e95472b..e2a6d30249 100644 --- a/lib/kernel/doc/src/kernel_app.xml +++ b/lib/kernel/doc/src/kernel_app.xml @@ -481,13 +481,13 @@ MaxT = TickTime + TickTime / 4
Deprecated Configuration Parameters -

In OTP-21, a new API for logging was added to Erlang/OTP. The +

In Erlang/OTP 21.0, a new API for logging was added. The old error_logger event manager, and event handlers - running on this manager, will still work, but they are not used + running on this manager, still work, but they are no longer used by default.

The following application configuration parameters can still be - set, but they will only be used if the corresponding new logger - variables are not set.

+ set, but they are only used if the corresponding configuration + parameters for Logger are not set.

error_logger Replaced by setting the type of the default diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index bb356c5b86..c0b3d81367 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -132,6 +132,29 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro log event to the handlers. If the same keys occur, values from the log call overwrite process metadata, which in turn overwrite values set by Logger.

+

The following custom metadata keys have special meaning:

+ + domain + +

The value associated with this key is used by filters + for grouping log events originating from, for example, + specific functional + areas. See + logger_filters:domain/2 + for a description of how this field can be used.

+ + report_cb + +

If the log message is specified as + a report(), + the report_cb key can be associated with a fun + (report callback) that converts the report to a format + string and arguments. See + section Log + Message in the User's Guide for more + information about report callbacks.

+ + @@ -145,7 +168,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro filters => [] formatter => {logger_formatter,DefaultFormatterConfig} -

See the +

See the logger_formatter(3) manual page for information about the default configuration for this formatter.

@@ -978,6 +1001,25 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
+ + FModule:check_config(FConfig) -> ok | {error,term()} + Validate the given formatter configuration. + + FConfig = + formatter_config() + + +

This callback function is optional.

+

The function is called by a Logger when formatter + configuration is set or modified. The formatter must + validate the given configuration and return ok if it + is correct, and {error,term()} if it is faulty.

+

See + logger_formatter(3) + for an example implementation. logger_formatter is the + default formatter used by Logger.

+ + FModule:format(LogEvent,FConfig) -> FormattedLogEntry Format the given log event. diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml index 3b4cafb010..a3eec7bd4b 100644 --- a/lib/kernel/doc/src/logger_chapter.xml +++ b/lib/kernel/doc/src/logger_chapter.xml @@ -30,7 +30,7 @@ logger_chapter.xml -

As of OTP-21, Erlang/OTP provides a standard API for logging +

Erlang/OTP 21.0 provides a new standard API for logging through Logger, which is part of the Kernel application. Logger consists of the API for issuing log events, and a customizable backend where log handlers, filters and @@ -65,63 +65,14 @@ Conceptual Overview - -

In accordance with the Syslog protocol, RFC-5424, eight log - levels can be specified:

- - - - Level - Integer - Description - - - emergency - 0 - system is unusable - - - alert - 1 - action must be taken immediately - - - critical - 2 - critical contidions - - - error - 3 - error conditions - - - warning - 4 - warning conditions - - - notice - 5 - normal but significant conditions - - - info - 6 - informational messages - - - debug - 7 - debug-level messages - - Log Levels -
- -

A log event passes the level check if the integer value of its - log level is less than or equal to the currently configured log - level, that is, if the event is equally or more severe than the - configured level.

+

Log levels are expressed as atoms. Internally in Logger, the + atoms are mapped to integer values, and a log event passes the + log level check if the integer value of its log level is less + than or equal to the currently configured log level. That is, + the check pases if the event is equally or more severe than the + configured level. See section Log + Level for a listing and description of all log + levels.

The global log level can be overridden by a log level configured per module. This is to, for instance, allow more verbose logging from a specific part of the system.

@@ -137,13 +88,150 @@ event to its destination. See section Handlers for more details.

-

Everything upto and including the call to the handler callbacks - is executed on the client process, that is, the process where - the log event was issued. It is up to the handler implementation - if other processes are to be involved or not.

+

Everything up to and including the call to the handler + callbacks is executed on the client process, that is, the + process where the log event was issued. It is up to the handler + implementation if other processes are involved or not.

The handlers are called in sequence, and the order is not defined.

+
+ Logger API +

The API for logging consists of a set + of macros, and a set + of functions on the form logger:Level/1,2,3, which are + all shortcuts + for + logger:log(Level,Arg1[,Arg2[,Arg3]]).

+

The difference between using the macros and the exported + functions is that macros add location (originator) information + to the metadata, and performs lazy evaluation by wrapping the + logger call in a case statement, so it is only evaluated if the + log level of the event passes the global log level check.

+
+ + Log Level +

The log level indicates the severity of a event. In + accordance with the Syslog protocol, RFC-5424, eight log + levels can be specified. The following table lists all + possible log levels by name (atom), integer value, and + description:

+ + + + Level + Integer + Description + + + emergency + 0 + system is unusable + + + alert + 1 + action must be taken immediately + + + critical + 2 + critical contidions + + + error + 3 + error conditions + + + warning + 4 + warning conditions + + + notice + 5 + normal but significant conditions + + + info + 6 + informational messages + + + debug + 7 + debug-level messages + + Log Levels +
+

Notice that the integer value is only used internally in + Logger. In the API, you must always use the atom. To compare + the severity of two log levels, + use + logger:compare_levels/2.

+
+
+ + Log Message +

The log message contains the information to be logged. The + message can consist of a format string and arguments (given as + two separate parameters in the Logger API), a string or a + report. The latter, which is either a map or a key-value list, + can be accompanied by a report callback specified in the log + event's metadata. The + report callback is a convenience function that + the formatter can use + to convert the report to a format string and arguments. The + formatter can also use its own conversion function, if no + callback is provided, or if a customized formatting is + desired.

+

Example, format string and arguments:

+ logger:error("The file does not exist: ~ts",[Filename]) +

Example, string:

+ logger:notice("Something strange happened!") +

Example, report, and metadata with report callback:

+ +logger:debug(#{got => connection_request, id => Id, state => State}, + #{report_cb => fun(R) -> {"~p",[R]} end}) +

The log message can also be provided through a fun for lazy + evaluation. The fun is only evaluated if the global log level + check passes, and is therefore recommended if it is expensive + to generate the message. The lazy fun must return a string, a + report, or a tuple with format string and arguments.

+
+
+ Metadata +

Metadata contains additional data associated with a log + message. Logger inserts some metadata fields by default, and + the client can add custom metadata in two different ways:

+ + Set process metadata + +

Process metadata is set and updated + with + logger:set_process_metadata/1 + and + logger:update_process metadata/1, + respectively. This metadata applies to the process on + which these calls are made, and Logger adds the metadata + to all log events issued on that process.

+ + Add metadata to a specifc log event + +

Metadata associated with one specifc log event is given + as the last parameter to the log macro or Logger API + function when the event is issued. For example:

+ ?LOG_ERROR("Connection closed",#{context => server}) + + +

See the description of + the + logger:metadata() type for information + about which default keys Logger inserts, and how the different + metadata maps are merged.

+
+
Filters @@ -166,13 +254,13 @@ discarded. If the filter is global, no handler filters or callbacks are called. If it is a handler filter, the corresponding handler callback is not called, but the log event - is forwarded to the filters attached to the next handler, if + is forwarded to filters attached to the next handler, if any.

If the log event is returned, the next filter function is called with the returned value as the first argument. That is, if a filter function modifies the log event, the next filter - function receivea the modified event. The value returned from - the last filter funcion is the value that the handler callback + function receives the modified event. The value returned from + the last filter function is the value that the handler callback receives.

If the filter function returns ignore, it means that it did not recognize the log event, and thus leaves to other @@ -180,24 +268,21 @@

The configuration option filter_default specifies the behaviour if all filter functions - return ignore. filter_default is by default set - to log, meaning that if all filters ignore a log event, - Logger forwards the event to the handler - callback. If filter_default is set to stop, - Logger discards such events.

- -

Filters are applied in the reverse order of installation, - meaning that the last added filter is applied first.

- + return ignore, or if no filters + exist. filter_default is by default set to log, + meaning that if all existing filters ignore a log event, Logger + forwards the event to the handler + callback. If filter_default is set to stop, Logger + discards such events.

Global filters are added with logger:add_logger_filter/2 and removed with logger:remove_logger_filter/1. They can also - be added at system start via Kernel configuration + be added at system start via the Kernel configuration parameter logger.

-

Handler filters are added with +

Handler filters are added with logger:add_handler_filter/3 and removed @@ -206,7 +291,7 @@ be specified directly in the configuration when adding a handler with logger:add_handler/3 - or via Kernel configuration + or via the Kernel configuration parameter logger.

To see which filters are currently installed in the system, @@ -215,35 +300,37 @@ logger:get_logger_config/0 and logger:get_handler_config/1. Filters are - applied in the order they are listed.

+ listed in the order they are applied, that is, the first + filter in the list is applied first, and so on.

For convenience, the following built-in filters exist:

- - -

- logger_filters:domain/2 provides a way of - filtering log events based on a - domain field Metadata.

- - -

- logger_filters:level/2 provides a way of - filtering log events based on the log level.

- - -

- logger_filters:progress/2 stops or allows - progress reports from supervisor - and application_controller.

- - -

- logger_filters:remote_gl/2 stops or allows - log events originating from a process that has its group - leader on a remote node.

- - + + + logger_filters:domain/2 + +

Provides a way of filtering log events based on a + domain field in Metadata.

+ + + logger_filters:level/2 + +

Provides a way of filtering log events based on the log + level.

+ + + logger_filters:progress/2 + +

Stops or allows progress reports from supervisor + and application_controller.

+ + + logger_filters:remote_gl/2 + +

Stops or allows log events originating from a process + that has its group leader on a remote node.

+ +
@@ -252,19 +339,19 @@

A handler is defined as a module exporting at least the following function:

- 
log(LogEvent, Config)
+ 
log(LogEvent, Config) -> void()

This function is called when a log event has passed through all global filters, and all handler filters attached to the handler in question. The function call is executed on the client process, and it is up to the handler implementation if other - processes are to be involved or not.

+ processes are involved or not.

Logger allows adding multiple instances of a handler - callback. That is, the callback module might be implemented in - such a way that, by using different handler identities, the same - callback module can be used for multiple handler - instances. Handler configuration is per instance.

+ callback. That is, if a callback module implementation allows + it, you can add multiple handler instances using the same + callback module. The different instances are identified by + unique handler identities.

In addition to the mandatory callback function log/2, a handler module can export the optional callback @@ -281,20 +368,19 @@

This is the default handler used by OTP. Multiple instances can be started, and each instance will write log events to a - given destination, console or file. Filters can be used for - selecting which event to send to which handler instance.

+ given destination, terminal or file.

logger_disk_log_h -

This handler behaves much like logger_std_h, except it uses +

This handler behaves much like logger_std_h, except it uses disk_log as its destination.

 error_logger -

This handler is to be used for backwards compatibility +

This handler is provided for backwards compatibility only. It is not started by default, but will be automatically started the first time an error_logger event handler is added @@ -302,7 +388,8 @@ error_logger:add_report_handler/1,2.

The old error_logger event handlers in STDLIB and - SASL still exist, but they are not added by Erlang/OTP.

+ SASL still exist, but they are not added by Erlang/OTP 21.0 + or later.
@@ -312,9 +399,10 @@ Formatters

A formatter can be used by the handler implementation to do the final formatting of a log event, before printing to the - handler's destination. The handler callback gets the formatter - information in the handler configuration, which is passed as the - second argument to + handler's destination. The handler callback receives the + formatter information as part of the handler configuration, + which is passed as the second argument + to HModule:log/2.

The formatter information consits of a formatter module, FModule and its @@ -322,9 +410,23 @@ following function, which can be called by the handler:

format(LogEvent,FConfig)
 	-> FormattedLogEntry
-

See the - logger_formatter(3) manual for the full - description of the default formatter used by Logger.

+

The formatter information for a handler is set as a part of its + configuration when the handler is added. It can also be changed + during runtime + with + logger:set_handler_config(HandlerId,formatter,{FModule,FConfig}) + , which overwrites the current formatter information, + or with + logger:update_formatter_config/2,3, which + only modifies the formatter configuration.

+

If the formatter module exports the optional callback + function + check_config(FConfig), Logger calls this + function when the formatter information is set or modified, to + verify the validity of the formatter configuration.

+

If no formatter information is specified for a handler, Logger + uses + logger_formatter(3) as default.

@@ -335,7 +437,7 @@ or at run-time by using the logger(3) 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 log level.

+ has to be changed at runtime, such as the log level.

Kernel Configuration Parameters @@ -436,9 +538,9 @@ logger:level()

Specifies the global log level to log.

-

See table Log - Levels in the Overview section for a listing - and description of possible log levels.

+

See section Log + Level for a listing and description of + possible log levels.

The initial value of this option is set by the Kernel configuration parameter @@ -465,7 +567,7 @@ filter_default = log | stop

Specifies what to do with an event if all filters - return ignore.

+ return ignore, or if no filters exist.

See section Filters for more information about how this option is used.

Default is log.

@@ -481,9 +583,9 @@ logger:level()

Specifies the log level which the handler logs.

-

See table Log - Levels in the Overview section for a listing - and description of possible log levels.

+

See section Log + Level for a listing and description of + possible log levels.

The log level can be specified when adding the handler, or changed during runtime with, for instance, @@ -509,7 +611,7 @@ filter_default = log | stop

Specifies what to do with an event if all filters - return ignore.

+ return ignore, or if no filters exist.

See section Filters for more information about how this option is used.

Default is log.

@@ -553,14 +655,14 @@
Backwards Compatibility with error_logger -

Logger provides backwards compatibility with the old +

Logger provides backwards compatibility with error_logger in the following ways:

API for Logging -

The old error_logger API still exists, but should - only be used by legacy code. It will be removed in a later +

The error_logger API still exists, but should only + be used by legacy code. It will be removed in a later release.

Calls to @@ -585,7 +687,7 @@

To get log events on the same format as produced by error_logger_tty_h and error_logger_file_h, use the default formatter, logger_formatter, with - configuration parameter legacy_header=>true. This is + configuration parameter legacy_header => true. This is also the default.

 Default Format of Log Events from OTP @@ -608,10 +710,11 @@ configuration parameters.

Due to the specific event handlers, the output format slightly differed from other log events.

-

As of OTP-21, the concept of SASL reports is removed, - meaning that the default behaviour is as follows:

+

As of Erlang/OTP 21.0, the concept of SASL reports is + removed, meaning that the default behaviour is as + follows:

- Supervisor reports, crash reports and progress reports + Supervisor reports, crash reports, and progress reports are no longer connected to the SASL application. Supervisor reports and crash reports are logged by default. @@ -626,15 +729,15 @@ parameter logger_sasl_compatible can be set to true. The - old SASL + SASL configuration parameters can then be used as before, and the SASL reports will only be printed if the SASL application is running, through a second log handler named sasl.

All SASL reports have a metadata - field domain=>[beam,erlang,otp,sasl], which can be + field domain => [beam,erlang,otp,sasl], which can be used, for example, by filters to stop or allow the - events.

+ log events.

See the SASL User's Guide for more information about the old SASL error logging functionality.

@@ -650,14 +753,14 @@ error_logger:add_report_handler/1,2. event manager, and add error_logger as a handler to logger, with configuration

-#{level=>info, - filter_default=>log, - filters=>[]}. +#{level => info, + filter_default => log, + filters => []}.

Notice that this handler will ignore events that do not - originate from the old error_logger API, or from - within OTP. This means that if your code uses the Logger API - for logging, then your log events will be discarded by this + originate from the error_logger API, or from within + OTP. This means that if your code uses the Logger API for + logging, then your log events will be discarded by this handler.

Also notice that error_logger is not overload protected.

@@ -676,8 +779,9 @@ error_logger:add_report_handler/1,2. arguments by the handler. If a report is given, a default report callback can be included in the log event's metadata. The handler can use this callback for converting the report to a - format string and arguments. The handler might also do a custom - conversion if the default format is not desired.

+ format string and arguments. If the format obtained by the + provided callback is not desired, or if there is no provided + callback, the handler must do a custom conversion.

Logger does, to a certain extent, check its input data before forwarding a log event to the handlers, but it does not evaluate conversion funs or check the validity of format strings @@ -686,18 +790,17 @@ error_logger:add_report_handler/1,2. that it does not crash due to bad input data or faulty callbacks.

If a filter or handler still crashes, Logger will remove the - filter or handler in question from the configuration, and then - print a short error message on the console. A debug event - containing the crash reason and other details is also issued, - and can be seen if a handler is installed which logs on debug - level.

+ filter or handler in question from the configuration, and print + a short error message to the terminal. A debug event containing + the crash reason and other details is also issued, and can be + seen if a handler logging debug events is installed.

Example: add a handler to log debug events to file -

When starting an erlang node, the default behaviour is that all +

When starting an Erlang node, the default behaviour is that all log events with level info and above are logged to the - console. In order to also log debug events, you can either + terminal. In order to also log debug events, you can either change the global log level to debug or add a separate handler to take care of this. In this example we will add a new handler which prints the debug events to a separate file.

@@ -705,28 +808,32 @@ error_logger:add_report_handler/1,2. type {file,File}, and we set the handler's level to debug:

-1> Config = #{level=>debug,logger_std_h=>#{type=>{file,"./debug.log"}}}.
+1> Config = #{level => debug, logger_std_h => #{type => {file,"./debug.log"}}}.
 #{logger_std_h => #{type => {file,"./debug.log"}},
   level => debug}
 2> logger:add_handler(debug_handler,logger_std_h,Config).
 ok

By default, the handler receives all events - (filter_defalt=log), so we need to add a filter to stop - all non-debug events:

+ (filter_default=log, see + section Filters for more + details), so we need to add a filter to stop all non-debug + events. The built-in + filter + logger_filters:level/2 + is used for this:

-3> Fun = fun(#{level:=debug}=Log,_) -> Log; (_,_) -> stop end.
-#Fun<erl_eval.12.98642416>
-4> logger:add_handler_filter(debug_handler,allow_debug,{Fun,[]}).
+3> logger:add_handler_filter(debug_handler,stop_non_debug,
+                             {fun logger_filters:level/2,{stop,neq,debug}}).
 ok

And finally, we need to make sure that Logger itself allows debug events. This can either be done by setting the global log level:

-5> logger:set_logger_config(level,debug).
+4> logger:set_logger_config(level,debug).
 ok

Or by allowing debug events from one or a few modules only:

-6> logger:set_module_level(mymodule,debug).
+5> logger:set_module_level(mymodule,debug).
 ok
@@ -736,29 +843,31 @@ ok

The only requirement that a handler MUST fulfill is to export the following function:

log(logger:log_event(),logger:config()) -> ok -

It may also implement the following callbacks:

+

It can optionally also implement the following callbacks:

adding_handler(logger:config()) -> {ok,logger:config()} | {error,term()} removing_handler(logger:config()) -> ok changing_config(logger:config(),logger:config()) -> {ok,logger:config()} | {error,term()} -

When logger:add_handler(Id,Module,Config) is called, Logger - will first call HModule:adding_handler(Config), and if it - returns {ok,NewConfig}, NewConfig is written to the - configuration database. After this, the handler may receive log - events as calls to HModule:log/2.

+

When logger:add_handler(Id,Module,Config) is called, + Logger first calls HModule:adding_handler(Config). If + this function returns {ok,NewConfig}, Logger + writes NewConfig to the configuration database, and + the logger:add_handler/3 call returns. After this, the + handler is installed and must be ready to receive log events as + calls to HModule:log/2.

A handler can be removed by calling - logger:remove_handler(Id). Logger will call - HModule:removing_handler(Config), and then remove the + logger:remove_handler(Id). Logger calls + HModule:removing_handler(Config), and removes the handler's configuration from the configuration database.

When logger:set_handler_config/2,3 - or logger:update_handler_config/2 are called, Logger + or logger:update_handler_config/2 is called, Logger calls HModule:changing_config(OldConfig,NewConfig). If - this function returns {ok,NewConfig}, NewConfig is - written to the configuration database.

+ this function returns {ok,NewConfig}, Logger + writes NewConfig to the configuration database.

-

A simple handler that prints to the console could be - implemented as follows:

+

A simple handler that prints to the terminal can be implemented + as follows:

-module(myhandler). -export([log/2]). @@ -776,7 +885,7 @@ log(LogEvent,#{formatter:={FModule,FConfig}) -> adding_handler(Config) -> {ok,Fd} = file:open(File,[append,{encoding,utf8}]), - {ok,Config#{myhandler_fd=>Fd}}. + {ok,Config#{myhandler_fd => Fd}}. removing_handler(#{myhandler_fd:=Fd}) -> _ = file:close(Fd), @@ -790,10 +899,12 @@ log(LogEvent,#{myhandler_fd:=Fd,formatter:={FModule,FConfig}}) -> protection, and all log events are printed directly from the client process.

-

For examples of overload protection, please refer to the - implementation - of logger_std_h - and logger_disk_log_h +

For information and examples of overload protection, please + refer to + section Protecting the + Handler from Overload, and the implementation + of logger_std_h(3) + and logger_disk_log_h(3) .

Below is a simpler example of a handler which logs through one @@ -805,7 +916,7 @@ log(LogEvent,#{myhandler_fd:=Fd,formatter:={FModule,FConfig}}) -> adding_handler(Config) -> {ok,Pid} = gen_server:start(?MODULE,Config), - {ok,Config#{myhandler_pid=>Pid}}. + {ok,Config#{myhandler_pid => Pid}}. removing_handler(#{myhandler_pid:=Pid}) -> gen_server:stop(Pid). @@ -815,7 +926,7 @@ log(LogEvent,#{myhandler_pid:=Pid} = Config) -> init(#{myhandler_file:=File}) -> {ok,Fd} = file:open(File,[append,{encoding,utf8}]), - {ok,#{file=>File,fd=>Fd}}. + {ok,#{file => File, fd => Fd}}. handle_call(_,_,State) -> {reply,{error,bad_request},State}. @@ -949,7 +1060,7 @@ logger:add_handler(my_standard_h, logger_std_h, both built-in handlers offer the possibility to set a maximum level of how many requests to process with a certain time frame. With this burst control feature enabled, the handler will take care of bursts of log requests - without choking log files, or the console, with massive amounts of + without choking log files, or the terminal, with massive amounts of printouts. These are the configuration parameters:

diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml index ee43634cf9..02f89b26be 100644 --- a/lib/kernel/doc/src/logger_formatter.xml +++ b/lib/kernel/doc/src/logger_formatter.xml @@ -46,97 +46,150 @@ Logger.

-
- Configuration -

The configuration term for logger_formatter is a - map, - and the following keys can be set as configuration - parameters:

- - chars_limit = pos_integer() | unlimited - -

A positive integer representing the value of the option - with the same name to be used when calling - io_lib:format/3. - This value limits the total number of characters printed - for each log event. Notice that this is a soft limit. For a - hard truncation limit, see option max_size.

-

Default is unlimited.

- -

chars_limit has no effect on log messages on - string form. These are expected to be short, but can still - be truncated by the max_size parameter.

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

A positive integer representing the maximum depth to - which terms shall be printed by this formatter. Format - strings passed to this formatter are rewritten. The format - controls ~p and ~w are replaced with ~P and ~W, - respectively, and the value is used as the depth - parameter. For details, see - io:format/2,3 - in STDLIB.

-

Default is unlimited.

- -

depth has no effect on log messages on string - form. These are expected to be short, but can still be - truncated by the max_size parameter.

- - - max_size = pos_integer() | unlimited - -

A positive integer representing the absolute maximum size a - string returned from this formatter can have. If the - formatted string is longer, after possibly being limited - by chars_limit or depth, it is truncated.

-

Default is unlimited.

- - single_line = boolean() - -

If set to true, all newlines in the message are - replaced with ", ", and whitespaces following - directly after newlines are removed. Note that newlines - added by the template parameter are not replaced.

-

Default is true.

- - legacy_header = boolean() - -

If set to true a header field is added to - logger_formatter's part of Metadata. The value of - this field is a string similar to the header created by the - old error_logger event handlers. It can be included - in the log event by adding the - tuple {logger_formatter,header} to the template. See - section Default - Templates for more information.

-

Default is false.

- - report_cb = fun((logger:report()) -> {io:format(),[term()]}) - -

A report callback is used by the formatter to transform log - messages on report form to a format string and - arguments. The report callback can be specified in the - metadata for the log event. If no report callback exist in - metadata, logger_formatter will - use - logger:format_report/1 as default - callback.

-

If this configuration parameter is set, it replaces both - the default report callback, and any report callback found - in metadata. That is, all reports are converted by this - configured function.

-

The value must be a function with arity 1, - returning {Format,Args}, and it will be called with a - report as only argument.

- - template = template() - + + + + + +

The configuration term for logger_formatter is a + map, and the + following keys can be set as configuration parameters:

+ + chars_limit = pos_integer() | unlimited + +

A positive integer representing the value of the option + with the same name to be used when calling + + io_lib:format/3. + This value limits the total number of characters printed + for each log event. Notice that this is a soft limit. For a + hard truncation limit, see option max_size.

+

Defaults to unlimited.

+ +

chars_limit has no effect on log messages on + string form. These are expected to be short, but can + still be truncated by the max_size + parameter.

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

A positive integer representing the maximum depth to + which terms shall be printed by this formatter. Format + strings passed to this formatter are rewritten. The + format controls ~p and ~w are replaced with ~P and ~W, + respectively, and the value is used as the depth + parameter. For details, see + io:format/2,3 + in STDLIB.

+

Defaults to unlimited.

+ +

depth has no effect on log messages on string + form. These are expected to be short, but can still be + truncated by the max_size parameter.

+ + + legacy_header = boolean() + +

If set to true a header field is added to + logger_formatter's part of Metadata. The value of + this field is a string similar to the header created by + the old error_logger event handlers. It can be + included in the log event by adding the + tuple {logger_formatter,header} to the + template. See the description of + the template() + type for more information.

+

Defaults to false.

+ + max_size = pos_integer() | unlimited + +

A positive integer representing the absolute maximum size a + string returned from this formatter can have. If the + formatted string is longer, after possibly being limited + by chars_limit or depth, it is truncated.

+

Defaults to unlimited.

+ + report_cb = fun((logger:report()) -> {io:format(),[term()]}) + +

A report callback is used by the formatter to transform + log messages on report form to a format string and + arguments. The report callback can be specified in the + metadata for the log event. If no report callback exist + in metadata, logger_formatter will + use + logger:format_report/1 as default + callback.

+

If this configuration parameter is set, it replaces + both the default report callback, and any report + callback found in metadata. That is, all reports are + converted by this configured function.

+

The value must be a function with arity 1, + returning {Format,Args}, and it will be called + with a report as only argument.

+ + single_line = boolean() + +

If set to true, all newlines in the message are + replaced with ", ", and whitespaces following + directly after newlines are removed. Note that newlines + added by the template parameter are not replaced.

+

Defaults to true.

+ + template = template() + +

The template describes how the formatted string is + composed by combining different data values from the log + event. See the description of + the template() + type for more information about this.

+ + time_designator = byte() + +

Timestamps are formatted according to RFC3339, and the + time designator is the character used as date and time + separator.

+

Defaults to $T.

+

The value of this parameter is used as + the time_designator option + to + calendar:system_time_to_rcf3339/2.

+ + time_offset = integer() | [byte()] + +

The time offset, either a string or an integer, to be + used when formatting the timestamp.

+

An empty string is interpreted as local time. The + values "Z", "z" or 0 are + interpreted as Universal Coordinated Time (UTC).

+

Strings, other than "Z", "z", + or "", must be on the form ±[hh]:[mm], for + example "-02:00" or "+00:00".

+

Integers must be in microseconds, meaning that the + offset 7200000000 is equivalent + to "+02:00".

+

Defaults to an empty string, meaning that timestamps + are displayed in local time. However, for backwards + compatibility, if the SASL configuration + parameter + utc_log=true, the default is + changed to "Z", meaning that timestamps are displayed + in UTC.

+

The value of this parameter is used as + the offset option + to + calendar:system_time_to_rcf3339/2.

+ + + + + + +

The template is a list of atoms, tuples and strings. The atoms level or msg, are treated as placeholders for the severity level and the log message, - repectively. Other atoms or tuples are interpreted as + respectively. Other atoms or tuples are interpreted as placeholders for metadata, where atoms are expected to match top level keys, and tuples represent paths to sub keys when the metadata is a nested map. For example the @@ -154,120 +207,84 @@

Strings in the template are printed literally.

The default template differs depending on the values of legacy_header - and single_line. See Default - Templates for more information

- - time_designator = byte() - -

Timestamps are formatted according to RFC3339, and the time - designator is the character used as date and time - separator.

-

Default is $T.

-

The value of this parameter is used as - the time_designator option - to - calendar:system_time_to_rcf3339/2.

- - time_offset = integer() | [byte()] - -

The time offset, either a string or an integer, to be - used when formatting the timestamp.

-

An empty string is interpreted as local time. The - values "Z", "z" or 0 are interpreted as - Universal Coordinated Time (UTC).

-

Strings, other than "Z", "z", or "", - must be on the form ±[hh]:[mm], for - example "-02:00" or "+00:00".

-

Integers must be in microseconds, meaning that the - offset 7200000000 is equivalent - to "+02:00".

-

The default value is an empty string, meaning that - timestamps are displayed in local time. However, for - backwards compatibility, if the SASL configuration - parameter - utc_log=true, the default is - changed to "Z", meaning that timestamps are displayed - in UTC.

-

The value of this parameter is used as the offset - option to - calendar:system_time_to_rcf3339/2.

- - -
- -
- - Default templates + and single_line:

-

The default value for the template configuration - parameter depends on the value of single_line - and legacy_header as follows.

+

The default value for the template configuration + parameter depends on the value of the single_line + and legacy_header configuration parameters as + follows.

-

The log event used in the examples is:

- +

The log event used in the examples is:

+ ?LOG_ERROR("name: ~p~nexit_reason: ~p",[my_name,"It crashed"]) - - legacy_header=true, single_line=false - -

Default template: [{logger_formatter,header},"\n",msg,"\n"]

+ + legacy_header=true, single_line=false + +

Default + template: [{logger_formatter,header},"\n",msg,"\n"]

-

Example log entry:

- +

Example log entry:

+ =ERROR REPORT==== 17-May-2018::18:30:19.453447 === name: my_name exit_reason: "It crashed" -

Notice that all eight levels can occur in the heading, - not only ERROR, WARNING or INFO as the - old error_logger produced. And microseconds are - added at the end of the timestamp.

- +

Notice that all eight levels can occur in the heading, + not only ERROR, WARNING or INFO as the + old error_logger produced. And microseconds are + added at the end of the timestamp.

+ - legacy_header=true, single_line=true - -

Default template: [{logger_formatter,header},"\n",msg,"\n"]

+ legacy_header=true, single_line=true + +

Default + template: [{logger_formatter,header},"\n",msg,"\n"]

-

Notice that the template is here the same as - for single_line=false, but the resulting log entry - differs in that there is only one line after the - heading:

- +

Notice that the template is here the same as + for single_line=false, but the resulting log entry + differs in that there is only one line after the + heading:

+ =ERROR REPORT==== 17-May-2018::18:31:06.952665 === name: my_name, exit_reason: "It crashed" - + - legacy_header=false, single_line=true - -

Default template: [time," ",level,": ",msg,"\n"]

+ legacy_header=false, single_line=true + +

Default template: [time," ",level,": ",msg,"\n"]

-

Example log entry:

- +

Example log entry:

+ 2018-05-17T18:31:31.152864+02:00 error: name: my_name, exit_reason: "It crashed" - + - legacy_header=false, single_line=false - -

Default template: [time," ",level,":\n",msg,"\n"]

+ legacy_header=false, single_line=false + +

Default template: [time," ",level,":\n",msg,"\n"]

-

Example log entry:

- +

Example log entry:

+ 2018-05-17T18:32:20.105422+02:00 error: name: my_name exit_reason: "It crashed" - - -
- - - - - + + + + + Validates the given formatter configuration. + +

This callback function is called by Logger when the + formatter configuration for a handler is set or modified. It + returns ok if the configuration is valid, + and {error,term()} if it is faulty.

+ + Formats the given message. @@ -290,7 +307,6 @@ exit_reason: "It crashed" - -- cgit v1.2.3