error_logger(3)

MODULE
error_logger - 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.

  Note:

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