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 ($):

Operator	Output
$date	Current date
$time	Current time
$datetime	$dateT$time
$app	os.getAppFilename()
$appname	base name of $app
$appdir	directory name of $app
$levelid	first letter of log level
$levelname	log level name

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. Warning: When logging on disk or console, only error and fatal messages are flushed out immediately. Use flushFile() where needed.

Imports

strutils, times, os

Types

Level = enum
  lvlAll,                     ## all levels active
  lvlDebug,                   ## debug level (and any above) active
  lvlInfo,                    ## info level (and any above) active
  lvlNotice,                  ## info notice (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

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

ConsoleLogger = ref object of Logger

logger that writes the messages to the console

FileLogger = ref object of Logger
  file*: File                  ## the wrapped file.

logger that writes the messages to a file

RollingFileLogger = ref object of FileLogger
  maxLines: int
  curLine: int
  baseName: string
  baseMode: FileMode
  logFiles: int
  bufSize: int

logger that writes the messages to a file and performs log rotation

Consts

LevelNames: array[Level, string] = ["DEBUG", "DEBUG", "INFO", "NOTICE", "WARN", "ERROR",
                                "FATAL", "NONE"]

defaultFmtStr = "$levelname "

default format string

verboseFmtStr = "$levelid, [$datetime] -- $appname: "

Procs

proc substituteLog(frmt: string; level: Level; args: varargs[string, `$`]): string {.
    raises: [Exception], tags: [ReadIOEffect, TimeEffect].}

Format a log message using the frmt format string, level and varargs. See the module documentation for the format string syntax.

proc newConsoleLogger(levelThreshold = lvlAll; fmtStr = defaultFmtStr): ConsoleLogger {.
    raises: [], tags: [].}

Creates a new console logger. This logger logs to the console.

proc defaultFilename(): string {.raises: [], tags: [ReadIOEffect].}

Returns the default filename for a logger.

proc newFileLogger(file: File; levelThreshold = lvlAll; fmtStr = defaultFmtStr): FileLogger {.
    raises: [], tags: [].}

Creates a new file logger. This logger logs to file.

proc newFileLogger(filename = defaultFilename(); mode: FileMode = fmAppend;
                  levelThreshold = lvlAll; fmtStr = defaultFmtStr; bufSize: int = - 1): FileLogger {.
    raises: [Exception, IOError], tags: [].}

Creates a new file logger. This logger logs to a file, specified by fileName. Use bufSize as size of the output buffer when writing the file (-1: use system defaults, 0: unbuffered, >0: fixed buffer size).

proc newRollingFileLogger(filename = defaultFilename();
                         mode: FileMode = fmReadWrite; levelThreshold = lvlAll;
                         fmtStr = defaultFmtStr; maxLines = 1000; bufSize: int = - 1): 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. Use bufSize as size of the output buffer when writing the file (-1: use system defaults, 0: unbuffered, >0: fixed buffer size).

proc addHandler(handler: Logger) {.raises: [], tags: [].}

Adds handler to the list of handlers.

proc getHandlers(): seq[Logger] {.raises: [], tags: [].}

Returns a list of all the registered handlers.

proc setLogFilter(lvl: Level) {.raises: [], tags: [].}

Sets the global log filter.

proc getLogFilter(): Level {.raises: [], tags: [].}

Gets the global log filter.

Methods

method log(logger: Logger; level: Level; args: varargs[string, `$`]) {.
    raises: [Exception], gcsafe, tags: [TimeEffect, WriteIOEffect, ReadIOEffect], base.}

Override this method in custom loggers. Default implementation does nothing.

method log(logger: ConsoleLogger; level: Level; args: varargs[string, `$`]) {.
    raises: [Exception], tags: [ReadIOEffect, TimeEffect, WriteIOEffect].}

Logs to the console using logger only.

method log(logger: FileLogger; level: Level; args: varargs[string, `$`]) {.
    raises: [IOError, Exception], tags: [WriteIOEffect, ReadIOEffect, TimeEffect].}

Logs to a file using logger only.

method log(logger: RollingFileLogger; level: Level; args: varargs[string, `$`]) {.
    raises: [OSError, Exception, IOError],
    tags: [ReadIOEffect, WriteIOEffect, TimeEffect].}

Logs to a file using rolling logger only.

Templates

template log(level: Level; args: varargs[string, `$`])

Logs a message to all registered handlers at the given level.

template debug(args: varargs[string, `$`])

Logs a debug message to all registered handlers.

Messages that are useful to the application developer only and are usually turned off in release.

template info(args: varargs[string, `$`])

Logs an info message to all registered handlers.

Messages that are generated during the normal operation of an application and are of no particular importance. Useful to aggregate for potential later analysis.

template notice(args: varargs[string, `$`])

Logs an notice message to all registered handlers.

Semantically very similar to info, but meant to be messages you want to be actively notified about (depending on your application). These could be, for example, grouped by hour and mailed out.

template warn(args: varargs[string, `$`])

Logs a warning message to all registered handlers.

A non-error message that may indicate a potential problem rising or impacted performance.

template error(args: varargs[string, `$`])

Logs an error message to all registered handlers.

A application-level error condition. For example, some user input generated an exception. The application will continue to run, but functionality or data was impacted, possibly visible to users.

template fatal(args: varargs[string, `$`])

Logs a fatal error message to all registered handlers.

A application-level fatal condition. FATAL usually means that the application cannot go on and will exit (but this logging event will not do that for you).