# (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)** \
\&#xNAN;**(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*****)** \
\&#xNAN;**(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*****)** \
\&#xNAN;**(make-port-logger *****port formatter*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(make-file-logger *****path formatter*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(log *****sev message tag*****)**\
\&#xNAN;**(log *****sev message lg*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(log-debug *****message tag*****)**\
\&#xNAN;**(log-debug *****message lg*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(log-info *****message tag*****)**\
\&#xNAN;**(log-info *****message lg*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(log-warn *****message tag*****)**\
\&#xNAN;**(log-warn *****message lg*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(log-error *****message tag*****)**\
\&#xNAN;**(log-error *****message lg*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(log-fatal *****message tag*****)**\
\&#xNAN;**(log-fatal *****message lg*****)**\
\&#xNAN;**(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*****)** 
\
\&#xNAN;**(log-time *****expr descr*****)**\
\&#xNAN;**(log-time *****expr descr tag*****)**\
\&#xNAN;**(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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://www.lisppad.app/libraries/lispkit/lispkit-log.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.