easy_logging

Module to log messages. Aimed at being both powerful and easy to use
IN THIS PACKAGE

easy_logging

Easy logging %%VERSION%%

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

Reference

  • Author: %%PKG_AUTHORS%%
  • Homepage: %%PKG_HOMEPAGE%%
  • Repo: %%PKG_REPO%%