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

FreeBSD Manual Pages

  
 
  

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

NAME
       error_logger - Erlang Error Logger

DESCRIPTION
       The  Erlang error logger	is an event manager (see OTP Design Principles
       and gen_event(3)), registered as	error_logger. Error, warning and  info
       events  are sent	to the error logger from the Erlang runtime system and
       the different Erlang/OTP	applications.  The  events  are,  by  default,
       logged  to  tty.	 Note  that an event from a process P is logged	at the
       node of the group leader	of P. This means that log output  is  directed
       to  the node from which a process was created, which not	necessarily is
       the same	node as	where it is executing.

       Initially, error_logger only has	a primitive event handler, which  buf-
       fers  and prints	the raw	event messages.	During system startup, the ap-
       plication Kernel	replaces this with a standard event  handler,  by  de-
       fault  one which	writes nicely formatted	output to tty. Kernel can also
       be configured so	that events are	logged to file instead,	or not	logged
       at all, see kernel(6).

       Also  the  SASL	application,  if  started, adds	its own	event handler,
       which by	default	writes supervisor, crash and progress reports to  tty.
       See sasl(6).

       It  is  recommended that	user defined applications should report	errors
       through the error logger, in order to get uniform reports. User defined
       event  handlers	can  be	 added	to handle application specific events.
       (add_report_handler/1,2). Also, there is	 a  useful  event  handler  in
       STDLIB for multi-file logging of	events,	see log_mf_h(3).

       Warning	events	were introduced	in Erlang/OTP R9C. To retain backwards
       compatibility, these are	by default tagged as errors, thus  showing  up
       as  error  reports  in the logs.	By using the command line flag +W _w |
       i_, they	can instead be tagged as warnings or  info.  Tagging  them  as
       warnings	may require rewriting existing user defined event handlers.

DATA TYPES
       report()	= [{Tag	:: term(), Data	:: term()} | term()]
		| string()
		| term()

EXPORTS
       error_msg(Format) -> ok

       error_msg(Format, Data) -> ok

       format(Format, Data) -> ok

	      Types:

		 Format	= string()
		 Data =	list()

	      Sends a standard error event to the error	logger.	The Format and
	      Data arguments are the same as the arguments of io:format/2. The
	      event is handled by the standard event handler.

	      1> error_logger:error_msg("An error occurred in ~p~n", [a_module]).

	      =ERROR REPORT====	11-Aug-2005::14:03:19 ===
	      An error occurred	in a_module
	      ok

	  Warning:
	      If  called with bad arguments, this function can crash the stan-
	      dard event handler, meaning no further events are	 logged.  When
	      in doubt,	use error_report/1 instead.

       error_report(Report) -> ok

	      Types:

		 Report	= report()

	      Sends  a	standard  error	 report	event to the error logger. The
	      event is handled by the standard event handler.

	      2> error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).

	      =ERROR REPORT====	11-Aug-2005::13:45:41 ===
		  tag1:	data1
		  a_term
		  tag2:	data
	      ok
	      3> error_logger:error_report("Serious error in my	module").

	      =ERROR REPORT====	11-Aug-2005::13:45:49 ===
	      Serious error in my module
	      ok

       error_report(Type, Report) -> ok

	      Types:

		 Type =	term()
		 Report	= report()

	      Sends a user defined error report	event to the error logger.  An
	      event  handler  to  handle  the  event  is supposed to have been
	      added. The event is ignored by the standard event	handler.

	      It is recommended	that Report follows the	same structure as  for
	      error_report/1.

       warning_map() ->	Tag

	      Types:

		 Tag = error | warning | info

	      Returns  the current mapping for warning events. Events sent us-
	      ing warning_msg/1,2 or warning_report/1,2	are tagged  as	errors
	      (default),  warnings or info, depending on the value of the com-
	      mand line	flag +W.

	      os$ erl
	      Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]

	      Eshell V5.4.8  (abort with ^G)
	      1> error_logger:warning_map().
	      error
	      2> error_logger:warning_msg("Warnings tagged as: ~p~n", [error]).

	      =ERROR REPORT====	11-Aug-2005::15:31:23 ===
	      Warnings tagged as: error
	      ok
	      3>
	      User switch command
	       --> q
	      os$ erl +W w
	      Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]

	      Eshell V5.4.8  (abort with ^G)
	      1> error_logger:warning_map().
	      warning
	      2> error_logger:warning_msg("Warnings tagged as: ~p~n", [warning]).

	      =WARNING REPORT==== 11-Aug-2005::15:31:55	===
	      Warnings tagged as: warning
	      ok

       warning_msg(Format) -> ok

       warning_msg(Format, Data) -> ok

	      Types:

		 Format	= string()
		 Data =	list()

	      Sends a standard warning event to	the error logger.  The	Format
	      and Data arguments are the same as the arguments of io:format/2.
	      The event	is handled by the standard event handler. It is	tagged
	      either as	an error, warning or info, see warning_map/0.

	  Warning:
	      If  called with bad arguments, this function can crash the stan-
	      dard event handler, meaning no further events are	 logged.  When
	      in doubt,	use warning_report/1 instead.

       warning_report(Report) -> ok

	      Types:

		 Report	= report()

	      Sends  a	standard warning report	event to the error logger. The
	      event is handled by the standard event handler. It is tagged ei-
	      ther as an error,	warning	or info, see warning_map/0.

       warning_report(Type, Report) -> ok

	      Types:

		 Type =	any()
		 Report	= report()

	      Sends  a	user defined warning report event to the error logger.
	      An event handler to handle the event is supposed	to  have  been
	      added. The event is ignored by the standard event	handler. It is
	      tagged either as an error, warning or  info,  depending  on  the
	      value of warning_map/0.

       info_msg(Format)	-> ok

       info_msg(Format,	Data) -> ok

	      Types:

		 Format	= string()
		 Data =	list()

	      Sends a standard information event to the	error logger. The For-
	      mat and Data arguments are the same as the arguments of  io:for-
	      mat/2. The event is handled by the standard event	handler.

	      1> error_logger:info_msg("Something happened in ~p~n", [a_module]).

	      =INFO REPORT==== 11-Aug-2005::14:06:15 ===
	      Something	happened in a_module
	      ok

	  Warning:
	      If  called with bad arguments, this function can crash the stan-
	      dard event handler, meaning no further events are	 logged.  When
	      in doubt,	use info_report/1 instead.

       info_report(Report) -> ok

	      Types:

		 Report	= report()

	      Sends  a	standard information report event to the error logger.
	      The event	is handled by the standard event handler.

	      2> error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).

	      =INFO REPORT==== 11-Aug-2005::13:55:09 ===
		  tag1:	data1
		  a_term
		  tag2:	data
	      ok
	      3> error_logger:info_report("Something strange happened").

	      =INFO REPORT==== 11-Aug-2005::13:55:36 ===
	      Something	strange	happened
	      ok

       info_report(Type, Report) -> ok

	      Types:

		 Type =	any()
		 Report	= report()

	      Sends a user defined information report event to the error  log-
	      ger.  An	event  handler to handle the event is supposed to have
	      been added. The event is ignored by the standard event handler.

	      It is recommended	that Report follows the	same structure as  for
	      info_report/1.

       add_report_handler(Handler) -> any()

       add_report_handler(Handler, Args) -> Result

	      Types:

		 Handler = module()
		 Args =	gen_event:handler_args()
		 Result	= gen_event:add_handler_ret()

	      Adds  a new event	handler	to the error logger. The event handler
	      must  be	implemented  as	 a  gen_event  callback	 module,   see
	      gen_event(3).

	      Handler is typically the name of the callback module and Args is
	      an optional term (defaults to [])	passed to  the	initialization
	      callback	function  Handler:init/1.  The	function returns ok if
	      successful.

	      The event	handler	must be	able to	handle	the  events  described
	      below.

       delete_report_handler(Handler) -> Result

	      Types:

		 Handler = module()
		 Result	= gen_event:del_handler_ret()

	      Deletes  an  event  handler  from	 the  error  logger by calling
	      gen_event:delete_handler(error_logger,   Handler,	   []),	   see
	      gen_event(3).

       tty(Flag) -> ok

	      Types:

		 Flag =	boolean()

	      Enables  (Flag  == true) or disables (Flag == false) printout of
	      standard events to the tty.

	      This is done by adding or	deleting the  standard	event  handler
	      for  output  to  tty,  thus  calling this	function overrides the
	      value of the Kernel error_logger configuration parameter.

       logfile(Request :: {open, Filename}) -> ok | {error, OpenReason}

       logfile(Request :: close) -> ok | {error, CloseReason}

       logfile(Request :: filename) -> Filename	| {error, FilenameReason}

	      Types:

		 Filename = file:name()
		 OpenReason = allready_have_logfile | open_error()
		 CloseReason = module_not_found
		 FilenameReason	= no_log_file
		 open_error() =	file:posix() | badarg |	system_limit

	      Enables or disables printout of standard events to a file.

	      This is done by adding or	deleting the  standard	event  handler
	      for  output  to  file,  thus calling this	function overrides the
	      value of the Kernel error_logger configuration parameter.

	      Enabling file logging can	be used	in  combination	 with  calling
	      tty(false), in order to have a silent system, where all standard
	      events are logged	to a file only.	There can only be  one	active
	      log file at a time.

	      Request is one of:

		{open, Filename}:
		  Opens	 the  log  file	Filename. Returns ok if	successful, or
		  {error, allready_have_logfile} if logging to file is already
		  enabled,  or	an  error tuple	if another error occurred. For
		  example, if Filename could not be opened.

		close:
		  Closes the current log file. Returns	ok,  or	 {error,  mod-
		  ule_not_found}.

		filename:
		  Returns  the	name  of  the  log  file  Filename, or {error,
		  no_log_file} if logging to file is not enabled.

EVENTS
       All event handlers added	to the error logger must handle	the  following
       events.	Gleader	 is the	group leader pid of the	process	which sent the
       event, and Pid is the process which sent	the event.

	 {error, Gleader, {Pid,	Format,	Data}}:
	   Generated when error_msg/1,2	or format is called.

	 {error_report,	Gleader, {Pid, std_error, Report}}:
	   Generated when error_report/1 is called.

	 {error_report,	Gleader, {Pid, Type, Report}}:
	   Generated when error_report/2 is called.

	 {warning_msg, Gleader,	{Pid, Format, Data}}:
	   Generated when warning_msg/1,2 is called,  provided	that  warnings
	   are set to be tagged	as warnings.

	 {warning_report, Gleader, {Pid, std_warning, Report}}:
	   Generated  when  warning_report/1 is	called,	provided that warnings
	   are set to be tagged	as warnings.

	 {warning_report, Gleader, {Pid, Type, Report}}:
	   Generated when warning_report/2 is called, provided	that  warnings
	   are set to be tagged	as warnings.

	 {info_msg, Gleader, {Pid, Format, Data}}:
	   Generated when info_msg/1,2 is called.

	 {info_report, Gleader,	{Pid, std_info,	Report}}:
	   Generated when info_report/1	is called.

	 {info_report, Gleader,	{Pid, Type, Report}}:
	   Generated when info_report/2	is called.

       Note  that  also	 a number of system internal events may	be received, a
       catch-all clause	last in	the definition of the event  handler  callback
       function	 Module:handle_event/2	is necessary. This also	holds true for
       Module:handle_info/2, as	there are a number of system internal messages
       the event handler must take care	of as well.

SEE ALSO
       gen_event(3), log_mf_h(3), kernel(6), sasl(6)

Ericsson AB			  kernel 3.2		       error_logger(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | EVENTS | SEE ALSO

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

home | help