Erlang/OTP provides a standard API for logging. The backend of this API can be used as is, or it can be customized to suite specific needs.

It consists of two parts - the logger part and the handler part. The logger will forward log events to one or more handler(s).

Filters can be added to the logger and to each handler. The filters decide if an event is to be forwarded or not, and they can also modify all parts of the log event.

A formatter can be set for each handler. The formatter does the final formatting of the log event, including the log message itself, and possibly a timestamp, header and other metadata.

In accordance with the Syslog protocol, RFC-5424, eight severity levels can be specified:

A log event is allowed by Logger if the integer value of its Level is less than or equal to the currently configured log level. The log level can be configured globally, or to allow more verbose logging from a specific part of the system, per module.

Log data is expected to be either a format string and arguments, a string (unicode:chardata), or a report (map or key-value list) which can be converted to a format string and arguments by the handler. A default report callback should be included in the log event's metadata, which can be used for converting the report to a format string and arguments. The handler might also do a custom conversion if the default format is not desired.

logger does, to a certain extent, check its input data before forwarding a log event to the handlers, but it does not evaluate conversion funs or check the validity of format strings and arguments. This means that any filter or handler must be careful when formatting the data of a log event, making sure that it does not crash due to bad input data or faulty callbacks.

If a filter or handler still crashes, logger will remove the filter or handler in question from the configuration, and then print a short error message on the console. A debug event containing the crash reason and other details is also issued, and can be seen if a handler is installed which logs on debug level.

When starting an erlang node, the default behavior is that all log events with level info and above are logged to the console. In order to also log debug events, you can either change the global log level to debug or add a separate handler to take care of this. In this example we will add a new handler which prints the debug events to a separate file.

First, we add an instance of logger_std_h with type {file,File}, and we set the handler's level to debug:

1> Config = #{level=>debug,logger_std_h=>#{type=>{file,"./debug.log"}}}.
#{logger_std_h => #{type => {file,"./debug.log"}},
  level => debug}
2> logger:add_handler(debug_handler,logger_std_h,Config).
ok

By default, the handler receives all events, so we need to add a filter to stop all non-debug events:

3> Fun = fun(#{level:=debug}=Log,_) -> Log; (_,_) -> stop end.
#Fun<erl_eval.12.98642416>
4> logger:add_handler_filter(debug_handler,allow_debug,{Fun,[]}).
ok

And finally, we need to make sure that the logger itself allows debug events. This can either be done by setting the global logger level:

5> logger:set_logger_config(level,debug).
ok

Or by allowing debug events from one or a few modules only:

6> logger:set_module_level(mymodule,debug).
ok

The only requirement that a handler MUST fulfill is to export the following function:

It may also implement the following callbacks:

When logger:add_handler(Id,Module,Config) is called, logger will first call Module:adding_handler(Id,Config), and if it returns {ok,NewConfig} the NewConfig is written to the configuration database. After this, the handler may receive log events as calls to Module:log/2.

A handler can be removed by calling logger:remove_handler(Id). logger will call Module:removing_handler(Id), and then remove the handler's configuration from the configuration database.

When logger:set_handler_config is called, logger calls Module:changing_config(Id,OldConfig,NewConfig). If this function returns ok, the NewConfig is written to the configuration database.

A simple handler which prints to the console could be implemented as follows:

A simple handler which prints to file could be implemented like this:

Note that none of the above handlers have any overload protection, and all log events are printed directly from the client process. Neither do the handlers use the formatter or in any way add time or other metadata to the printed events.

For examples of overload protection, please refer to the implementation of logger_std_h and logger_disk_log_h .

Below is a simpler example of a handler which logs through one single process, and uses the default formatter to gain a common look of the log events.

It also uses the metadata field report_cb, if it exists, to print reports in the way the event issuer suggests. The formatter will normally do this, but if the handler either has an own default (as in this example) or if the given report_cb should not be used at all, then the handler must take care of this itself.

error_logger(3), SASL(6)