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