Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       error_logger - Erlang Error Logger

DESCRIPTION

       The   Erlang   error   logger   is  an  event  manager  (see  OTP  Design  Principles  and
       gen_event(3erl)), 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 buffers and prints the
       raw event messages. During system startup, the application Kernel  replaces  this  with  a
       standard event handler, by default 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(7).

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

       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(3erl).

       Warning  events was 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 standard  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  using  warning_msg/1,2
              or  warning_report/1,2  are tagged as errors (default), warnings or info, depending
              on the value of the command 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 standard  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 either 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  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: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 standard  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 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 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(3erl).

              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(3erl).

       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, module_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(3erl), log_mf_h(3erl), kernel(7), sasl(7)