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

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.

### 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.
`{emulator, Gleader, string()}`
  This event is generated by the runtime system. If the error was not issued by a special process, `Gleader` is `noproc`. This event should be handled in the `handle_info/2` function of the event handler.

| 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.7.2
Copyright © 1991-2002 Ericsson Utvecklings AB