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.

Basic usage

To get started, first create a logger:

import logging

var logger = newConsoleLogger()

The logger that was created above logs to the console, but this module also provides loggers that log to files, such as the FileLogger. Creating custom loggers is also possible by inheriting from the Logger type.

Once a logger has been created, call its log proc to log a message:

logger.log(lvlInfo, "a log message")
# Output: INFO a log message

The INFO within the output is the result of a format string being prepended to the message, and it will differ depending on the message's level. Format strings are explained in more detail here.

There are six logging levels: debug, info, notice, warn, error, and fatal. They are described in more detail within the Level enum's documentation. A message is logged if its level is at or above both the logger's levelThreshold field and the global log filter. The latter can be changed with the setLogFilter proc.

Warning:

For loggers that log to a console or to files, only error and fatal messages will cause their output buffers to be flushed immediately. Use the flushFile proc to flush the buffer manually if needed.

Handlers

When using multiple loggers, calling the log proc for each logger can become repetitive. Instead of doing that, register each logger that will be used with the addHandler proc, which is demonstrated in the following example:

import logging

var consoleLog = newConsoleLogger()
var fileLog = newFileLogger("errors.log", levelThreshold=lvlError)
var rollingLog = newRollingFileLogger("rolling.log")

addHandler(consoleLog)
addHandler(fileLog)
addHandler(rollingLog)

After doing this, use either the log template or one of the level-specific templates, such as the error template, to log messages to all registered handlers at once.

# This example uses the loggers created above
log(lvlError, "an error occurred")
error("an error occurred")  # Equivalent to the above line
info("something normal happened")  # Will not be written to errors.log

Note that a message's level is still checked against each handler's levelThreshold and the global log filter.

Format strings

Log messages are prefixed with format strings. These strings contain placeholders for variables, such as $time, that are replaced with their corresponding values, such as the current time, before they are prepended to a log message. Characters that are not part of variables are unaffected.

The format string used by a logger can be specified by providing the fmtStr argument when creating the logger or by setting its fmtStr field afterward. If not specified, the default format string is used.

The following variables, which must be prefixed with a dollar sign ($), are available:

Variable	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

Note that $app, $appname, and $appdir are not supported when using the JavaScript backend.

The following example illustrates how to use format strings:

import logging

var logger = newConsoleLogger(fmtStr="[$time] - $levelname: ")
logger.log(lvlInfo, "this is a message")
# Output: [19:50:13] - INFO: this is a message

Notes when using multiple threads

There are a few details to keep in mind when using this module within multiple threads:

The global log filter is actually a thread-local variable, so it needs to be set in each thread that uses this module.
The list of registered handlers is also a thread-local variable. If a handler will be used in multiple threads, it needs to be registered in each of those threads.

Imports

strutils, times, os

Types

Level = enum lvlAll, lvlDebug, lvlInfo, lvlNotice, lvlWarn, lvlError, lvlFatal, lvlNone

Enumeration of logging levels.

Debug messages represent the lowest logging level, and fatal error messages represent the highest logging level. lvlAll can be used to enable all messages, while lvlNone can be used to disable all messages.

Typical usage for each logging level, from lowest to highest, is described below:

Debug - debugging information helpful only to developers
Info - anything associated with normal operation and without any particular importance
Notice - more important information that users should be notified about
Warn - impending problems that require some attention
Error - error conditions that the application can recover from
Fatal - fatal errors that prevent the application from continuing

It is completely up to the application how to utilize each level.

Individual loggers have a levelThreshold field that filters out any messages with a level lower than the threshold. There is also a global filter that applies to all log messages, and it can be changed using the setLogFilter proc.