easy_logging

Easy logging

Logging library inspired by the Python logging module.

Easy_logging allows fine-grained tuning of of when and where and how log messages are printed, with relatively low configuration, and simple logger configuration and usage.

It has the following features :

• one line logger creation
• log messages printf style, or provide string or string lazy_t message
• loggers for tree architecture for easy level and handlers configuration
• handlers associated to each logger will filter, format and treat the message independantly
• use tags and tag generators to add contextual information to log messages
• use default handlers for outputing log messages to stdout, stderr or to a file
• declare your own handler for anything else

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

Table of contents

1. Overall description (see also Easy_logging)

2. defaults

   1. Handlers (see also Easy_logging__Handlers)
   2. Loggers (see also Easy_logging.Logging.logger )
   3. The Logging module (see also Easy_logging.Logging)
3. The MakeLogging functor (see also Easy_logging__Make_logging.MakeLogging )
4. More examples
5. Index of modules

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. Trace : used between info and debug
3. Info : used to trace program execution.
4. Warning : used for warnings.
5. Error : used for errors.
6. Flash : used for one-shot debugging: displays an easy to spot message.
7. NoLevel : used to filter out all messages.

Log items

A log item has type

type log_item = {
    level : level;          (* the level of the log item *)
    logger_name : string;   (* the name of the logger to which the log call was passed *)
    msg : string;           (* the actual log message *)
    tags : string list      (* a list of tags *)
  } 

Handlers

Four handler creation helper function are provided. They instantiate handlers with a level of their own to filter messages :

• Cli handler: outputs colored messages to stdout.

  let h = Handlers.make (Cli Debug) 

• CliErr handler: outputs colored messages to stderr.

  let h = Handlers.make (CliErr Debug) 

• File handler : outputs messages to a given file.

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

• RotatingFile handler : outputs messages to a given file. Takes as argument the max number of kb per log file, and the number of backup log files.

  let h = Handlers.make (RotatingFile ("filename", Debug, 65536, 3)) 

Log file creation is governed by configuration values (setting up file name prefix/suffix, folder, file creation mode, etc...). The configuration can be specified when creating the handlers explicitely (like above), and a default configuration can be set in the Logging module.

See more at Easy_logging.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 the application of MakeLogging over Handlers. It provides two functions :

• val make_logger :
  ?propagate:bool -> string -> log_level -> 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.

• val set_handlers_config : Handlers.config -> unit

  Sets the default handlers configuration, used when creating new handlers via make_logger.

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.

Examples

See the examples page for more examples.

Index of modules

1. Easy_logging__Colorize
2. Easy_logging
3. Easy_logging__Formatters
4. Easy_logging__Handlers
5. Easy_logging__Logging_infra
6. Easy_logging__Logging_types
7. Easy_logging__Make_logging