Module log

Log library provides logging facilities.

The module exposes extension points. It is possible to provide both the custom printing function and the custom log saving function.
The module is callable. Thus:

local log = require 'log' log("MODULE", "INFO", "message")

calls the log.trace function.

Type log

log.displaylogger(module, severity, msg)

Default logger for instant display.
log.format

Format is a string used to apply specific formating before the log is outputted.
log.musttrace(modulename, severity)

Determines whether a log must be traced depending on its severity and the module issuing the log.
log.setlevel(slevel, varargs)

Sets the log level for a list of module names.
log.storelogger(module, severity, msg)

Logger function for log storage.
log.trace(modulename, severity, fmt, varargs)

Prints out a log entry according to the module and the severity of the log entry.

Type log

Field(s)

log.displaylogger(module, severity, msg)

Default logger for instant display.

This logger can be replaced by a custom function. It is called only if the log needs to be traced.

Parameters

  • #string module : string identifying the module that issues the log

  • severity : string representing the log level, see log#levels.

  • msg : string containing the message to log.

#string log.format

Format is a string used to apply specific formating before the log is outputted.

Within a format, the following tokens are available (in addition to standard text)

  • %l => the actual log (given in 3rd argument when calling log() function)
  • %t => the current date
  • %m => module name
  • %s => log level (severity), see log#levels
log.musttrace(modulename, severity)

Determines whether a log must be traced depending on its severity and the module issuing the log.

This function is mostly useful to protect log() calls which involve costly computations

Parameters

  • modulename : string identifying the module that issues the log.

  • severity : string representing the log level, see log#levels.

Return values

  1. `nil' if the message of the given severity by the given module should not be printed.

  2. true if the message should be printed.

Usage:


   if log.musttrace('SAMPLE', 'DEBUG') then
       log('SAMPLE', 'DEBUG', "Here are some hard-to-compute info: %s",
           computeAndReturnExpensiveDebugString())
   end
log.setlevel(slevel, varargs)

Sets the log level for a list of module names.

If no module name is given, the default log level is affected

Parameters

  • slevel : level as in log#levels

  • varargs : Optional list of modules names (string) to apply the level to.

Return value

nothing.

log.storelogger(module, severity, msg)

Logger function for log storage.

This logger can be replaced by a custom function. There is no default store logger. It is called only if the log needs to be traced (see log.musttrace) and after the log has been displayed using {displaylogger}.

Parameters

  • module : string identifying the module thats issues the log

  • severity : string representing the log level, see log#levels.

  • msg : string containing the message to log.

log.trace(modulename, severity, fmt, varargs)

Prints out a log entry according to the module and the severity of the log entry.

This function uses log.format and log.timestampformat to create the final message string. It calls log.displaylogger and log.storelogger.

Parameters

  • modulename : string identifying the module that issues the log.

  • severity : string representing the level in log#levels.

  • fmt : string format that holds the log text the same way as string.format does.

  • varargs : additional arguments can be provided (as with string.format).

Usage:

trace("MODULE", "INFO", "message=%s", "sometext").

Type levels

Log levels are strings used to filter logs.

Levels are to be used both in log filtering configuration (see log.setlevel) and each time log.trace function is used to issue a new log.

Levels are ordered by verbosity/severity level.

While configuring log filtering, if you set a module log level to 'INFO' level for exemple, you enable all logs up to 'INFO', that is to say that logs with 'WARNING' and 'ERROR' severities will be displayed too.

Built-in values (in order from the least verbose to the most): - 'NONE': filtering only: when no log is wanted - 'ERROR': filtering or tracing level - 'WARNING': filtering or tracing level - 'INFO': filtering or tracing level - 'DETAIL': filtering or tracing level - 'DEBUG': filtering or tracing level - 'ALL': filtering only: when all logs are to be displayed