# error_logger

### MODULE

error_logger

### MODULE SUMMARY

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

### EXPORTS

`error_msg(Format) -> ok`
`error_msg(Format, Data) -> ok`
`format(Format, Data) -> ok`

Types:

`Format = string()`
`Data = [term()]`

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 occured in ~p~n", [a_module]).

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

| 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 = [{Tag, Data} | term()] | string() | term()`
`Tag = Data = term()`

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 = [{Tag, Data} | term()] | string() | term()`
`Tag = Data = term()`

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 = [term()]`

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.

| 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 = [{Tag, Data} | term()] | string() | term()`
`Tag = Data = term()`

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 = term()`
`Report = [{Tag, Data} | term()] | string() | term()`
`Tag = Data = term()`

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 = [term()]`

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

| 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 = [{Tag, Data} | term()] | string() | term()`
`Tag = Data = term()`

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 = term()`
`Report = [{Tag, Data} | term()] | string() | term()`
`Tag = Data = term()`

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) -> Result`
`add_report_handler(Handler, Args) -> Result`

Types:

`Handler, Args, Result -- see gen_event:add_handler/3`

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 `Module: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, Result -- see gen_event:delete_handler/3`

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 = bool()`

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) -> ok | Filename | {error, What}`

Types:

`Request = {open, Filename} | close | filename`
`Filename = atom() | string()`
`What = allready_have_logfile | no_log_file | term()`

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, What}`.
`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)

### AUTHORS

Joe Armstrong - support@erlang.ericsson.se
Magnus Fröberg - support@erlang.ericsson.se
Claes Wikström - support@erlang.ericsson.se
Gunilla Arendt - support@erlang.ericsson.se

kernel 2.11.5
Copyright © 1991-2007 Ericsson AB