Module logging

This module implements a simple logger. It has been designed to be as simple as possible to avoid bloat, if this library does not fulfill your needs, write your own.

Format strings support the following variables which must be prefixed with the dollar operator ($):

OperatorOutput
$dateCurrent date
$timeCurrent time
$appos.getAppFilename()

The following example demonstrates logging to three different handlers simultaneously:

var L = newConsoleLogger()
var fL = newFileLogger("test.log", fmtStr = verboseFmtStr)
var rL = newRollingFileLogger("rolling.log", fmtStr = verboseFmtStr)
addHandler(L)
addHandler(fL)
addHandler(rL)
info("920410:52 accepted")
warn("4 8 15 16 23 4-- Error")
error("922044:16 SYSTEM FAILURE")
fatal("SYSTEM FAILURE SYSTEM FAILURE")

Warning: The global list of handlers is a thread var, this means that the handlers must be re-added in each thread.

Types

Level = enum 
  lvlAll,                     ## all levels active
  lvlDebug,                   ## debug level (and any above) active
  lvlInfo,                    ## info level (and any above) active
  lvlWarn,                    ## warn level (and any above) active
  lvlError,                   ## error level (and any above) active
  lvlFatal,                   ## fatal level (and any above) active
  lvlNone                     ## no levels active
logging level   Source
Logger = ref object of RootObj
  levelThreshold*: Level      ## only messages of level >= levelThreshold
                              ## should be processed
  fmtStr: string              ## = defaultFmtStr by default, see substituteLog for $date etc.
  
abstract logger; the base type of all loggers   Source
ConsoleLogger = ref object of Logger
logger that writes the messages to the console   Source
FileLogger = ref object of Logger
  f: File
logger that writes the messages to a file   Source
RollingFileLogger = ref object of FileLogger
  maxLines: int
  curLine: int
  baseName: string
  baseMode: FileMode
  logFiles: int
logger that writes the messages to a file and performs log rotation   Source

Consts

LevelNames: array[Level, string] = ["DEBUG", "DEBUG", "INFO", "WARN", "ERROR", 
                                    "FATAL", "NONE"]
  Source
defaultFmtStr = ""
default string between log level and message per logger   Source
verboseFmtStr = "$date $time "
  Source

Procs

proc defaultFilename(): string {.raises: [], tags: [ReadIOEffect].}
Returns the default filename for a logger.   Source
proc newConsoleLogger(levelThreshold = lvlAll; fmtStr = defaultFmtStr): ConsoleLogger {.
    raises: [], tags: [].}
Creates a new console logger. This logger logs to the console.   Source
proc newFileLogger(filename = defaultFilename(); mode: FileMode = fmAppend; 
                   levelThreshold = lvlAll; fmtStr = defaultFmtStr): FileLogger {.
    raises: [Exception, IOError], tags: [].}
Creates a new file logger. This logger logs to a file.   Source
proc newRollingFileLogger(filename = defaultFilename(); 
                          mode: FileMode = fmReadWrite; levelThreshold = lvlAll; 
                          fmtStr = defaultFmtStr; maxLines = 1000): RollingFileLogger {.
    raises: [Exception, IOError, OverflowError], tags: [ReadIOEffect].}
Creates a new rolling file logger. Once a file reaches maxLines lines a new log file will be started and the old will be renamed.   Source
proc addHandler(handler: Logger) {.raises: [], tags: [].}
Adds handler to the list of handlers.   Source
proc getHandlers(): seq[Logger] {.raises: [], tags: [].}
Returns a list of all the registered handlers.   Source
proc setLogFilter(lvl: Level) {.raises: [], tags: [].}
Sets the global log filter.   Source
proc getLogFilter(): Level {.raises: [], tags: [].}
Gets the global log filter.   Source

Methods

method log(logger: Logger; level: Level; frmt: string; 
           args: varargs[string, `$`]) {.raises: [Exception], 
    tags: [TimeEffect, WriteIOEffect, ReadIOEffect].}
Override this method in custom loggers. Default implementation does nothing.   Source
method log(logger: ConsoleLogger; level: Level; frmt: string; 
           args: varargs[string, `$`]) {.raises: [IOError, ValueError], 
    tags: [WriteIOEffect, ReadIOEffect, TimeEffect].}
Logs to the console using logger only.   Source
method log(logger: FileLogger; level: Level; frmt: string; 
           args: varargs[string, `$`]) {.raises: [IOError, ValueError], 
    tags: [WriteIOEffect, ReadIOEffect, TimeEffect].}
Logs to a file using logger only.   Source
method log(logger: RollingFileLogger; level: Level; frmt: string; 
           args: varargs[string, `$`]) {.
    raises: [OSError, Exception, IOError, ValueError], 
    tags: [ReadIOEffect, WriteIOEffect, TimeEffect].}
Logs to a file using rolling logger only.   Source

Templates

template log(level: Level; frmt: string; args: varargs[string, `$`])
Logs a message to all registered handlers at the given level.   Source
template debug(frmt: string; args: varargs[string, `$`])
Logs a debug message to all registered handlers.   Source
template info(frmt: string; args: varargs[string, `$`])
Logs an info message to all registered handlers.   Source
template warn(frmt: string; args: varargs[string, `$`])
Logs a warning message to all registered handlers.   Source
template error(frmt: string; args: varargs[string, `$`])
Logs an error message to all registered handlers.   Source
template fatal(frmt: string; args: varargs[string, `$`])
Logs a fatal error message to all registered handlers.   Source