From 6f49591e7d5bf11d8bfc6014a0711ae59e3f3c33 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Tue, 8 May 2018 14:36:37 +0200 Subject: Update reference manuals for logger --- lib/kernel/doc/src/logger.xml | 371 +++++++++++++++++++++++++++++++++++------- 1 file changed, 312 insertions(+), 59 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 2f7feb5eef..d901454e62 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -67,37 +67,86 @@ -

Metadata associated with the message to be logged.

+

Metadata for the log event.

+

Logger adds the following metadata to each log event:

+ + pid => self() + gl => group_leader() + time => erlang:monotonic_time(microsecond) + +

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

+ + mfa => {?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY} + file => ?FILE + line => ?LINE + +

You can add custom metadata, either by specifying a map as + the last parameter to any of the log macros or the API + functions, or by setting process metadata + with + set_process_metadata/1 + or + update_process_metadata/1.

+

Logger merges all the metadata maps before forwarding the + log event to the handlers. If the same keys occur, values + from the log call overwrites process metadata, which in turn + overwrites values set by Logger.

 -

+

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 logger or for a handler.

+ + + + + +

The second argument to the filter fun.

 -

+

The return value from the filter fun.

+ + + + + +

A timestamp produced + with + erlang:monotonic_time(microsecond).

 @@ -126,14 +175,10 @@

All macros expand to a call to logger, where Level is - taken from the macro name, and the following metadata is added, - or merged with the given Metadata:

- - -#{mfa=>{?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY}, - file=>?FILE, - line=>?LINE} - + taken from the macro name, and location data is added. See the + description of + the metadata() + type for more information about the location data.

The call is wrapped in a case statement and will be evaluated only if Level is equal to or below the configured log @@ -267,7 +312,7 @@ - Get information about all logger configurations + Get all logger configurations

Same as logger:i(term)

@@ -277,26 +322,29 @@ - Get information about all logger configurations + Get all logger configurations -

The logger:i/1 function can be used to get all - current logger configuration. The way that the information - is returned depends on the Action

+

Display or return all current logger configuration.

- string - Return the pretty printed current logger configuration - as iodata. - term - Return the current logger configuration as a term. The - format of this term may change inbetween releases. For a - stable format use + 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 inbetween releases. For a + stable format use logger:get_handler_config/1 - and + and logger:get_logger_config/0. - The same as calling logger:i(). - print - Pretty print all the current logger configuration to - standard out. Example: + 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 @@ -339,6 +387,39 @@ Current logger configuration: Add a filter to the logger.

Add a filter to the 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() + +

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 the + 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 specifies if the + log event shall be discarded or forwarded to the handler + part.

+ + +

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

+

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

 @@ -347,6 +428,39 @@ Current logger configuration: Add a filter to the specified handler.

Add a filter to the specified handler.

+

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 handler callback:

+ + log() + +

The filter passed. The next handler filter, if + any, is applied. If no more filters exist for this + handler, the log event is forwarded to the handler + callback.

+ + 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 + handler filter, if any, is applied. If no more filters + exist for this handler, the value of + the filter_default configuration parameter for + the handler specifies if the log event shall be + discarded or forwarded to the handler callback.

+ + +

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

+

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

 @@ -354,7 +468,8 @@ Current logger configuration: Remove a filter from the logger. -

Remove the filter with the specified identity from the logger.

+

Remove the filter identified + by FilterId from the logger.

 @@ -362,7 +477,9 @@ Current logger configuration: Remove a filter from the specified handler. -

Remove the filter with the specified identity from the given handler.

+

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

 @@ -371,6 +488,9 @@ Current logger configuration: 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 reffering to this + handler.

 @@ -378,7 +498,7 @@ Current logger configuration: Remove the handler with the specified identity. -

Remove the handler with the specified identity.

+

Remove the handler identified by HandlerId.

 @@ -386,10 +506,37 @@ Current logger configuration: Set the log level for the specified module. -

Set the log level for the specified module.

-

To change the logging level globally, use - logger:set_logger_config(level, Level). -

+

Set the log level for the + specified Module.

+

The log level for a module overrides the global log level + of the logger for log event 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 the + 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 set 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 the 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 the logger API + is called directly, without using a macro, the logging + client must explicitly add this information.

+ @@ -414,6 +561,8 @@ Current logger configuration: with get_logger_config/0 , then merge in your added or updated associations before writing it back.

+

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

 @@ -423,7 +572,7 @@ Current logger configuration:

Add or update configuration data for the logger. If the given Key already exists, its associated - value will be set to Value. If it + value will be changed to Value. If it doesn't exist, it will be added.

 @@ -440,6 +589,11 @@ Current logger configuration: with get_handler_config/1 , then merge in your added or updated associations before writing it back.

+

If a key is removed compared to the current configuration, + and the key is know by Logger, the default value is used. If + it is a custom key, then it is up to the handler + implementation if the value is removed or a default value is + inserted.

@@ -449,10 +603,10 @@ Current logger configuration: handler.

Add or update configuration data for the specified - handler. If the - given Key already exists, its associated - value will be set to Value. If it - doesn't exist, it will be added.

+ handler. If the given Key already + exists, its associated value will be changed + to Value. If it doesn't exist, it will + be added.

 @@ -471,30 +625,36 @@ Current logger configuration: Set metadata to use when logging from current process. -

Set metadata which logger automatically inserts in - all log events produced on the current process. Subsequent - calls will overwrite previous data set by this function.

-

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

+

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 metadata to use when logging from current process. + Set or update metadata to use when logging from + current process. -

Update metadata to use when logging from current process

-

This function behaves as if it was implemented as follows:

+

Set or update metadata to use when logging from current + process

+

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

If no process metadata exists, the function behaves as - set_process_metadata/1 + + set_process_metadata/1 .

 @@ -505,7 +665,9 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta))

Retrieve data set with - set_process_metadata/1.

+ set_process_metadata/1 or + + update_process_metadata/1.

 @@ -515,12 +677,103 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta))

Delete data set with - set_process_metadata/1.

+ set_process_metadata/1 or + + update_process_metadata/1.

+ + + + + + 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 + by + logger_formatter when no custom report + callback is found.

+

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.

 +
+ Callback Functions +

The following functions are to be exported from a handler + callback module.

+
+ + + + Module:adding_handler(HandlerId,Config1) -> {ok,Config2} | {error,Reason} + An instance of this handler is about to be added. + + HandlerId = + handler_id() + Config1 = Config2 = + config() + Reason = term() + + +

This callback function is optional.

+

The function is called when an new handler is about to be + added, and the purpose is to verify the configuration and + initiate all resourced needed by the handler.

+

If everything succeeds, the callback function can add + possible default values or internal state values to the + configuration, and return the adjusted map + in {ok,Config2}.

+

If the configuration is faulty, or if the initiation fails, + the callback function must return {error,Reason}.

+ + + + + Module:removing_handler(HandlerId,Config) -> ok + The given handler is about to be removed. + + HandlerId = + handler_id() + Config = + config() + + +

This callback function is optional.

+

The function is called when a handler is about to be + removed, and the purpose is to release all resources used by + the handler. The return value is ignored by Logger.

+ + + + + Module:changing_config(HandlerId,Config1,Config2) -> {ok,Config3} | {error,Reason} + The configuration for this handler is about to change. + + HandlerId = + handler_id() + Config1 = Config2 = Config3 = + config() + Reason = term() + + +

This callback function is optional.

+

The function is called when the configuration for a handler + is about to change, and the purpose is to verify and act on + the new configuration.

+

Config1 is the existing configuration + and Config2 is the new configuration.

+

If everything succeeds, the callback function must return a + possibly adjusted configuration in {ok,Config3}.

+

If the configuration is faulty, the callback function must + return {error,Reason}.

+ + + -- cgit v1.2.3