(lispkit log)
Last updated
Last updated
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 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 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.
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.
Formatter procedure using a long format.
Formatter procedure using a short format.
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.
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.
Symbol representing the logger type. The type-for procedure of library (lispkit type) returns this symbol for all logger objects.
Returns #t if obj is a logger object, #f otherwise.
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.
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.
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.
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.
Returns a new logger which includes tag into the tags to log and forwards the logging request to logger 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.
Closes the logger lg by calling the deinitialization procedures of the full logger chain of lg.
Returns the logging request procedure used by logger lg.
Returns the default logging severity used by logger lg.
Sets the default logging severity used by logger lg to sev.
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.
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.
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.
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.
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.
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.
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.
Assigns lg as the current logger and executed expressions body ... in the context of this assignment.
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.
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.
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.
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.
default-log-formatter
(long-log-formatter timestamp sev message tags)
(short-log-formatter timestamp sev message tags)
default-logger
current-logger
logger-type-tag
(logger? obj)
(logger) (logger sev)
(make-logger logproc lg) (make-logger logproc deinit lg)
(make-port-logger port) (make-port-logger port formatter) (make-port-logger port formatter sev)
(make-file-logger path) (make-file-logger path formatter) (make-file-logger path formatter sev)
(make-tag-logger tag lg)
(make-filter-logger filter lg)
(close-logger lg)
(logger-addproc lg)
(logger-severity lg)
(logger-severity-set! lg sev)
(log sev message) (log sev message tag) (log sev message lg) (log sev message tag lg)
(log-debug message) (log-debug message tag) (log-debug message lg) (log-debug message tag lg)
(log-info message) (log-info message tag) (log-info message lg) (log-info message tag lg)
(log-warn message) (log-warn message tag) (log-warn message lg) (log-warn message tag lg)
(log-error message) (log-error message tag) (log-error message lg) (log-error message tag lg)
(log-fatal message) (log-fatal message tag) (log-fatal message lg) (log-fatal message tag lg)
(log-time expr) (log-time expr descr) (log-time expr descr tag) (log-time expr descr tag lg)
(log-using lg body ...)
(log-into-file filepath body ...)
(log-with-tag tag body ...)
(log-from-severity sev body ...)
(log-dropping-below-severity sev body ...)
