(lispkit log)

Library (lispkit log) defines a simple logging API for LispKit. Log entries are sent to a logger. A logger processes each log entry, e.g. by adding or filtering information, and eventually persists it if the severity of the log entry is at or above the level of the severity of the logger. Supported are logging to a port and into a file. The macOS IDE LispPad implements a special version of (lispkit log) which makes log messages available in a session logging user interface supporting filtering, sorting, and exporting of log entries.

A log entry consists of the following four components: a timestamp, a severity, a sequence of tags, and a log message. Timestamps are generated via current-second. There are five severities, represented as symbols, supported by this library: debug, info, warn, err, and fatal. Also tags are represented as symbols. The sequence of tags is represented as a list of symbols. A log message is a string.

Logging functions take the logger as an optional argument. If it is not provided, the current logger is chosen. The current logger is represented via the parameter object current-logger. The current logger is initially set to default-logger.

Log severities

Log severities are represented using symbols. The following symbols are supported: debug (0), info (1), warn (2), err (3), and fatal (4). Each severity has an associated severity level (previously listed in parenthesis for each severity). The higher the level, the more severe a logged issue.

default-severity

The default logging severity that is used if no severity is specified (initially 'debug) when a new empty logger is created via procedure logger.

(severity? obj)

Returns #t if obj is an object representing a log severity, #f otherwise. The following symbols are representing severities: debug, info, warn, err, and fatal.

(severity->level sev)

Returns the severity level of severity sev as a fixnum.

(severity->string sev)

Returns a human readable string (in English) for the default textual representation of the given severity sev.

Log formatters

Log formatters are used by port and file loggers to map a structured logging request consisting of a timestamp, severity, log message, and logging tags into a string.

default-log-formatter

The default log formatting procedure. It is used by default when a new port or file logger gets created and no formatter procedure is provided.

(long-log-formatter timestamp sev message tags)

Formatter procedure using a long format.

(short-log-formatter timestamp sev message tags)

Formatter procedure using a short format.

Logger objects

default-logger

The default logger that is initially created by the logging library. The native implementation for LispKit logs to standard out, the native implementation for LispPad logs into the session logging system of LispPad.

current-logger

Parameter object referring to the current logger that is used as a default if no logger object is provided for a logging request. Initially current-logger is set to default-logger.

logger-type-tag

Symbol representing the logger type. The type-for procedure of library (lispkit type) returns this symbol for all logger objects.

(logger? obj)

Returns #t if obj is a logger object, #f otherwise.

(logger) (logger sev)

Returns a new empty logger with the lowest persisted severity sev. The logger does not perform any logging action. If sev is not provided, default-severity is used as a default.

(make-logger logproc lg) (make-logger logproc deinit lg)

Returns a new logger with logging procedure logproc, the de-initialization thunk deinit, and a logger object lg which can be used as a delegate and whose state will be inherited (e.g. the lowest persisted severity).

logproc gets called by logging requests via procedures such as log, log-debug, etc. logproc is a procedure with the following signature: (logproc timestamp sev message tags). timestamp is a floating-point number representing the number of seconds since 00:00 UTC on January 1, 1970 (e.g. returned by current-second), sev is a severity, message is the log message string, and tags is a list of logging tags. A tag is represented as a symbol.

Procedure deinit is called without parameters when the logger gets closed via close-logger before the de-initialization procedure of lg is called.

(make-port-logger port) (make-port-logger port formatter) (make-port-logger port formatter sev)

Returns a new port logger object which forwards log messages formatted by formatter to port if the severity is above the lowest persisted severity sev.

formatter is a procedure with the following signature: (formatter timestamp sev message tags). timestamp is a floating-point number representing the number of seconds since 00:00 UTC on January 1, 1970, sev is a severity, message is the log message string, and tags is a list of logging tags. A tag is represented as a symbol.

(make-file-logger path) (make-file-logger path formatter) (make-file-logger path formatter sev)

Returns a new file logger object which writes log messages formatted by formatter into a new file at the given file path path if the severity is above the lowest persisted severity sev.

formatter is a procedure with the following signature: (formatter timestamp sev message tags). timestamp is a floating-point number representing the number of seconds since 00:00 UTC on January 1, 1970, sev is a severity, message is the log message string, and tags is a list of logging tags. A tag is represented as a symbol.

(make-tag-logger tag lg)

Returns a new logger which includes tag into the tags to log and forwards the logging request to logger lg.

(make-filter-logger filter lg)

Returns a new logger which filters logging requests via procedure filter and forwards the requests which pass the filter to logger lg.

filter is a predicate with the following signature: (filter timestamp sev message tags). timestamp is a floating-point number representing the number of seconds since 00:00 UTC on January 1, 1970, sev is a severity, message is the log message string, and tags is a list of logging tags. A tag is represented as a symbol.

(close-logger lg)

Closes the logger lg by calling the deinitialization procedures of the full logger chain of lg.

(logger-addproc lg)

Returns the logging request procedure used by logger lg.

(logger-severity lg)

Returns the default logging severity used by logger lg.

(logger-severity-set! lg sev)

Sets the default logging severity used by logger lg to sev.

Logging procedures

(log sev message) (log sev message tag) (log sev message lg) (log sev message tag lg)

Logs message string message with severity sev into logger lg with tag if provided. If lg is not provided, the current logger (as defined by parameter object current-logger) is used.

(log-debug message) (log-debug message tag) (log-debug message lg) (log-debug message tag lg)

Logs message string message with severity debug into logger lg with tag if provided. If lg is not provided, the current logger (as defined by parameter object current-logger) is used.

(log-info message) (log-info message tag) (log-info message lg) (log-info message tag lg)

Logs message string message with severity info into logger lg with tag if provided. If lg is not provided, the current logger (as defined by parameter object current-logger) is used.

(log-warn message) (log-warn message tag) (log-warn message lg) (log-warn message tag lg)

Logs message string message with severity warn into logger lg with tag if provided. If lg is not provided, the current logger (as defined by parameter object current-logger) is used.

(log-error message) (log-error message tag) (log-error message lg) (log-error message tag lg)

Logs message string message with severity error into logger lg with tag if provided. If lg is not provided, the current logger (as defined by parameter object current-logger) is used.

(log-fatal message) (log-fatal message tag) (log-fatal message lg) (log-fatal message tag lg)

Logs message string message with severity fatal into logger lg with tag if provided. If lg is not provided, the current logger (as defined by parameter object current-logger) is used.

Logging syntax

(log-time expr) (log-time expr descr) (log-time expr descr tag) (log-time expr descr tag lg)

Log the time for executing expression expr into logger lg. descr is a description string and tag is a logging tag. If lg is not provided, the current logger (as defined by parameter object current-logger) is used.

(log-using lg body ...)

Assigns lg as the current logger and executed expressions body ... in the context of this assignment.

(log-into-file filepath body ...)

Creates a new file logger at file path filepath, assigns the new file logger to parameter object current-logger and executes the statements body ... in the context of this assignment.

(log-with-tag tag body ...)

Creates a new logger which appends tag to the tags logged to current-logger and assigns the new logger to current-logger. body ... gets executed in the context of this assignment.

(log-from-severity sev body ...)

Modifies the current logger setting its lowest persisted severity to sev and executing body ... in the context of this change. Once body ... has been executed, the lowest persisted severity is set back to its original value.

(log-dropping-below-severity sev body ...)

Creates a new logger on top of current-logger which filters out all logging requests with a severity level below the severity level of sev and assigns the new logger to current-logger. body ... gets executed in the context of this assignment.