Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
logger(3)		   Erlang Module Definition		     logger(3)

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

DESCRIPTION
       This  module implements the main	API for	logging	in Erlang/OTP. To cre-
       ate 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	 stan-
       dard  log events	produced by the	Erlang runtime system, standard	behav-
       iours and different Erlang/OTP applications. The	log events are by  de-
       fault 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  in-
       troduce	changes	to the Logger API and functionality in patches follow-
       ing this	release. These changes might or	might not be backwards compat-
       ible with the initial version.

DATA TYPES
       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(3)
	      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 in-
	      serted  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(3) and	logger_disk_log_h man-
	      ual  pages  for  information about the specifc configuration for
	      these handlers.

	      See the logger_formatter(3) 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 informa-
	      tion:

		* 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  up-
	      date_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	 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 descrip-
		  tion 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 con-
		  verts	 the  report  to a format string and arguments,	or di-
		  rectly to a string. See the type definition of  report_cb(),
		  and  section Log Message in the User's Guide for more	infor-
		  mation about report callbacks.

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

       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,
	     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 argu-
	      ments, 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().

MACROS
       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	 meta-
       data() 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.

LOGGING	API FUNCTIONS
EXPORTS
       emergency(StringOrReport[,Metadata])
       emergency(Format,Args[,Metadata])
       emergency(Fun,FunArgs[,Metadata])

	      Equivalent to log(emergency,...).

       alert(StringOrReport[,Metadata])
       alert(Format,Args[,Metadata])
       alert(Fun,FunArgs[,Metadata])

	      Equivalent to log(alert,...).

       critical(StringOrReport[,Metadata])
       critical(Format,Args[,Metadata])
       critical(Fun,FunArgs[,Metadata])

	      Equivalent to log(critical,...).

       error(StringOrReport[,Metadata])
       error(Format,Args[,Metadata])
       error(Fun,FunArgs[,Metadata])

	      Equivalent to log(error,...).

       warning(StringOrReport[,Metadata])
       warning(Format,Args[,Metadata])
       warning(Fun,FunArgs[,Metadata])

	      Equivalent to log(warning,...).

       notice(StringOrReport[,Metadata])
       notice(Format,Args[,Metadata])
       notice(Fun,FunArgs[,Metadata])

	      Equivalent to log(notice,...).

       info(StringOrReport[,Metadata])
       info(Format,Args[,Metadata])
       info(Fun,FunArgs[,Metadata])

	      Equivalent to log(info,...).

       debug(StringOrReport[,Metadata])
       debug(Format,Args[,Metadata])
       debug(Fun,FunArgs[,Metadata])

	      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.

CONFIGURATION API FUNCTIONS
EXPORTS
       add_handler(HandlerId, Module, Config) -> ok | {error, term()}

	      Types:

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

	      Add a handler with the given configuration.

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

       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.

	      The filter fun is	called with the	log event as the first parame-
	      ter, 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_event():
		  The  filter  passed. The next	handler	filter,	if any,	is ap-
		  plied. 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  han-
		  dler	filter,	 if  any, is applied. If no more filters exist
		  for this handler, the	value of the filter_default configura-
		  tion	parameter  for	the handler specifies if the log event
		  shall	be discarded or	forwarded to the handler callback.

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

	      Some  built-in  filters  exist. These are	defined	in logger_fil-
	      ters.

       add_handlers(Application) -> ok | {error, term()}

	      Types:

		 Application = atom()

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

       add_handlers(HandlerConfig) -> ok | {error, term()}

	      Types:

		 HandlerConfig = [config_handler()]
		 config_handler() =
		     {handler, handler_id(), module(), handler_config()}

	      This  function  should be	used by	custom Logger handlers to make
	      configuration consistent no  matter  which  handler  the	system
	      uses.  Normal  usage  is	to add a call to logger:add_handlers/1
	      just after the processes that the	handler	needs are started, and
	      pass the application's logger configuration as the argument. For
	      example:

	      -behaviour(application).
	      start(_, []) ->
		  case supervisor:start_link({local, my_sup}, my_sup, []) of
		      {ok, Pid}	->
			  ok = logger:add_handlers(my_app),
			  {ok, Pid, []};
		      Error -> Error
		   end.

	      This reads the logger configuration parameter  from  the	my_app
	      application  and starts the configured handlers. The contents of
	      the configuration	use the	same rules as the logger handler  con-
	      figuration.

	      If the handler is	meant to replace the default handler, the Ker-
	      nel's default handler have to be disabled	before the new handler
	      is added.	A sys.config file that disables	the Kernel handler and
	      adds a custom handler could look like this:

	      [{kernel,
		[{logger,
		  %% Disable the default Kernel	handler
		  [{handler, default, undefined}]}]},
	       {my_app,
		[{logger,
		  %% Enable this handler as the	default
		  [{handler, default, my_handler, #{}}]}]}].

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

	      Types:

		 FilterId = filter_id()
		 Filter	= filter()

	      Add a primary filter to Logger.

	      The filter fun is	called with the	log event as the first parame-
	      ter, 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  ap-
		  plied.  If  no  more primary filters exist, the log event is
		  forwarded to the handler part	of Logger, where handler  fil-
		  ters 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  pri-
		  mary	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_fil-
	      ters.

       get_config() ->
		     #{primary => primary_config(),
		       handlers	=> [handler_config()],
		       proxy =>	olp_config(),
		       module_levels =>
			   [{module(), level() | all | none}]}

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

       get_handler_config() -> [Config]

	      Types:

		 Config	= handler_config()

	      Look up the current configuration	for all	handlers.

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

	      Types:

		 HandlerId = handler_id()
		 Config	= handler_config()

	      Look up the current configuration	for the	given handler.

       get_handler_ids() -> [HandlerId]

	      Types:

		 HandlerId = handler_id()

	      Look up the identities for all installed handlers.

       get_primary_config() -> Config

	      Types:

		 Config	= primary_config()

	      Look up the current primary configuration	for Logger.

       get_proxy_config() -> Config

	      Types:

		 Config	= olp_config()

	      Look up the current configuration	for the	Logger proxy.

	      For  more	 information about the proxy, see section Logger Proxy
	      in the Kernel User's Guide.

       get_module_level() -> [{Module, Level}]

	      Types:

		 Module	= module()
		 Level = level() | all | none

	      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.

       get_module_level(Modules) -> [{Module, Level}]

	      Types:

		 Modules = [Module] | Module
		 Module	= module()
		 Level = level() | all | none

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

       get_process_metadata() -> Meta |	undefined

	      Types:

		 Meta =	metadata()

	      Retrieve	 data	set   with   set_process_metadata/1   or   up-
	      date_process_metadata/1.

       i() -> ok

       i(What) -> ok

	      Types:

		 What =	primary	| handlers | proxy | modules | handler_id()

	      Pretty print the Logger configuration.

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

	      Types:

		 HandlerId = handler_id()

	      Remove the handler identified by HandlerId.

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

	      Types:

		 HandlerId = handler_id()
		 FilterId = filter_id()

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

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

	      Types:

		 FilterId = filter_id()

	      Remove the primary filter	identified by FilterId from Logger.

       set_application_level(Application, Level) ->
				ok | {error, not_loaded}

	      Types:

		 Application = atom()
		 Level = level() | all | none

	      Set  the log level for all the modules of	the specified applica-
	      tion.

	      This  function  is  a  convenience  function  that  calls	  log-
	      ger:set_module_level/2 for each module associated	with an	appli-
	      cation.

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

	      Types:

		 HandlerId = handler_id()
		 Config	= handler_config()

	      Set configuration	data for the  specified	 handler.  This	 over-
	      writes the current handler configuration.

	      To  modify  the  existing	configuration, use update_handler_con-
	      fig/2, or, if a more complex merge is needed, read  the  current
	      configuration  with  get_handler_config/1, then do the merge be-
	      fore writing the new configuration back with this	function.

	      If a key is removed compared to the current  configuration,  and
	      the  key is known	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.

       set_handler_config(HandlerId, Key :: level, Level) -> Return

       set_handler_config(HandlerId,
			  Key :: filter_default,
			  FilterDefault) ->
			     Return

       set_handler_config(HandlerId, Key :: filters, Filters) -> Return

       set_handler_config(HandlerId, Key :: formatter, Formatter) ->
			     Return

       set_handler_config(HandlerId, Key :: config, Config) -> Return

	      Types:

		 HandlerId = handler_id()
		 Level = level() | all | none
		 FilterDefault = log | stop
		 Filters = [{filter_id(), filter()}]
		 Formatter = {module(),	formatter_config()}
		 Config	= term()
		 Return	= ok | {error, term()}

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

	      If the value is incomplete, which	for example can	 be  the  case
	      for  the	config key, it is up to	the handler implementation how
	      the unspecified parts are	set. For all handlers  in  the	Kernel
	      application,  unspecified	 data for the config key is set	to de-
	      fault values. To update only specified data, and keep the	exist-
	      ing configuration	for the	rest, use update_handler_config/3.

	      See  the definition of the handler_config() type for more	infor-
	      mation about the different parameters.

       set_primary_config(Config) -> ok	| {error, term()}

	      Types:

		 Config	= primary_config()

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

	      To  modify  the  existing	configuration, use update_primary_con-
	      fig/1, or, if a more complex merge is needed, read  the  current
	      configuration  with  get_primary_config/0, then do the merge be-
	      fore writing the new configuration back with this	function.

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

       set_primary_config(Key :: level,	Level) -> ok | {error, term()}

       set_primary_config(Key :: filter_default, FilterDefault)	->
			     ok	| {error, term()}

       set_primary_config(Key :: filters, Filters) ->
			     ok	| {error, term()}

	      Types:

		 Level = level() | all | none
		 FilterDefault = log | stop
		 Filters = [{filter_id(), filter()}]

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

       set_proxy_config(Config)	-> ok |	{error,	term()}

	      Types:

		 Config	= olp_config()

	      Set configuration	data for the Logger proxy. This	overwrites the
	      current proxy configuration. Keys	that are not specified in  the
	      Config map gets default values.

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

	      For more information about the proxy, see	section	 Logger	 Proxy
	      in the Kernel User's Guide.

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

	      Types:

		 Modules = [module()] |	module()
		 Level = level() | all | none

	      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 configura-
	      tion 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 han-
	      dler, 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_con-
	      fig(level, Level).

	      To change	the log	level  for  a  handler,	 use  set_handler_con-
	      fig(HandlerId, level, Level).

	  Note:
	      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_process_metadata(Meta) -> ok

	      Types:

		 Meta =	metadata()

	      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	 loca-
	      tion data.

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

       unset_application_level(Application) -> ok | {error, not_loaded}

	      Types:

		 Application = atom()

	      Unset  the log level for all the modules of the specified	appli-
	      cation.

	      This function is a convinience function  that  calls  logger:un-
	      set_module_level/2  for  each module associated with an applica-
	      tion.

       unset_module_level() -> ok

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

       unset_module_level(Modules) -> ok

	      Types:

		 Modules = [module()] |	module()

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

       unset_process_metadata()	-> ok

	      Delete   data   set   with   set_process_metadata/1    or	   up-
	      date_process_metadata/1.

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

	      Types:

		 HandlerId = handler_id()
		 FormatterConfig = formatter_config()

	      Update the formatter configuration for the specified handler.

	      The new configuration is merged with the existing	formatter con-
	      figuration.

	      To overwrite the existing	configuration without any merge, use

	      set_handler_config(HandlerId, formatter, {FormatterModule, FormatterConfig}).

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

	      Types:

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

	      Update the formatter configuration for the specified handler.

	      This is equivalent to

	      update_formatter_config(HandlerId, #{Key => Value})

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

	      Types:

		 HandlerId = handler_id()
		 Config	= handler_config()

	      Update configuration data	for the	specified handler. This	 func-
	      tion 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.

       update_handler_config(HandlerId,	Key :: level, Level) ->	Return

       update_handler_config(HandlerId,
			     Key :: filter_default,
			     FilterDefault) ->
				Return

       update_handler_config(HandlerId,	Key :: filters,	Filters) ->
				Return

       update_handler_config(HandlerId,	Key :: formatter, Formatter) ->
				Return

       update_handler_config(HandlerId,	Key :: config, Config) -> Return

	      Types:

		 HandlerId = handler_id()
		 Level = level() | all | none
		 FilterDefault = log | stop
		 Filters = [{filter_id(), filter()}]
		 Formatter = {module(),	formatter_config()}
		 Config	= term()
		 Return	= ok | {error, term()}

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

	      If  the  value  is incomplete, which for example can be the case
	      for the config key, it is	up to the handler  implementation  how
	      the  unspecified	parts  are set.	For all	handlers in the	Kernel
	      application, unspecified data for	the config key is not changed.
	      To  reset	 unspecified  data  to	default	 values,  use set_han-
	      dler_config/3.

	      See the definition of the	handler_config() type for more	infor-
	      mation about the different parameters.

       update_primary_config(Config) ->	ok | {error, term()}

	      Types:

		 Config	= primary_config()

	      Update  primary configuration data for Logger. This function be-
	      haves 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.

       update_process_metadata(Meta) ->	ok

	      Types:

		 Meta =	metadata()

	      Set or update metadata to	use when logging from current process

	      If  process  metadata exists for the current process, this func-
	      tion 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.

       update_proxy_config(Config) -> ok | {error, term()}

	      Types:

		 Config	= olp_config()

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

	      Old = logger:get_proxy_config(),
	      logger:set_proxy_config(maps:merge(Old, Config)).

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

	      For  more	 information about the proxy, see section Logger Proxy
	      in the Kernel User's Guide.

MISCELLANEOUS API FUNCTIONS
EXPORTS
       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.

       format_report(Report) ->	FormatArgs

	      Types:

		 Report	= report()
		 FormatArgs = {io:format(), [term()]}

	      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. 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  Report  is a map, it is converted to a key-value list	before
	      formatting as such.

       timestamp() -> timestamp()

	      Return a timestamp that can be inserted as the time field	in the
	      meta  data  for  a  log  event.  It  is  produced	 with  os:sys-
	      tem_time(microsecond).

	      Notice that Logger automatically inserts a timestamp in the meta
	      data unless it already exists. This function is exported for the
	      rare case	when the timestamp must	be taken at a different	 point
	      in time than when	the log	event is issued.

HANDLER	CALLBACK FUNCTIONS
       The following functions are to be exported from a handler callback mod-
       ule.

EXPORTS
       HModule:adding_handler(Config1) -> {ok, Config2}	| {error, Reason}

	      Types:

		 Config1 = Config2 = handler_config()
		 Reason	= term()

	      This callback function is	optional.

	      The function is called on	a temporary process when an  new  han-
	      dler is about to be added. The purpose is	to verify the configu-
	      ration and initiate all resources	needed by the handler.

	      The handler identity is associated with the id key in Config1.

	      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}.

       HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Con-
       fig} | {error, Reason}

	      Types:

		 SetOrUpdate = set | update
		 OldConfig = NewConfig = Config	= handler_config()
		 Reason	= term()

	      This callback function is	optional.

	      The function is called on	a temporary process when the  configu-
	      ration  for a handler is about to	change.	The purpose is to ver-
	      ify and act on the new configuration.

	      OldConfig	is the existing	configuration and NewConfig is the new
	      configuration.

	      The handler identity is associated with the id key in OldConfig.

	      SetOrUpdate has the value	set if the configuration change	origi-
	      nates from a call	to set_handler_config/2,3, and	update	if  it
	      originates  from	update_handler_config/2,3. The handler can use
	      this parameteter to decide how to	update the value of the	config
	      field,  that  is,	the handler specific configuration data. Typi-
	      cally, if	SetOrUpdate equals set,	values that are	not  specified
	      must  be	given  their default values. If	SetOrUpdate equals up-
	      date, the	values found in	OldConfig must be used instead.

	      If everything succeeds, the callback function must return	a pos-
	      sibly adjusted configuration in {ok,Config}.

	      If  the  configuration is	faulty,	the callback function must re-
	      turn {error,Reason}.

       HModule:filter_config(Config) ->	FilteredConfig

	      Types:

		 Config	= FilteredConfig = handler_config()

	      This callback function is	optional.

	      The function is called when one of the Logger API	functions  for
	      fetching	the  handler configuration is called, for example log-
	      ger:get_handler_config/1.

	      It allows	the handler to remove internal data  fields  from  its
	      configuration data before	it is returned to the caller.

       HModule:log(LogEvent, Config) ->	void()

	      Types:

		 LogEvent = log_event()
		 Config	= handler_config()

	      This callback function is	mandatory.

	      The  function is called when all primary filters and all handler
	      filters for the handler in question have passed  for  the	 given
	      log  event.  It  is  called  on the client process, that is, the
	      process that issued the log event.

	      The handler identity is associated with the id key in Config.

	      The handler must log the event.

	      The return value from this function is ignored by	Logger.

       HModule:removing_handler(Config)	-> ok

	      Types:

		 Config	= handler_config()

	      This callback function is	optional.

	      The function is called on	a temporary process when a handler  is
	      about  to	 be  removed.  The purpose is to release all resources
	      used by the handler.

	      The handler identity is associated with the id key in Config.

	      The return value is ignored by Logger.

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

EXPORTS
       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  con-
	      figuration 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(3)  for  an	example	 implementation.  log-
	      ger_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 us-
	      ing io:put_chars/1,2.

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

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)

Ericsson AB			  kernel 6.3			     logger(3)

NAME | DESCRIPTION | DATA TYPES | MACROS | LOGGING API FUNCTIONS | EXPORTS | CONFIGURATION API FUNCTIONS | EXPORTS | MISCELLANEOUS API FUNCTIONS | EXPORTS | HANDLER CALLBACK FUNCTIONS | EXPORTS | FORMATTER CALLBACK FUNCTIONS | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=logger&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help