package easy_logging

Easy logging

Logging infrastructure inspired by the Python logging module. The aim of this module is to provide a quick and easy to use logging infrastructure.

It has the following features :

• one line logger creation
• log messages are either string or string lazy_t
• log level adaptable at runtime from anywhere in the program
• handlers associated to each logger will format and treat the message independantly

Basic example

open Easy_logging
logger = Logging.make_logger "my_logger" (Some Debug) [Cli Debug];;
logger#info "log_message";; 

will output to the stdout a message of the form

1.306  my_logger    Info    log_message

Reference

• Easy_logging.Logging.logger : Default logger class.
• Easy_logging__Default_handlers : Default handlers.
• Easy_logging.MakeLogging : Functor to create your own logging module.
• Easy_logging__Easy_logging_types : Types definitions.
• Easy_logging : Entry point of the module.

Overall description

Infrastructure

Like in the python logging module, this logging infrastructure is based on four concepts:

loggers, handlers, formatters and log items.

A call to logger will create a log item, which it will pass to its handlers. Each handler transforms the log item to a string using its assigned formatter, and then treats the item (e.g. outputs to stdout or to a file).

                                   ___________________________
                                  |         handler 1         |
                                  | (formatter) | (treatment) |
             _______________      |---------------------------|
            |     logger    | ==> | -> string  ==>    ( * )   |
            |---------------|     |___________________________|
message ==> | -> log item   |      ___________________________
            [_______________| ==> |         handler 2         |
                                  |            ...            |

Levels

To each logger, handler and log message are associated a level, which will be used to filter the messages going through the logging infrastructure.

The predefined levels are, in increasing order of precedence :

1. Debug : used for debugging.
2. Info : used to trace program execution.
3. Warning : used for warnings.
4. Error : used for errors.
5. Flash : used for one-shot debugging: displays an easy to spot message.

Defaults

Default Handlers

By default, two handlers are provided:

• Cli handler: outputs colored messages to stdout.

   let h = Default_handlers.make (Cli Debug) 

• File handler : outputs messages to a given file.

   let h = Default_handlers.make (File ("filename", Debug)) 

See more about default handlers at Easy_logging__Default_handlers.

Loggers

See complete class documentation at Easy_logging.Logging.logger

Creation

A logger object can be created directly :

 let logger1 = new Logging.logger "my_logger1" (Some Warning) [Cli Debug] 

or through the make_logger function :

 let logger2 = Logging.make_logger "my_logger2" (Some Debug) [Cli Debug] 

The make_logger function will register the logger instance internaly so that it will be possible to access and modify it from anywhere in the program.

Usage

A logger object has two methods for each of the log levels.

logger1#debug "x is alive";
logger1#ldebug (lazy (heavy_calculation ()));