# error_logger

### MODULE

error_logger

### MODULE SUMMARY

The Erlang Error Logger

### DESCRIPTION

The error logger is an event manager behaviour which runs with the registered name `error_logger` (see more about event managers/handlers in the Design Principles chapter and in gen_event(3)). All error messages from the Erlang runtime system are sent to this process as messages with the format `{emulator, Gleader, Str}`, where `Str` is a string which describes the error in plain English. The `Gleader` argument is the group leader process of the process causing the error. This is useful in a distributed setting as all error messages can be returned to the `error_logger` process on the originating node.

Beginning with release R9C of Erlang/OTP, a new class of events, warnings, are added. By default, a warning is similar to an error, i.e. it shows up as an error report in the logs. By using the emulator switch `+W {e|w|i}` one can map warnings to be tagged either as errors (default), warnings (may require rewrite of custom error loggers) or infos.

How warnings are mapped in the running system can be determined by use of the function `error_logger:warning_map/0`, see below.

All errors detected by the standard libraries are reported with the `error_logger` functions. Errors detected in application modules should also be reported through the `error_logger` in order to get uniform reports.

Associated event handlers can be used to add private `types` of reports to the `error_logger`. An event handler which recognizes the specialized report type is first added to the `error_logger` (`add_report_handler/1,2`)

The standard configuration of the `error_logger` supports the logging of errors to the `tty`, or to a specified `file`. There is also a multi-file logger which logs all events, not only the standard error events, to several files. (see log_mf_h(3)).

All error events are tagged with the group leader `Gleader` in order to send the error to the originating node.

### EXPORTS

`start() -> {ok, Pid} | {error, What}`
`start_link() -> {ok, Pid} | {error, What}`

Types:

`Pid = pid()`
`What = {already_started, Pid} | term()`

Starts the `error_logger`. The `start_link` function should be used when the `error_logger` is supervised

`error_report(Report) -> ok`

Types:

`Report = [{Tag, Data}] | [term()] | string() | term()`
`Tag = term()`
`Data = term()`

Sends a standard error report event to the error logger. This report event is handled by the standard event handler. The report is formatted as follows:

    Tag1:   Data1
    Tag2:   Data2
    Term1
    Term2

If `Report` is a string(), the string is written.

The report is written with an error heading.

`error_report(Type,Report) -> ok`

Types:

`Type = term()`
`Report = [{Tag, Data}] | [term()] | string() | term()`
`Tag = term()`
`Data = term()`

Sends a user defined error report type event to the error logger. If specialized error handling is required, an event handler recognizing this `Type` of report must first be added to the `error_logger`.

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

`info_report(Report) -> ok`

Types:

`Report = [{Tag, Data}] | [term()] | string() | term()`
`Tag = term()`
`Data = term()`

Sends an information report to the error logger. This report event is handled by the standard event handler. The report is formatted as follows:

    Tag1:   Data1
    Tag2:   Data2
    Term1
    Term2

If `Report` is a string(), the string is written.

The report is written with an information heading.

`info_report(Type,Report) -> ok`

Types:

`Type = term()`
`Report = [{Tag, Data}] | [term()] | string() | term()`
`Tag = term()`
`Data = term()`

Sends a user defined information report type event to the error logger. If specialized error handling is required, an event handler recognizing this `Type` of report must first be added to the `error_logger`.

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

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

Types:

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

Sends an error event to the error logger. The `Format` and `Args` arguments are the same as the arguments of `io:format/2`. These events are handled by the standard event handler.

`info_msg(Format) -> ok`
`info_msg(Format,Args) -> ok`

Types:

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

Sends an information event to the error logger. The `Format` and `Args` arguments are the same as the arguments of `io:format/2`. These events are handled by the standard event handler.

`tty(Flag) -> ok`

Types:

`Flag = true | false`

Enables or disables error printouts to the tty. If `Flag` is `false`, all text that the error logger would have sent to the terminal is discarded. If `Flag` is `true`, error messages are sent to the terminal screen.

`logfile(Request) -> ok | FileName | {error, What}`

Types:

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

This function makes it possible to append a copy of all standard error printouts to a file. It can be used in combination with the `tty(false)` function in to have a silent system, where all errors are logged to a file.

`Request` can be:

- `{open, Filename}`. Opens the file `Filename` to store a copy of all error messages. Returns `ok`, or `{error, What}`.
- `close`. Closes the current log file. Returns `ok`, or `{error, What}`.
- `filename`. Returns `{error, What}` or `FileName`, where `FileName` is the name of the open log file.

There can only be one active log file.

`add_report_handler(Module) -> ok | Other`
`add_report_handler(Module,Args) -> ok | Other`

Types:

`Module = atom()`
`Args = term()`
`Other = term()`

Adds a new event handler to the error logger. The event handler is initialized by a call to the `Module`:init/1 function. This function must return `{ok, State}`. If anything else (`Other`) is returned, the handler is not added.

The report (event) handler will be called for every error event that the error logger receives (`Module:handle_event/2`). Errors dedicated to this handler should be handled accordingly.

`delete_report_handler(Module) -> Return | {error, What}`

Types:

`Module = atom()`
`Return = term()`
`What = term()`

Deletes an error report (event) handler. The `Module`:terminate/2 function is called in order to finalize the event handler. The return value of the terminate/2 function is `Return`.

`swap_handler(ToHandler) -> ok`

Types:

`ToHandler = tty | {logfile, File}`
`File = atom() | string()`

The `error_logger` event manager is initially started with a primitive event handler which buffers and prints the raw error events. However, this function does install the standard event handler to be used according to the system configuration.

`warning_map() -> TagAtom`

Types:

`TagAtom = {error|warning|info}`

This function is used to determine how warnings are mapped in the current system. If `warning_msg/1`, `warning_msg/2`, `warning_report/1` or `warning_report/2` are called, the events might be tagged either as `error`, `warning` or `info`, depending on the switches used when the emulator was started (`+W {i|w|e})`.

`warning_msg(Format) -> ok`
`warning_msg(Format,Args) -> ok`

Types:

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

Works like error_msg/1 or error_msg/2 respectively, but the event might be tagged either as error, warning or info, depending on how the emulator was started.

`warning_report(Report) -> ok`
`warning_report(Type,Report) -> ok`

Types:

`Type = term()`
`Report = [{Tag, Data}] | [term()] | string() | term()`
`Tag = term()`
`Data = term()`

Works like error_report/1 or error_report/2 respectively, but the event might be tagged either as error, warning or info, depending on how the emulator was started. See description of warnings in the introduction above.

### Events

The error logger event manager forwards the following events to all added event handlers. In the events that follow, `Gleader` is the group leader process identity of the error reporting process, and `EPid` is the process identity of the `error_logger`. All other variables are described with the function in which they appear.

`{error_report, Gleader, {Epid, std_error, Report}}`
  This event is generated when the `error_report/1` function is called.
`{error_report, Gleader, {Epid, Type, Report}}`
  This event is generated when the `error_report/2` function is called.
`{info_report, Gleader, {Epid, std_info, Report}}`
  This event is generated when the `info_report/1` function is called.
`{info_report, Gleader, {Epid, Type, Report}}`
  This event is generated when the `info_report/2` function is called.
`{error, Gleader, {EPid, Format, Args}}`
  This event is generated when the `error_msg` or `format` functions are called.
`{info_msg, Gleader, {EPid, Format, Args}}`
  This event is generated when the `info_msg` functions are called.
`{info, Gleader, {EPid, term(), []}}`
  This structure is only used by the `init` process for erroneously received messages.
`{warning_msg, Gleader, {EPid, Format, Args}}`
  This structure only appears when the emulator is started with the `+W w` switch, as a result of someone calling `warning_msg/1` or `warning_msg/2`.
`{warning_report, Gleader, {Epid, Type, Report}}`
  This structure only appears when the emulator is started with the `+W w` switch, as a result of someone calling `warning_report/1` or `warning_report/2`.

| All events issued by a process which has the group leader `Gleader` process located on another node will be passed to this node by the `error_logger`.

### See Also

gen_event(3), log_mf_h(3)

### AUTHORS

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

kernel 2.10.4
Copyright © 1991-2005 Ericsson AB