Kernel

Reference Manual

Version 6.0

Table of Contents

logger

Module

logger

Module Summary

API module for the logger application.

Description

Data Types

level() =
    emergency |
    alert |
    critical |
    error |
    warning |
    notice |
    info |
    debug

The severity level for the message to be logged.

log() =
    #{level => level(),
      msg =>
          {io:format(), [term()]} |
          {report, report()} |
          {string, unicode:chardata()},
      meta => metadata()}

report() = map() | [{atom(), term()}]

msg_fun() =
    fun((term()) ->
            {io:format(), [term()]} |
            report() |
            unicode:chardata())

metadata() = map()

Metadata associated with the message to be logged.

config() = map()

handler_id() = atom()

filter_id() = atom()

filter() = {fun((log(), term()) -> filter_return()), term()}

filter_return() = stop | ignore | log()

Macros

The following macros are defined:

  • ?LOG_EMERGENCY(StringOrReport[,Metadata])
  • ?LOG_EMERGENCY(FunOrFormat,Args[,Metadata])
  • ?LOG_ALERT(StringOrReport[,Metadata])
  • ?LOG_ALERT(FunOrFormat,Args[,Metadata])
  • ?LOG_CRITICAL(StringOrReport[,Metadata])
  • ?LOG_CRITICAL(FunOrFormat,Args[,Metadata])
  • ?LOG_ERROR(StringOrReport[,Metadata])
  • ?LOG_ERROR(FunOrFormat,Args[,Metadata])
  • ?LOG_WARNING(StringOrReport[,Metadata])
  • ?LOG_WARNING(FunOrFormat,Args[,Metadata])
  • ?LOG_NOTICE(StringOrReport[,Metadata])
  • ?LOG_NOTICE(FunOrFormat,Args[,Metadata])
  • ?LOG_INFO(StringOrReport[,Metadata])
  • ?LOG_INFO(FunOrFormat,Args[,Metadata])
  • ?LOG_DEBUG(StringOrReport[,Metadata])
  • ?LOG_DEBUG(FunOrFormat,Args[,Metadata])

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}

The call is wrapped in a case statement and will be evaluated only if Level is equal to or below the configured log level.

Exports

Equivalent to log(emergency,...).

Equivalent to log(alert,...).

Equivalent to log(critical,...).

Equivalent to log(error,...).

Equivalent to log(warning,...).

Equivalent to log(notice,...).

Equivalent to log(info,...).

Equivalent to log(debug,...).

log(Level, StringOrReport) -> ok
log(Level, StringOrReport, Metadata) -> ok
log(Level, Format, Args) -> ok
log(Level, Fun, FunArgs) -> ok
log(Level, Format, Args, Metadata) -> ok
log(Level, Fun, FunArgs, Metadata) -> ok

Types

Level = level()
StringOrReport = unicode:chardata() | report()
Format = io:format()
Args = [term()]
Fun = msg_fun()
FunArgs = term()
Metadata = metadata()

Log the given message.

get_logger_config() -> {ok, Config}

Types

Config = config()

Lookup the current configuration for logger.

get_handler_config(HandlerId) ->
                      {ok, {Module, Config}} | {error, term()}

Types

HandlerId = handler_id()
Module = module()
Config = config()

Lookup the current configuration for the given handler.

i() ->
     #{logger => config(),
       handlers => [{handler_id(), module(), config()}],
       module_levels => [{module(), level()}]}

Same as logger:i(term)

i(Action :: term) ->
     #{logger => config(),
       handlers => [{handler_id(), module(), config()}],
       module_levels => [{module(), level()}]}
i(Action :: print) -> ok
i(Action :: string) -> iolist()

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

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 logger:get_handler_config/1 and logger:get_logger_config/0. The same as calling logger:i().
print
Pretty print all the current logger configuration to standard out. Example:
1> logger:i().
Current logger configuration:
  Level: info
  FilterDefault: log
  Filters:
  Handlers:
    Id: logger_std_h
      Module:    logger_std_h
      Level:     info
      Formatter:
        Module: logger_formatter
        Config: #{template => [{logger_formatter,header},"\n",msg,"\n"],
                  legacy_header => true}
      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,prefix_of,[beam,erlang,otp,sasl]}
        Id: no_domain
          Fun:    fun logger_filters:domain/2
          Config: {log,no_domain,[]}
      Handler Config:
        logger_std_h: #{type => standard_io}
  Level set per module:
    Module: my_module
      Level:    debug

add_logger_filter(FilterId, Filter) -> ok | {error, term()}

Types

FilterId = filter_id()
Filter = filter()

Add a filter to the logger.

add_handler_filter(HandlerId, FilterId, Filter) ->
                      ok | {error, term()}

Types

HandlerId = handler_id()
FilterId = filter_id()
Filter = filter()

Add a filter to the specified handler.

remove_logger_filter(FilterId) -> ok | {error, term()}

Types

FilterId = filter_id()

Remove the filter with the specified identity from the logger.

remove_handler_filter(HandlerId, FilterId) -> ok | {error, term()}

Types

HandlerId = handler_id()
FilterId = filter_id()

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

add_handler(HandlerId, Module, Config) -> ok | {error, term()}

Types

HandlerId = handler_id()
Module = module()
Config = config()

Add a handler with the given configuration.

remove_handler(HandlerId) -> ok | {error, term()}

Types

HandlerId = handler_id()

Remove the handler with the specified identity.

set_module_level(Module, Level) -> ok | {error, term()}

Types

Module = module()
Level = level()

Set the log level for the specified module.

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

reset_module_level(Module) -> ok | {error, term()}

Types

Module = module()

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

set_logger_config(Config) -> ok | {error, term()}
set_logger_config(Key, Value) -> ok | {error, term()}

Types

Key = atom()
Value = term()

Add or update configuration data for the logger.

set_handler_config(HandlerId, Config) -> ok | {error, term()}
set_handler_config(HandlerId, Key, Value) -> ok | {error, term()}

Types

HandlerId = handler_id()
Key = atom()
Value = term()

Add or update configuration data for the specified handler.

compare_levels(Level1, Level2) -> eq | gt | lt

Types

Level1 = Level2 = level()

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.

set_process_metadata(Meta) -> ok

Types

Meta = metadata()

Set metadata which logger automatically inserts it 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.

get_process_metadata() -> Meta | undefined

Types

Meta = metadata()

Retrieve data set with set_process_metadata/1.

unset_process_metadata() -> ok

Delete data set with set_process_metadata/1.