logger - API module for Logger, the standard logging facility

filter() =
           {fun((log_event(), filter_arg()) -> filter_return()),
            filter_arg()}

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

       filter_arg() = term()

              The second argument to the filter fun.

       filter_id() = atom()

              A unique identifier for a filter.

       filter_return() = stop | ignore | log_event()

              The return value from the filter fun.

       formatter_config() = #{atom() => term()}

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

       handler_config() =
           #{id => handler_id(),
             config => term(),
             level => level() | all | none,
             module => module(),
             filter_default => log | stop,
             filters => [{filter_id(), filter()}],
             formatter => {module(), formatter_config()}}

              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

              These are read-only and cannot be changed in runtime.

              Handler specific configuration data is inserted by the handler callback itself, in a sub structure
              associated  with  the  field  named config. See the logger_std_h(3erl) and logger_disk_log_h(3erl)
              manual pages for information about the specific configuration for these handlers.

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

       handler_id() = atom()

              A unique identifier for a handler instance.

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

              The severity level for the message to be logged.

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

       metadata() =
           #{pid => pid(),
             gl => pid(),
             time => timestamp(),
             mfa => {module(), atom(), integer() >= 0},
             file => file:filename(),
             line => integer() >= 0,
             domain => [atom()],
             report_cb => report_cb(),
             atom() => term()}

              Metadata for the log event.

              Logger adds the following metadata to each log event:

                * pid=>self()

                * gl=>group_leader()

                * time=>logger:timestamp()

              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 logger API functions.

                * setting process metadata with set_process_metadata/1 or update_process_metadata/1.

                * setting  primary  metadata  with  set_primary_config/1  or  through  the  kernel configuration
                  parameter  logger_metadata

          Note:
              When adding custom metadata, make sure not to use any of the keys  mentioned  above  as  that  may
              cause a lot of confusion about the log events.

              Logger  merges  all the metadata maps before forwarding the log event to the handlers. If the same
              keys occur, values from the log call overwrite process  metadata,  which  overwrites  the  primary
              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, or directly to a
                  string. See the type definition of report_cb(), and section Log Message in  the  User's  Guide
                  for more information about report callbacks.

       msg_fun() =
           fun((term()) ->
                   msg_fun_return() | {msg_fun_return(), metadata()})

       msg_fun_return() =
           {io:format(), [term()]} |
           report() |
           unicode:chardata() |
           ignore

       olp_config() =
           #{sync_mode_qlen => integer() >= 0,
             drop_mode_qlen => integer() >= 1,
             flush_qlen => integer() >= 1,
             burst_limit_enable => boolean(),
             burst_limit_max_count => integer() >= 1,
             burst_limit_window_time => integer() >= 1,
             overload_kill_enable => boolean(),
             overload_kill_qlen => integer() >= 1,
             overload_kill_mem_size => integer() >= 1,
             overload_kill_restart_after => integer() >= 0 | infinity}

       primary_config() =
           #{level => level() | all | none,
             metadata => metadata(),
             filter_default => log | stop,
             filters => [{filter_id(), filter()}]}

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

                * level=>info

                * filter_default=>log

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

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

              A  fun  which  converts  a report() to a format string and arguments, or directly to a string. See
              section Log Message in the User's Guide for more information.

       report_cb_config() =
           #{depth := integer() >= 1 | unlimited,
             chars_limit := integer() >= 1 | unlimited,
             single_line := boolean()}

       timestamp() = integer()

              A timestamp produced with logger:timestamp().

       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,
             #{config => #{file => "path/to/file.log"}}}]}]}].

       For more information about:

         * the Logger facility in general, see the User's Guide.

         * how to configure Logger, see the Configuration section in the User's Guide.

         * the built-in handlers, see logger_std_h and logger_disk_log_h.

         * the built-in formatter, see logger_formatter.

         * built-in filters, see logger_filters.

   Note:
       Since Logger is new in Erlang/OTP 21.0, we do reserve the right to introduce changes to  the  Logger  API
       and  functionality  in  patches  following  this  release.  These changes might or might not be backwards
       compatible with the initial version.

FModule:check_config(FConfig)->ok|{error,Reason}

              Types:

                 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,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:update_handler_config/2,3

                * logger:update_formatter_config/2

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

       FModule:format(LogEvent,FConfig)->FormattedLogEntry

              Types:

                 LogEvent = log_event()
                 FConfig = formatter_config()
                 FormattedLogEntry = unicode:chardata()

              This callback function is mandatory.

              The function can be called by a log handler to convert a log event term to a printable string. The
              returned value can, for example, be printed as a  log  entry  to  the  console  or  a  file  using
              io:put_chars/1,2.

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

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

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

       The following macros are defined in logger.hrl, which is included in a module with the directive

           -include_lib("kernel/include/logger.hrl").

         * ?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])

         * ?LOG(Level,StringOrReport[,Metadata])

         * ?LOG(Level,FunOrFormat,Args[,Metadata])

       All macros expand to a call to Logger, where Level is taken from  the  macro  name,  or  from  the  first
       argument  in  the  case  of the ?LOG macro. Location data is added to the metadata as described under the
       metadata() type definition.

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

       logger - API module for Logger, the standard logging facility
           in Erlang/OTP.

config(5), erlang(3erl), io(3erl), logger_disk_log_h(3erl), logger_filters(3erl), logger_formatter(3erl),
       logger_std_h(3erl), unicode(3erl)

Ericsson AB                                        kernel 8.2                                       logger(3erl)