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 printf style, or provide string or string lazy_t message
• tree architecture for easy configuration
• handlers associated to each logger will format and treat the message independantly
• use the infrastructure with your own handlers with the MakeLogging functor.

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

Index

1. Overall description (Easy_logging)

2. Defaults

   1. Default Handlers ( Easy_logging__Default_handlers)
   2. Loggers ( Easy_logging.Logging.logger )
   3. The Logging module (Easy_logging.Logging)
3. The MakeLogging functor ( Easy_logging.MakeLogging )
4. Examples

Overall description

The logging infrastructure is based on four concepts:

loggers, handlers, log items and logging tree.

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

                                     ___________
                                    | handler 1 |
               _______________      |-----------|
              |     logger    | ==> |   ( * )   |
              |---------------|     |___________|
(message) ==> | -> log item   |      ___________
              [_______________| ==> | handler 2 |
                                    |   ...     |

Logging tree

Loggers are stored in a tree structure, with the following properties :

• messages handled by a logger (after level filtering) are passed to its ancestor's handlers (this can be overriden with the set_propagate method).
• if not set, the level of a logger is that of its closest ancestor whose level is set (or NoLevel if there is no such ancestor)

Example

                       A (Info, Cli Debug)
                     /    \
                  A.B      A.C
                 /            \
            A.B.D (Warning)    A.C.E (Debug, (File "f", Debug),
                                                propagate=false)

For example, with the above logging tree

• logs made to A, A.B or A.C of level Info or more are written to the stdout.
• logs made to A.B.D of level Warning or above are written the stdout.
• logs made to A.C.E are only written to the file "f"

Levels

To each logger 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.
6. NoLevel : used to filter out all messages.

Log items

A log item has type

    type log_item = {
        level : level;
        logger_name : string;
        msg : string;
        tags : tag list
      } 

where the tag type is defined by the Handlers module.

Defaults

Default Handlers

By default, two handlers are provided. They are instantiated with a level of their own to filter messages :

• 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)) 

Note that file handlers will write to files in the logs folder in the current path, creating it if it doesn't exist. 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 (in which case it will not be part of the logging tree)

 let logger1 = new Logging.logger "my_logger1" 

or through helper functions of the The Logging module module.

Usage

A logger object has three methods for each of the log levels:

• one that takes a formatting string and parameters (printf like)

  logger1#debug "Myvar : %s" (to_string myvar); 

• one that takes a string lazy_t

  logger1#ldebug (lazy (heavy_calculation ())); 

• one that takes a string

   logger1#sdebug (to_string myvar);

The Logging module

The Easy_logging.Logging module is that application of MakeLogging over DefaultHandlers. It provides two functions :

•  val make_logger :
   ?propagate:bool -> string -> log_level -> Default_handlers.desc list 

  Instantiates a logger with some paramters, and adds it to the logging tree.

•  val get_logger : string -> logger 

  Returns a registered logger, or creates a new one if it doesn't exist.

The MakeLogging functor

The MakeLogging functor takes a Easy_logging__.Easy_logging_types.HandlersT typed module, and creates a Logging module.

WARNING

When declaring your Handlers module, do not coerce it the type HandlersT, because then its internal types t and desc won't be accessible.

Example

Here is a very simple example :

module MyHandlers =
  struct
    type t = string -> unit
    type desc = string list ref
    let set_formatter _ _ = ()
    let set_level _ _ = ()
    let apply h (item : log_item) = h item.msg
    let make (_internal : desc) =
      fun s -> _internal := s::!_internal
  end

module MyLogging = MakeLogging(MyHandlers)

let l = ref [];;
let mylogger = MyLogging.make_logger "mylogger" Debug [l];;
mylogger#info "this is a message";