Module Batteries.Logger

make_log name returns a new logger.

log_name logger returns the name of the logger.

log_enable logger level enables a log level for a logger.

log_level logger returns the currently enabled level for a logger.

log_enabled logger level returns true if the specified level is currently enabled for the logger.

A log event consists of an event name and a list of key-value parameters (an association list). Events are constructed by log when a log level is enabled and passed to log formatters to render them to any logging output stream.

log logger level event_fun raises a log event if if the specified level is currently enabled for the logger. The function event_fun () is called to return the event record, and is a function in order to delay construction or formatting of any event parameters in the case where the specified log level is not enabled. For example:

log io_log INFO (fun () -> "connect", ["ADDR", addr])

would only log the "connect" event (with the "ADDR" string parameter) when the INFO log level was enabled for the io_log logger.

with_log logger level event_fun ?result body logs an event before and after calling body (). The function event_fun () is called to return the event record to be logged. After the body is evaluated, the result function is used to convert the body's result value into a string, which is added to the event record as a "RESULT" parameter (if no result function is supplied then a "-" is used). In the case where the body raises an exception, an "EXN" parameter is instead added to the event containing the name of the exception. In addition, an indentation level is maintained throughout the duration of the body such that any other log statements occurring inside the body will see an incremented indentation level. This is added to the event key-value arguments as an additional "I" parameter.

the type of a log formatter is a function that takes the logger, the level of the log statement (which will be the currently enabled level or one of its successors), the event record, and a unix timestamp indicating the time the event was created.

register_formatter name formatter registers a named log formatter. The name is only used for subsequent calls to identify the formatter via unregister_formatter.

unregister_formatter name unregisters a named log formatter.

make_std_formatter oc constructs a formatter from an output channel. This formatter will format log events as tab-separated <keyword>:<value> pairs. The resulting formatter must be registered via register_formatter to be used when events are raised. This formatter also always outputs special parameters that describe the event timestamp (an ISO-8610 timestamp prefixed by "D"), the event name (the log module name followed by a dot, followed by the event name, prefixed by "E"), the log level (prefixed by "L"), the indentation level ( prefixed by "I"), followed by any other event parameters. For example, the log statement:

log io_log INFO (fun () -> "connect", ["ADDR", addr])

would produce formatted output like the following when the io_log INFO level was enabled:

D:2009-01-26T00:47:45.033329Z   E:io.connect   L:INFO   I:1   ADDR:localhost:8080

stderr_formatter is a standard formatter that outputs log events to stderr using the same format as make_std_formatter. The resulting formatter must be registered via register_formatter or supplied to init or init_from_string to be used when events are raised.

null_formatter is a formatter that does not output any events, but simply discards them.

make_dbg_formatter oc constructs a debug formatter from an output channel. The debug formatter outputs simplified format that is easier to read for debugging purposes and displays indentation level. E.g.:

      with_log io_log DEBUG (fun () -> "listener" ["ADDR", addr])
        accept_connections (* calls other log statements *)
    

would produce formatted output like the following when the io_log DEBUG level was enabled:

      ### io.listener ADDR:localhost:8080 [DEBUG]
          ### | io.connected CLIENT_ADDR:192.168.0.23:28303 [DEBUG]
          ### | io.disconnected CLIENT_ADDR:192.168.0.23:28303 [DEBUG]
                                                               ...
            ### io.listener ADDR:localhost:8080 RESULT:- [DEBUG]
    

dbg_formatter is a debug formatter that outputs log events to stderr using the same format as make_dbg_formatter. The resulting formatter must be registered via register_formatter or supplied to init or init_from_string to be used when events are raised.

init name_level_list formatter initializes the logging system enabling the specified levels for each named logger. The formatter is the initial formatter for any log events that are output and is registered with the name "default" (other formatters may be registered by register_formatter).

init_from_string name_level_string formatter initializes the logging system enabling the specified levels for each named logger. The string must be a comma separated list of <logger
    name>:<level name> pairs, e.g. "FOO:ERROR,BAR:WARN". If a un-prefixed level name is specified, then that becomes the default log level for all newly created logs, and all currently created logs are enabled to that level. If the logger does not yet exist, it is created. The formatter is the initial formatter for any log events that are output and is registered with the name "default" (other formatters may be registered by register_formatter).

level_of_name str returns the level associated with str.

name_of_level level returns the name of the specified level.

format_timestamp oc timestamp prints an ISO-8601 formatted timestamp (extended to specify higher-resolution seconds) to the output channel, oc.