From b9d2cb688e562d200663bdbedfa65adc5a29aeae Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Fri, 8 Jun 2018 14:18:36 +0200 Subject: [logger] Update documentation --- lib/kernel/doc/src/logger.xml | 883 ++++++++++++++++++++++-------------------- 1 file changed, 472 insertions(+), 411 deletions(-) (limited to 'lib/kernel/doc/src/logger.xml') diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index 911eb158da..7f35a5d752 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -33,73 +33,150 @@ logger.xml logger - API module for logging in Erlang/OTP. + API module for Logger, the standard logging facility + in Erlang/OTP. -

- This module is the main API for logging in Erlang/OTP. It - contains functions that allow applications to use a single log - API and the system to manage those log events independently. Use - the API functions or the log - macros to log events. For instance, - to log a new error event:

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

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

+

This module implements the main API for logging in + Erlang/OTP. To create a log event, use the + API functions or the + log + macros, for example:

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

To configure the Logger backend, + use Kernel configuration + parameters + or configuration + functions in the Logger API.

+ +

By default, the Kernel application installs one log handler at + system start. This handler is named default. It receives + and processes standard log events produced by the Erlang runtime + system, standard behaviours and different Erlang/OTP + applications. The log events are by default printed to the + terminal.

+

If you want your systems logs to be printed to a file instead, + you must 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"}}}}]}]}]. + [{handler, default, logger_std_h, + #{config => #{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 + the Logger facility in general, 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, + the built-in handlers, see logger_std_h and logger_disk_log_h. - what builtin filters are available, + the built-in formatter, + see logger_formatter. + built-in filters, see logger_filters. - + -

The severity level for the message to be logged.

+

Primary configuration data for Logger. The following + default values apply:

+ + level => info + filter_default => log + filters => [] + - + -

+

Handler configuration data for Logger. The following + default values apply:

+ + level => all + filter_default => log + filters => [] + formatter => {logger_formatter, DefaultFormatterConfig} + +

In addition to these, the following fields are + automatically inserted by Logger, values taken from the + two first parameters + to add_handler/3:

+ + id => HandlerId + module => Module + +

Handler specific configuration data is inserted by the + handler callback itself, in a sub structure associated with + the field named config.

+

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

 - + -

+

A filter which can be installed as a handler filter, or as + a primary filter in Logger.

 - + + +

The second argument to the filter fun.

+ + + + + +

A unique identifier for a filter.

+ + + + + +

The return value from the filter fun.

+ + + + + +

Configuration data for the + formatter. See + logger_formatter(3) + for an example of a formatter implementation.

+ + + + + +

A unique identifier for a handler instance.

+ + + + + +

The severity level for the message to be logged.

+ + + +

@@ -117,7 +194,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro

When a log macro is used, Logger also inserts location information:

- mfa => {?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY} + mfa => {?MODULE, ?FUNCTION_NAME, ?FUNCTION_ARITY} file => ?FILE line => ?LINE @@ -158,51 +235,15 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro - - -

Configuration data for the logger part of Logger, or for a handler.

-

The following default values apply:

- - level => info - filter_default => log - filters => [] - formatter => {logger_formatter,DefaultFormatterConfig} - -

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

- - - - - -

A unique identifier for a handler instance.

- - - - - -

A unique identifier for a filter.

- - - - - -

A filter which can be installed for the logger part of - Logger, or for a handler.

- - - - + -

The second argument to the filter fun.

+

- + -

The return value from the filter fun.

+

@@ -213,15 +254,6 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro erlang:system_time(microsecond).

 - - - -

Configuration data for the - formatter. See - logger_formatter(3) - for an example of a formatter implementation.

- -
@@ -258,6 +290,10 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro level.

+
+ + Logging API functions +
emergency(StringOrReport[,Metadata]) @@ -317,7 +353,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro notice(StringOrReport[,Metadata]) notice(Format,Args[,Metadata]) - notice(Fun,FunArgs[,Metadata]) + notice(Fun,FunArgs[,Metadata]) Logs the given message as level notice.

Equivalent to @@ -366,136 +402,21 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro

Log the given message.

 + +
+ + Configuration API functions +
+ - - Look up the current configuration for the logger part - of Logger. - -

Look up the current configuration for the logger part of - Logger.

- - - - - - Look up the current configuration for the given - handler. - -

Look up the current configuration for the given handler.

- - - - - - Get all Logger configurations - -

Same as logger:i(term)

- - - - - - - - Get all Logger configurations - -

Display or return all current Logger configurations.

- - Action = string - -

Return the pretty printed current Logger configuration - as iodata.

- - Action = term - -

Return the current Logger configuration as a term. The - format of this term may change between releases. For a - stable format use - logger:get_handler_config/1 - and - logger:get_logger_config/0.

-

The same as calling logger:i().

- - Action = print - -

Pretty print all the current Logger configuration to - standard out. Example:

- logger:i(print). -Current logger configuration: - Level: info - Filter Default: log - Filters: - Handlers: - Id: default - Module: logger_std_h - Level: info - Formatter: - Module: logger_formatter - Config: #{legacy_header => true,single_line => false, - template => [{logger_formatter,header},"\n",msg,"\n"]} - Filter Default: stop - Filters: - Id: stop_progress - Fun: fun logger_filters:progress/2 - Config: stop - Id: remote_gl - Fun: fun logger_filters:remote_gl/2 - Config: stop - Id: domain - Fun: fun logger_filters:domain/2 - Config: {log,super,[beam,erlang,otp,sasl]} - Id: no_domain - Fun: fun logger_filters:domain/2 - Config: {log,undefined,[]} - Handler Config: - logger_std_h: #{type => standard_io} - Level set per module: - Module: my_module - Level: debug]]> - - - - - - - - Add a filter to the logger part of Logger. + + Add a handler with the given configuration. -

Add a filter to the logger part of Logger.

-

The filter fun is called with the log event as the first - parameter, and the specified filter_args() as the - second parameter.

-

The return value of the fun specifies if a log event is to - be discarded or forwarded to the handlers:

- - log_event() - -

The filter passed. The next logger filter, if - any, is applied. If no more logger filters exist, the - log event is forwarded to the handler part of Logger, - where handler filters are applied.

- - stop - -

The filter did not pass, and the log event is - immediately discarded.

- - ignore - -

The filter has no knowledge of the log event. The next - logger filter, if any, is applied. If no more logger - filters exist, the value of the filter_default - configuration parameter for the logger part specifies if - the log event shall be discarded or forwarded to the - handler part.

- - -

See section - Filters in the User's Guide for more information - about filters.

-

Some built-in filters exist. These are defined - in logger_filters.

+

Add a handler with the given configuration.

+

HandlerId is a unique identifier which + must be used in all subsequent calls referring to this + handler.

 @@ -540,99 +461,13 @@ Current logger configuration: - - - Remove a filter from the logger part of Logger. - -

Remove the filter identified - by FilterId from the logger part of Logger.

- - - - - - Remove a filter from the specified handler. - -

Remove the filter identified - by FilterId from the handler identified - by HandlerId.

- - - - - - Add a handler with the given configuration. - -

Add a handler with the given configuration.

-

HandlerId is a unique identifier which - must be used in all subsequent calls referring to this - handler.

- - - - - - Remove the handler with the specified identity. - -

Remove the handler identified by HandlerId.

- - - - - - Set the log level for the specified module. - -

Set the log level for the - specified Module.

-

The log level for a module overrides the global log level - of Logger for log events originating from the module in - question. Notice, however, that it does not override the - level configuration for any handler.

-

For example: Assume that the global log level for Logger - is info, and there is one handler, h1, with - level info and one handler, h2, with - level debug.

-

With this configuration, no debug messages will be logged, - since they are all stopped by the global log level.

-

If the level for mymodule is now set - to debug, then debug events from this module will be - logged by the handler h2, but not by - handler h1.

-

Debug events from other modules are still not logged.

-

To change the global log level for Logger, use - - logger:set_logger_config(level,Level).

-

To change the log level for a handler, use - - logger:set_handler_config(HandlerId,level,Level).

- -

The originating module for a log event is only detected - if mfa=>{Module,Function,Arity} exists in the - metadata. When log macros are used, this association is - automatically added to all log events. If an API function - is called directly, without using a macro, the logging - client must explicitly add this information if module - levels shall have any effect.

- - - - - - - Remove a module specific log setting. - -

Remove a module specific log setting. After this, the - global log level is used for the specified module.

- - - Set up log handlers from the application's configuration parameters.

Reads the application configuration parameter logger and - calls logger:add_handlers/1 with its contents.

+ calls add_handlers/1 with its contents.

 @@ -670,61 +505,158 @@ start(_, []) -> [{kernel, [{logger, %% Disable the default Kernel handler - [{handler,default,undefined}]}]}, + [{handler, default, undefined}]}]}, {my_app, [{logger, %% Enable this handler as the default - [{handler,default,my_handler,#{}}]}]}]. + [{handler, default, my_handler, #{}}]}]}]. - - Set configuration data for the logger part of Logger. + + Add a primary filter to Logger. -

Set configuration data for the logger part of Logger. This - overwrites the current logger configuration.

-

To modify the existing configuration, - use - update_logger_config/1, or, if a more - complex merge is needed, read the current configuration - with get_logger_config/0 - , then do the merge before writing the new - configuration back with this function.

-

If a key is removed compared to the current configuration, - the default value is used.

+

Add a primary filter to Logger.

+

The filter fun is called with the log event as the first + parameter, and the specified filter_args() as the + second parameter.

+

The return value of the fun specifies if a log event is to + be discarded or forwarded to the handlers:

+ + log_event() + +

The filter passed. The next primary filter, if + any, is applied. If no more primary filters exist, the + log event is forwarded to the handler part of Logger, + where handler filters are applied.

+ + stop + +

The filter did not pass, and the log event is + immediately discarded.

+ + ignore + +

The filter has no knowledge of the log event. The next + primary filter, if any, is applied. If no more primary + filters exist, the value of the + primary filter_default configuration parameter + specifies if the log event shall be discarded or + forwarded to the handler part.

+ + +

See section + Filters in the User's Guide for more information + about filters.

+

Some built-in filters exist. These are defined + in logger_filters.

 - - Add or update configuration data for the logger part - of Logger. + + Look up the current Logger configuration -

Add or update configuration data for the logger part of - Logger. If the given Key already exists, - its associated value will be changed - to Value. If it does not exist, it will - be added.

+

Look up all current Logger configuration, including primary + and handler configuration, and module level settings.

 - - Update configuration data for the logger part of - Logger. + + Look up the current configuration for all handlers. -

Update configuration data for the logger part of - Logger. This function behaves as if it was implemented as - follows:

- -{ok,Old} = logger:get_logger_config(), -logger:set_logger_config(maps:merge(Old,Config)). - -

To overwrite the existing configuration without any merge, - use set_logger_config/1 - .

+

Look up the current configuration for all handlers.

+ + + + + + Look up the current configuration for the given + handler. + +

Look up the current configuration for the given handler.

+ + + + + + Look up the identities for all installed handlers. + +

Look up the identities for all installed handlers.

+ + + + + + Look up the current primary configuration for Logger. + +

Look up the current primary configuration for Logger.

+ + + + + + Look up all current module levels. + +

Look up all current module levels. Returns a list + containing one {Module,Level} element for each module + for which the module level was previously set + with + set_module_level/2.

+ + + + + + Look up the current level for the given modules. + +

Look up the current level for the given modules. Returns a + list containing one {Module,Level} element for each + of the given modules for which the module level was + previously set with + set_module_level/2.

+ + + + + + Retrieve data set with set_process_metadata/1. + +

Retrieve data set + with + set_process_metadata/1 or + + update_process_metadata/1.

+ + + + + + Remove the handler with the specified identity. + +

Remove the handler identified by HandlerId.

+ + + + + + Remove a filter from the specified handler. + +

Remove the filter identified + by FilterId from the handler identified + by HandlerId.

+ + + + + + Remove a primary filter from Logger. + +

Remove the primary filter identified + by FilterId from Logger.

 @@ -763,18 +695,122 @@ logger:set_logger_config(maps:merge(Old,Config)). - - Update configuration data for the specified handler. + + Set primary configuration data for Logger. -

Update configuration data for the specified handler. This function - behaves as if it was implemented as follows:

- -{ok,{_,Old}} = logger:get_handler_config(HandlerId), -logger:set_handler_config(HandlerId,maps:merge(Old,Config)). - -

To overwrite the existing configuration without any merge, - use set_handler_config/2 +

Set primary configuration data for Logger. This + overwrites the current configuration.

+

To modify the existing configuration, + use + update_primary_config/1, or, if a more + complex merge is needed, read the current configuration + with get_primary_config/0 + , then do the merge before writing the new + configuration back with this function.

+

If a key is removed compared to the current configuration, + the default value is used.

+ + + + + + Add or update primary configuration data for Logger. + +

Add or update primary configuration data for Logger. If the + given Key already exists, its associated + value will be changed to Value. If it + does not exist, it will be added.

+ + + + + + Set the log level for the specified modules. + +

Set the log level for the + specified modules.

+

The log level for a module overrides the primary log level + of Logger for log events originating from the module in + question. Notice, however, that it does not override the + level configuration for any handler.

+

For example: Assume that the primary log level for Logger + is info, and there is one handler, h1, with + level info and one handler, h2, with + level debug.

+

With this configuration, no debug messages will be logged, + since they are all stopped by the primary log level.

+

If the level for mymodule is now set + to debug, then debug events from this module will be + logged by the handler h2, but not by + handler h1.

+

Debug events from other modules are still not logged.

+

To change the primary log level for Logger, use + + set_primary_config(level, Level).

+

To change the log level for a handler, use + + set_handler_config(HandlerId, level, Level) .

+ +

The originating module for a log event is only detected + if the key mfa exists in the metadata, and is + associated with {Module, Function, Arity}. When log + macros are used, this association is automatically added + to all log events. If an API function is called directly, + without using a macro, the logging client must explicitly + add this information if module levels shall have any + effect.

+ + + + + + + Set metadata to use when logging from current process. + +

Set metadata which Logger shall automatically insert in + all log events produced on the current process.

+

Location data produced by the log macros, and/or metadata + given as argument to the log call (API function or macro), + are merged with the process metadata. If the same keys + occur, values from the metadata argument to the log call + overwrite values from the process metadata, which in turn + overwrite values from the location data.

+

Subsequent calls to this function overwrites previous data + set. To update existing data instead of overwriting it, + see + update_process_metadata/1.

+ + + + + + Remove module specific log settings for all modules. + +

Remove module specific log settings. After this, the + primary log level is used for all modules.

+ + + + + + Remove module specific log settings for the given + modules. + +

Remove module specific log settings. After this, the + primary log level is used for the specified modules.

+ + + + + + Delete data set with set_process_metadata/1. + +

Delete data set + with + set_process_metadata/1 or + + update_process_metadata/1.

 @@ -786,9 +822,10 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).

The new configuration is merged with the existing formatter configuration.

To overwrite the existing configuration without any merge, - use - set_handler_config(HandlerId,formatter, - {FormatterModule,FormatterConfig}).

+ use

+ 
+set_handler_config(HandlerId, formatter,
+	      {FormatterModule, FormatterConfig}).
@@ -797,39 +834,41 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)). Update the formatter configuration for the specified handler.

Update the formatter configuration for the specified handler.

-

This is equivalent - to
- update_formatter_config(HandlerId,#{Key=>Value})

+

This is equivalent to

+ 
+update_formatter_config(HandlerId, #{Key => Value})
 - - Compare the severity of two log levels. + + Update configuration data for the specified handler. -

Compare the severity of two log levels. Returns gt - if Level1 is more severe than - Level2, lt if Level1 is less severe, - and eq if the levels are equal.

+

Update configuration data for the specified handler. This function + behaves as if it was implemented as follows:

+ +{ok, {_, Old}} = logger:get_handler_config(HandlerId), +logger:set_handler_config(HandlerId, maps:merge(Old, Config)). + +

To overwrite the existing configuration without any merge, + use set_handler_config/2 + .

 - - Set metadata to use when logging from current process. + + Update primary configuration data for Logger. -

Set metadata which Logger shall automatically insert in - all log events produced on the current process.

-

Location data produced by the log macros, and/or metadata - given as argument to the log call (API function or macro), - are merged with the process metadata. If the same keys - occur, values from the metadata argument to the log call - overwrite values from the process metadata, which in turn - overwrite values from the location data.

-

Subsequent calls to this function overwrites previous data - set. To update existing data instead of overwriting it, - see - update_process_metadata/1.

+

Update primary configuration data for Logger. This function + behaves as if it was implemented as follows:

+ +Old = logger:get_primary_config(), +logger:set_primary_config(maps:merge(Old, Config)). + +

To overwrite the existing configuration without any merge, + use set_primary_config/1 + .

 @@ -843,7 +882,7 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).

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 @@ -851,48 +890,44 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). .

+ +
+ + Miscellaneous API functions +
+ - - Retrieve data set with set_process_metadata/1. - -

Retrieve data set - with - set_process_metadata/1 or - - update_process_metadata/1.

- - - - - - Delete data set with set_process_metadata/1. + + Compare the severity of two log levels. -

Delete data set - with - set_process_metadata/1 or - - update_process_metadata/1.

+

Compare the severity of two log levels. Returns gt + if Level1 is more severe than + Level2, lt if Level1 is less severe, + and eq if the levels are equal.

 - Convert a log message on report form to {Format,Args}. + Convert a log message on report form to {Format, Args}. -

Convert a log message on report form to {Format,Args}.

-

This is the default report callback used +

Convert a log message on report form to {Format, + Args}. This is the default report callback used by logger_formatter when no custom report - callback is found.

+ callback is found. See + section Log + Message in the Kernel User's Guide for + information about report callbacks and valid forms of log + messages.

The function produces lines of Key: Value from key-value lists. Strings are printed with ~ts and other terms with ~tp.

-

If the Report is a map, it is - converted to a key-value list before formatting as such.

+

If Report is a map, it is converted to + a key-value list before formatting as such.

 -
@@ -904,11 +939,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). - HModule:adding_handler(Config1) -> {ok,Config2} | {error,Reason} + HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason} An instance of this handler is about to be added. Config1 = Config2 = - config() + handler_config() Reason = term() @@ -928,11 +963,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). - HModule:changing_config(Config1,Config2) -> {ok,Config3} | {error,Reason} + HModule:changing_config(Config1, Config2) -> {ok, Config3} | {error, Reason} The configuration for this handler is about to change. Config1 = Config2 = Config3 = - config() + handler_config() Reason = term() @@ -952,17 +987,17 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). - HModule:log(LogEvent,Config) -> void() + HModule:log(LogEvent, Config) -> void() Log the given log event. LogEvent = log_event() Config = - config() + handler_config()

This callback function is mandatory.

-

The function is called when all global filters and all +

The function is called when all primary filters and all handler filters for the handler in question have passed for the given log event.

The handler identity is associated with the id key @@ -978,7 +1013,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). The given handler is about to be removed. Config = - config() + handler_config()

This callback function is optional.

@@ -1002,18 +1037,30 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). - FModule:check_config(FConfig) -> ok | {error,term()} + FModule:check_config(FConfig) -> ok | {error, Reason} Validate the given formatter configuration. FConfig = formatter_config() + Reason = term()

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.

+ is correct, and {error,Reason} if it is faulty.

+

The following Logger API functions can trigger this callback:

+ + + logger:add_handler/3 + + logger:set_handler_config/2,3 + + logger:updata_handler_config/2 + + logger:update_formatter_config/2 +

See logger_formatter(3) for an example implementation. logger_formatter is the @@ -1021,7 +1068,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). - FModule:format(LogEvent,FConfig) -> FormattedLogEntry + FModule:format(LogEvent, FConfig) -> FormattedLogEntry Format the given log event. LogEvent = @@ -1045,6 +1092,20 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)). + +

+ See Also +

+ config(4), + erlang(3), + io(3), + logger_disk_log_h(3), + logger_filters(3), + logger_formatter(3), + logger_std_h(3), + unicode(3) +

+
-- cgit v1.2.3