Common Lisp Package: LOG4CL-IMPL

README:

FUNCTION

Public

ADD-APPENDER (LOGGER APPENDER)

Adds appender to the logger

ADD-WATCH-TOKEN (TOKEN &KEY (TEST #'EQUAL) KEY (HIERARCHY (CURRENT-HIERARCHY)))

Add unique watch token to the HIERARCHY, uniqueness is determined by TEST and KEY arguments which are passed to FIND and REMOVE. Any matching token is already present, the old token is removed and new one is inserted. The per-hierarchy lock is held doing the operation. Automatically starts hierarchy watcher thread, if it was not already started

ALL-CONFIGURATIONS

Returns the *CONFIGURATIONS* list

CLEAR-LOGGING-CONFIGURATION

Delete all loggers configuration, leaving only LOG4CL.SELF

EFFECTIVE-APPENDERS (LOGGER)

Return the list of all appenders that logger output could possible go to, including inherited one

EFFECTIVE-LOG-LEVEL (LOGGER)

Return logger's own log level (if set) or the one it had inherited from parent

HIERARCHY-INDEX (HIERARCHY)

Return the hierarchy index for the specified hierarchy. Hierarchy must be already a number or a unique identifier suitable for comparing using EQL. If hierarchy is a string, it will be interned in the current package

LIST-CONFIGURATIONS (&OPTIONAL (STREAM *STANDARD-OUTPUT*))

Prints the *CONFIGURATIONS* list

LOG-CONFIG (&REST ARGS)

User friendly way of configuring loggers. General syntax is: (LOG-CONFIG [LOGGER-IDENTIFIER] OPTION1 OPTION2...) LOGGER-IDENTIFIER can be one of: * Logger instance ie result of (make-logger) expansion, or any form that returns a logger. * A list of logger categories, basically a shortcut for (MAKE-LOGGER '(CAT1 CAT2 CAT3)). An error will be given if logger does not exist. If you want to ensure logger is created, even if it did not exist before, use (LOG-CONFIG (MAKE-LOGGER ...) ...) If not specified, default logger will be root logger Valid options can be: Option | Description ---------------|--------------------------------------------------------------- :INFO | Or any other keyword identifying a log level, which can be :DEBUG | shortened to its shortest unambiguous prefix, such as :D ---------------|--------------------------------------------------------------- :CLEAR | Removes log level and appenders from any child loggers, | appenders are not removed from non-additive loggers ---------------|--------------------------------------------------------------- :ALL | Changes :CLEAR to remove appenders from non-additive | loggers ---------------|--------------------------------------------------------------- :SANE | Removes logger appenders, adds console appender with | pattern layout that makes messages look like this: | | [11:22:25] INFO {category.name} - message | | If used with :DAILY then console appender is not added, unless | :CONSOLE or :THIS-CONSOLE is explicitly used ---------------|--------------------------------------------------------------- :DAILY FILE | Adds file appender logging to the named file, which will | be rolled over every midnight into FILE.YYYYMMDD; Removes any | other FILE-APPENDER-BASE'ed appenders from the logger ---------------|--------------------------------------------------------------- :CONSOLE | Adds CONSOLE-APPENDER to the logger. Console appender logs | into the *DEBUG-IO* at the call site. | :THIS-CONSOLE | Adds FIXED-STREAM-APPENDER to the logger, with :stream argument | taken from the current value of *DEBUG-IO* ---------------|--------------------------------------------------------------- :STREAM stream | Adds FIXED-STREAM-APPENDER logging to specified stream ---------------|--------------------------------------------------------------- :PATTERN | For any new appenders added, specifies the conversion pattern for the | PATTERN-LAYOUT ---------------|--------------------------------------------------------------- :TWOLINE | Changes default pattern layout to print user log message or :2LINE | log message on 2nd line after the headers ---------------|--------------------------------------------------------------- :PROPERTIES | Configure with PROPERTY-CONFIGURATOR by parsing specified FILE | properties file ---------------|--------------------------------------------------------------- :WATCH | Used with :PROPERTIES, uses watcher thread to check | properties file modification time, and reloads if it changes ---------------|--------------------------------------------------------------- :IMMEDIATE- | Used with :SANE, :DAILY or :CONSOLE to create new appenders FLUSH | with :IMMEDIATE-FLUSH T option, which prevents automatic | startup of hierarchy watcher thread, which is used for | auto-flushing. ---------------|--------------------------------------------------------------- :OWN | For :SANE and :DAILY makes logger non-additive | otherwise additive flag will be set ---------------|--------------------------------------------------------------- Examples: * (LOG-CONFIG :D) -- Changes root logger level to debug * (LOG-CONFIG :SANE) -- Changes root logger level to info, removes its appenders, adds console appender with pattern layout * (LOG-CONFIG :SANE :THIS-CONSOLE) -- Same as above but adds fixed stream appender logging to current value of *DEBUG-IO* instead of regular console appender.. * (LOG-CONFIG :WARN :SANE :CLEAR :ALL) -- Changes root logger level to warnings, removes its appenders, adds console appender with pattern layout; then resets all child loggers log levels, and removes their appenders. * (LOG-CONFIG (MAKE-LOGGER :FOOBAR) :SANE :OWN :D :DAILY "debug.log") Configures the specified logger with debug log level, logging into file debug.log which will be rolled over daily, and makes it non-additive ie any messages will not be propagated to logger parents.

LOG-LEVEL-TO-STRING (LEVEL)

Return log-level string for the level

LOGGER-ADDITIVITY (LOGGER)

Return logger additivity

SETFLOGGER-ADDITIVITY (ADDITIVITY LOGGER)

Set logger appender additivity. Returns new additivity

LOGGER-APPENDERS (LOGGER)

Return the list of logger's own appenders. Please note that by default loggers inherit their parent logger appenders, see EFFECTIVE-APPENDERS

LOGGER-CATEGORIES (LOGGER)

Return LOGGER categories starting from parent logger as a newly consed list of strings

LOGGER-CATEGORY (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-CHILDREN (LOGGER)

Return a list of LOGGER's direct children

LOGGER-DEPTH (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-DESCENDANTS (LOGGER)

Return a list of LOGGER's descendants

LOGGER-LOG-LEVEL (LOGGER)

Return the logger own log level or NIL if unset. Please note that by default loggers inherit their parent logger log level, see EFFECTIVE-LOG-LEVEL

SETFLOGGER-LOG-LEVEL (LEVEL LOGGER)

Set logger log level. Returns logger own log level

LOGGER-NAME (LOGGER)

Return the name of the logger category itself (without parent loggers)

LOGGER-PARENT (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

MAKE-LOG-LEVEL (ARG)

Translate a more human readable log level into one of the log level constants, by calling LOG-LEVEL-FROM-OBJECT on ARG and current value of *PACKAGE*

MAP-LOGGER-CHILDREN (FUNCTION LOGGER)

Apply the function to all of logger's children (but not their descendants)

MAP-LOGGER-DESCENDANTS (FUNCTION LOGGER)

Apply the function to all of logger's descendants

REMOVE-ALL-APPENDERS (LOGGER)

Removes all appenders from the logger.

REMOVE-APPENDER (LOGGER APPENDER)

Removes APPENDER from the logger. APPENDER-REMOVED generic function will be called if appender was removed

REMOVE-WATCH-TOKEN (TOKEN &KEY (TEST #'EQUAL) KEY (HIERARCHY (CURRENT-HIERARCHY)))

Removes the watch token from the hierarchy, that matches the specified KEY and TEST arguments, which are passed to REMOVE function. Holds per-hierarchy lock doing its operation

RESET-LOGGING-CONFIGURATION

Clear the logging configuration in the current hierarchy, and configure root logger with INFO log level and a simple console appender

RESTORE (&OPTIONAL CONFIGURATION FROM-END)

Restore logging configuration CONFIGURATION, which can be a name, a CONFIGURATION instance, or a number indicating Nth (zero based) configuration in the *CONFIGURATIONS* list. NIL is treated as zero. When searching for the Before restoring the configuration, the current logging configuration is automatically saved under the name "Autosave <timestamp>", unless an equivalent configuration is already in the list If CONFIGURATION is NIL restores first element of *CONFIGURATIONS* that is not equivalent to the current configuration. So successive (RESTORE) will swap last two configurations

SAME-CONFIGURATION-P (C1 C2)

Compare two logging configurations and return T if they have exactly same loggers and levels

SAVE (&OPTIONAL NAME)

Save current logging configuration into configuration list. NAME -- specifies the name of this logging configuration, if NAME is not specified, one is automatically provided as "Saved on <timestamp>". If its equivalent to some other configuration, save it only if it had a different name, otherwise lift the older equivalent configuration to the top of the list. When *SAVE-CONFIGURATIONS-TO-FILE* is T (default) the configuration list list will also be saved to a file ".log4cl-configurations.lisp-expr" in user home directory. File name can be customized by changing *CONFIGURATIONS-FILE* variable

SET-LOG-LEVEL (LOGGER LEVEL &OPTIONAL (ADJUST-P T))

Set the log level of a logger. Log level is passed to MAKE-LOG-LEVEL to determine canonical log level. ADJUST-P controls if logger effective log level needs to be recalculated, the caller should NIL doing bulk operations that change the level of many loggers, as to avoid overhead. Returns if log level had changed as the 1st value and new level as the second value.

Undocumented

LOG4CL-ERROR (MESSAGE &REST ARGS)

SETFLOGGER-CATEGORY (NEW-VALUE INSTANCE)

SETFLOGGER-DEPTH (NEW-VALUE INSTANCE)

SETFLOGGER-PARENT (NEW-VALUE INSTANCE)

PATTERN-LAYOUT-ERROR (MESSAGE &REST ARGS)

START-HIERARCHY-WATCHER-THREAD

STOP-HIERARCHY-WATCHER-THREAD

Private

%GET-LOGGER (CATEGORIES CAT-SEP CAT-CASE &OPTIONAL FORCE-STRING-CASE (CREATEP T))

Retrieve or create a logger. CATEGORIES -- List of category names. SEPARATOR -- Category separator. Will only be used if logger did not exist before. CAT-CASE -- How each category case is treated. See NAMING-OPTION generic function for description FORCE-STRING-CASE -- Whenever elements of category which are strings, should also undergo case conversion according to CAT-CASE CREATEP -- Create the logger if it does not exist Note that its possible to receive a logger with different "official" category name then expected. For example if logger ONE:TWO:THREE was originally instantiated in a package which had custom category separator of "--", then LOGGER-CATEGORY of the returned logger will be ONE--TWO--THREE. But if a logger ONE:TWO:THREE:FOUR then the newly created logger FOUR will have official category name as "ONE--TWO--THREE:FOUR" FORCE-STRING-CASE should be used only when trying to create/find a logger, with its category name represented by a string entered by a user, since user would expect that any logger name he types, would get same treatment as symbol names he types. For example PROPERTY-CONFIGURATOR uses this to retrieve loggers based on the strings in configuration file:

ADJUST-LOGGER (LOGGER)

Recalculate LOGGER mask by finding out which log levels have reachable appenders.

APPLY-LOGGING-CONFIGURATION (CNF)

Restores logging configuration

AUTO-NAMED-P (CNF)

Test if logging configuration name was auto-generated

CALL-USER-LOG-MESSAGE (LOG-FUNC STREAM)

Calls the user log function, binding *INSIDE-USER-LOG-FUNCTION* for the duration to indicate that any errors must be re-thrown, rather then disable the appender

COMPILE-PATTERN-FORMAT (LAYOUT PATTERN)

Parses the pattern format and returns a function with lambda-list of (STREAM LOGGER LOG-LEVEL LOG-FUNC) that when called will output the log message to the stream with the specified format.

CONVERT-READ-CASE (STRING CASE)

Convert STRING according to CASE

CREATE-DELAYED-INSTANCE (INSTANCE)

First filter all properties through through INSTANCE-PROPERTY-FROM-STRING, and then create the instance

CURRENT-HIERARCHY

Return the currently active hierarchy

EXPAND-LOG-WITH-LEVEL (ENV LEVEL ARGS)

Returns a FORM that is used as an expansion of log-nnnnn macros

FORMAT-LOG-DATE (STREAM FMT-INFO UTC-P)

Helper function to print either %d or %D (date/time) pattern

FORMAT-STRING (STRING STREAM INFO &OPTIONAL (START 0) (END (LENGTH STRING)))

Write STRING to the STREAM, respecting flags in info

GET-LOGGER-INTERNAL (CATEGORIES CAT-SEP CAT-CASE &OPTIONAL FORCE-STRING-CASE (CREATEP T))

Retrieve or create a logger. CATEGORIES -- List of category names. SEPARATOR -- Category separator. Will only be used if logger did not exist before. CAT-CASE -- How each category case is treated. See NAMING-OPTION generic function for description FORCE-STRING-CASE -- Whenever elements of category which are strings, should also undergo case conversion according to CAT-CASE CREATEP -- Create the logger if it does not exist Note that its possible to receive a logger with different "official" category name then expected. For example if logger ONE:TWO:THREE was originally instantiated in a package which had custom category separator of "--", then LOGGER-CATEGORY of the returned logger will be ONE--TWO--THREE. But if a logger ONE:TWO:THREE:FOUR then the newly created logger FOUR will have official category name as "ONE--TWO--THREE:FOUR" FORCE-STRING-CASE should be used only when trying to create/find a logger, with its category name represented by a string entered by a user, since user would expect that any logger name he types, would get same treatment as symbol names he types. For example PROPERTY-CONFIGURATOR uses this to retrieve loggers based on the strings in configuration file:

HAVE-APPENDERS-FOR-LEVEL (LOGGER LEVEL)

Return non-NIL if logging with LEVEL will actually reach any appenders

HIERARCHY-WATCHER-ONCE

Do one iteration of watcher loop.

INCLUDE-BLOCK-DEBUG-NAME? (DEBUG-NAME)

Figures out if we should include the debug-name into the stack of nested blocks.. Should return the symbol to use. For now SBCL seems to use: SYMBOL => normal defun block (LABELS SYMBOL) => inside of labels function (FLET SYMBOL) => inside of flet function (LAMBDA (arglist) => inside of anonymous lambda (SB-PCL::FAST-METHOD SYMBOL ...) for defmethod (SB-PCL::VARARGS-ENTRY (SB-PCL::FAST-METHOD SYMBOL )) for defmethod with &rest parametwer (SB-C::HAIRY-ARG-PROCESSOR SYMBOL) => for functions with complex lambda lists In all of the above cases except LAMBDA we simply return SYMBOL, for LAMBDA we return the word LAMBDA and NIL for anything else. Example: As a result of this default logger name for SBCL for the following form: (defmethod foo () (labels ((bar () (funcall (lambda () (flet ((baz () (log-info "test"))) (baz)))))) (bar))) will be: package.foo.bar.baz

INTERN-BOOLEAN (VALUE)

Parse boolean value

IS-ENABLED-FOR (LOGGER LEVEL)

Returns t if log level is enabled for the logger in the context of the current application.

JOIN-CATEGORIES (SEPARATOR LIST)

Return a string with each element of LIST printed separated by SEPARATOR

LOG-EVENT-TIME

Returns the universal time of the current log event

LOG-LEVEL-TO-LC-STRING (LEVEL)

Return lower case log-level string for the level

LOG-WITH-LOGGER (LOGGER LEVEL LOG-FUNC)

Submit message to logger appenders, and its parent logger

LOGGER-CATEGORY-SEPARATOR (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-CHILD-HASH (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-NAME-LENGTH (LOGGER)

Return length of logger itself (without parent loggers)

LOGGER-NAME-START-POS (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-STATE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-STATE-ADDITIVITY (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-STATE-APPENDERS (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-STATE-LEVEL (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOGGER-STATE-MASK (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

MAYBE-FLUSH-APPENDER-STREAM (APPENDER STREAM)

Flush the APPENDER's stream if needed

MAYBE-RESTORE-CONFIGURATIONS

If configurations list empty and *CONFIGURATIONS-FILE* exists in home directory restore configuration list from it

NEXT-TIME-BOUNDARY (TIME CHECK-PERIOD)

Given universal time TIME return next boundary evenly divisible by CHECK-PERIOD seconds

PARSE-EXTRA-ARGS-IN-CURLY-BRACES (PATTERN START)

While next character at START is curly brace, collect anything between it and a closing curly brace into a string. For the set of empty curly braces, collects NIL. Return a list, with first element being new parse position, and rest being extra arguments collected Example: For the string {one}{}{three} will return the list (14 "one" NIL "three")

PARSE-LOGGER-HELPER (PARSER KEYWORD TOKENS VALUE)

Common helper that handles both .rootLogger= and .logger.name= lines

REMEMBER-LOGGING-CONFIGURATION (&OPTIONAL (LOGGER *ROOT-LOGGER*))

Utility method to make a list of logging configuration starting from LOGGER. Returns a list of CONFIGURATION-ELEMENT objects

SAVE-CONFIGURATION (CNF HAD-NAME-P)

Save CNF logging configuration into *CONFIGURATIONS* list. If its equivalent to some other configuration, save it only if it had a different name, otherwise lift the older equivalent configuration to the top of the list

SBCL-GET-BLOCK-NAME (ENV)

Return a list naming SBCL lexical environment. For example when compiling local function FOO inside a global function FOOBAR, will return (FOOBAR FOO)

SET-ADDITIVITY (LOGGER ADDITIVITY &OPTIONAL (ADJUST-P T))

Set logger additivity.

SHORTEST-PACKAGE-NAME (PACKAGE)

Return the shortest name or nickname of the package

SHOW-LOGGER-SETTINGS (LOGGER)

Print logger settings and its children to *STANDARD-OUTPUT* Example output: +ROOT, WARN | +-#<CONSOLE-APPENDER> | with #<PATTERN-LAYOUT> | :pattern [%P] %c %m%n | :immediate-flush: nil | :flush-interval: 1 +-LOG4CL | +-SELF (non-additive), DEBUG | | :config (:SANE, :OWN :TWOLINE :D) | | | +-#<CONSOLE-APPENDER 0x123123>, | | with #<PATTERN-LAYOUT> | | :pattern [%P] %c %m%n | | :immediate-flush: nil | | :flush-interval: 1 | +-#<DAILY-ROLLING-APPENDER 0x12345> | with #<SIMPLE-LAYOUT 1234> | :immediate-flush NIL | :flush-interval: 1 | +-OTHER, DEBUG

SPLIT-INTO-CATEGORIES (CATEGORY PACKAGE)

Splits the category name into a list of categories from parent to child. Uses NAMING-OPTION to determine category separator

SPLIT-STRING (STRING SEPARATOR &OPTIONAL SKIP-WHITESPACE-P)

Split the STRING into a list of strings. If SKIP-WHITESPACE-P is non-NIL strip whitespace from the string first

STRIP-WHITESPACE (STRING)

Strip tab and space characters from a string

TRIM-CONFIGURATION-LIST (&OPTIONAL (VAR '*CONFIGURATIONS*))

Trim the list in global variable VAR to at most *MAX-CONFIGURATIONS* elements

WRITE-LOG-LEVEL (LEVEL STREAM)

Print the log LEVEL's name to the STREAM

WRITE-STRING-MODIFY-CASE (STRING STREAM &OPTIONAL CASE (START 0) (END (LENGTH STRING)))

Helper function that writes STRING to STREAM, optionally doing case conversion.

Undocumented

%HIERARCHY-INDEX (NAME)

ADD-APPENDER-INTERNAL (LOGGER APPENDER &OPTIONAL (ADJUST-P T))

ADJUST-ALL-LOGGERS-STATE (NEW-LEN)

COMPILE-PATTERN (LAYOUT PATTERN)

COPY-LOGGER (INSTANCE)

COPY-LOGGER-STATE (INSTANCE)

CREATE-APPENDER-FILE (APPENDER)

CREATE-LOGGER (&KEY ((CATEGORY DUM65) NIL) ((CATEGORY-SEPARATOR DUM66) NIL) ((NAME-START-POS DUM67) 0) ((PARENT DUM68) NIL) ((DEPTH DUM69) 0) ((CHILD-HASH DUM70) NIL) ((STATE DUM71) (MAP-INTO (MAKE-ARRAY *HIERARCHY-MAX*) #'MAKE-LOGGER-STATE)))

CREATE-ROOT-LOGGER

CURRENT-STATE (LOGGER)

EXPAND-NAME-FORMAT (PATTERN TIME UTC-P)

HIERARCHY-WATCHER-DO-ONE-TOKEN (HIER TOKEN)

INTERN-CLASS-NAME (STRING)

LOG-APPENDER-ERROR (APPENDER CONDITION)

SETFLOGGER-CATEGORY-SEPARATOR (NEW-VALUE INSTANCE)

SETFLOGGER-CHILD-HASH (NEW-VALUE INSTANCE)

SETFLOGGER-NAME-START-POS (NEW-VALUE INSTANCE)

LOGGER-P (OBJECT)

SETFLOGGER-STATE (NEW-VALUE INSTANCE)

SETFLOGGER-STATE-ADDITIVITY (NEW-VALUE INSTANCE)

SETFLOGGER-STATE-APPENDERS (NEW-VALUE INSTANCE)

SETFLOGGER-STATE-LEVEL (NEW-VALUE INSTANCE)

SETFLOGGER-STATE-MASK (NEW-VALUE INSTANCE)

LOGGER-STATE-P (OBJECT)

MAKE-AUTOSAVE-CONFIGURATION

MAKE-LOGGER-STATE (&KEY ((APPENDERS DUM0) NIL) ((LEVEL DUM1) NIL) ((ADDITIVITY DUM2) T) ((MASK DUM3) 0))

MAYBE-CLOSE-FILE (APPENDER)

PARSE-CATEGORY-PRECISION (STRING)

PARSE-DATE-FORMAT-EXTRA-ARGS (FMT-INFO UTC-P PATTERN START)

PERFORM-DEFAULT-INIT

READ-CONFIGURATIONS-FROM-FILE (&OPTIONAL (FILE *CONFIGURATIONS-FILE*))

REMOVE-ALL-APPENDERS-INTERNAL (LOGGER &OPTIONAL (ADJUST-P T))

REMOVE-APPENDER-INTERNAL (LOGGER APPENDER &OPTIONAL (ADJUST-P T))

SAFE-INTERN (NAME)

SAVE-CONFIGURATIONS-TO-FILE (&OPTIONAL (FILE *CONFIGURATIONS-FILE*))

SET-DELAYED-INSTANCE-CLASS (INSTANCE VALUE)

SET-DELAYED-INSTANCE-PROPERTY (INSTANCE TOKENS VALUE)

SUBSTR (SEQ START &OPTIONAL END)

MACRO

Public

IN-LOG-HIERARCHY (&OPTIONAL HIERARCHY)

Sets the *CURRENT-HIERARCHY* to specified hierarchy, or the default one when NIL

IN-PACKAGE-LOG-HIERARCHY

Sets the *CURRENT-HIERARCHY* to specified hierarchy, or the default one when NIL

LOG-DEBUG (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-ERROR (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-FATAL (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-INFO (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-SEXP (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-DEBUG (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-ERROR (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-FATAL (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-INFO (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-TRACE (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER1 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER2 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER3 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER4 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER5 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER6 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER7 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER8 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-USER9 (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-WARN (&REST ARGS)

Expands into the log statement that will print each element of ARGS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. For constant string elements, it is output literally without printing its value. Example: (let ((a 1) (b '(two three))) (log-sexp "values are" a b)) will produce log message: [debug] - values are A=1 B=(TWO THREE)

LOG-SEXP-WITH-LEVEL (LEVEL &REST SEXPS &ENVIRONMENT ENV)

Expands into LOG-<LEVEL> log statement that will print each element of SEXPS in the form of ELEMENT=VALUE where ELEMENT will be the literal argument without evaluating it, and VALUE will be the result of evaluation. Constant string elements will be output directly. A pretty printer (pprint-newline :fill) format will be used as a separator between expressions, so that long expressions start on a new line, if *PRINT-PRETTY* is non-NIL Example: (let ((a 1) (b '(two three)) (c (loop for i from 1 to 15 collect i))) (log:sexp "values are" a b c)) will produce log message: [debug] - values are A=1 B=(TWO THREE) C=(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15) Separator between expression and value, which defaults to equal sign, and a suffix after each value, which defaults to " ~:_" (a space followed by conditional newline) can be customized per package via NAMING-OPTION generic function

LOG-TRACE (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER1 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER2 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER3 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER4 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER5 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER6 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER7 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER8 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-USER9 (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

LOG-WARN (&REST ARGS &ENVIRONMENT ENV)

Submit log message to the logging system. Whenever the message is actually displayed or not depends on logging system configuration at run-time. The ARGS are parsed as follows: 1. Determine a logger object If first argument is a constant list, constant symbol or a keyword, it is made into a logger object as described in the MAKE-LOGGER macro documentation If first argument is a constant string, logger name is auto-determined from context as described in the MAKE-LOGGER macro documentation, and system proceeds to step 2. Otherwise any non-NIL first argument is assumed to be a form, that when evaluated will return a logger object. 2. If there are remaining arguments, they are used as format control string and format arguments, to be passed into the FORMAT function to produce the log message, when one is produced. If there were no other arguments, then this macro expands into a form, that will return T or NIL depending if logging with specified log level will actually produce any log messages. Note that having log level enabled does not necessary mean logging with log level is enabled, it also takes into account whenever log message will reach any appenders.

WITH-LOG-HIERARCHY ((HIERARCHY) &BODY BODY)

Binds the *CURRENT-HIERARCHY* to the specified hierarchy for the dynamic scope of BODY. HIERARCHY can be hierarchy index or name

WITH-LOG-INDENT ((&OPTIONAL (INDENT '(1+ *LOG-INDENT*))) &BODY BODY)

Executes forms in BODY with *LOG-INDENT* set to INDENT

WITH-NDC-CONTEXT ((CONTEXT) &BODY BODY)

Execute forms in BODY with *NDC-CONTEXT* set to CONTEXT. The context is printed by the %x pattern layout format

WITH-PACKAGE-LOG-HIERARCHY (&BODY BODY)

Binds the *CURRENT-HIERARCHY* to the unique hierarchy for the current package for the dynamic scope of BODY.

Undocumented

MAKE-LOGGER (&OPTIONAL (ARG NIL ARG-P) &ENVIRONMENT ENV)

Private

WITH-PROPERTY-LOCATION ((LOCATION) &BODY BODY)

Run BODY with %PARSE-LINE and %PARSE-LINE-NUM bound to the remembered location, so that any errors signaled will have correct location

Undocumented

DEFINE-PATTERN-FORMATTER ((CHAR) &BODY BODY)

DEFLOG-MACROS (LEVELS)

DEFLOG-SEXP-MACROS (LEVELS)

FORWARD-FUNCTION (NAME FROM-NAME)

FORWARD-LEVELS (LEVELS)

FORWARD-MACRO (NAME FROM-NAME)

FORWARD-SEXP-LEVELS (LEVELS)

WITH-HIERARCHIES-LOCK (&BODY BODY)

WITH-HIERARCHY-LOCK ((&OPTIONAL (HIERARCHY (CURRENT-HIERARCHY))) &BODY BODY)

GENERIC-FUNCTION

Public

APPENDER-ADDED (LOGGER APPENDER)

Called when appender is added to a logger. Default method is used to keep logger count, and if re-implemented the (CALL-NEXT-METHOD) needs to be called.

APPENDER-DO-APPEND (APPENDER LOGGER LEVEL LOG-FUNC)

Writes the log message into the appender. Text of the log message is specified indirectly via LOG-FUNC argument, which will be a function that accepts a stream, and writes the text of log message to it. This function should first figure out or obtain the stream to write the log message to, and then call the LAYOUT-TO-STREAM function to have layout do actual formatting. If appender destination is ultimately not a stream, then it can obtain the full text of the log message by calling LAYOUT-TO-STREAM inside of WITH-OUTPUT-TO-STRING Example: (defmethod appender-do-append ((self custom-appender) logger level log-func) (let ((stream (custom-appender-destination))) (layout-to-stream (slot-value self 'layout) stream logger level log-func)) (values)) Return value of this function is ignored

APPENDER-FILENAME (APPENDER)

Returns the appenders file name

APPENDER-REMOVED (LOGGER APPENDER)

Called when appender is removed from a logger Default method is used to keep logger refcount, and calls CLOSE-APPENDER when it reaches zero. If re-implemented the (CALL-NEXT-METHOD) needs to be called

BACKUP-LOG-FILE (APPENDER LOG-FILENAME BACKUP-FILENAME)

Should move or rename LOG-FILENAME into the BACKUP-FILENAME. When this function is called, LOG-FILENAME is already closed. Implemented as generic function so its possible to write extensions that compress the backup log files automatically, or append to them. One possible extension could be having daily log file and a weekly backup, that is appended to each day

CLOSE-APPENDER (APPENDER)

Called when appender refcount reaches zero after being positive. Should close any streams or files that appender had opened.

CONFIGURE (CONFIGURATOR SOURCE &KEY AUTO-RELOAD &ALLOW-OTHER-KEYS)

Configure the logging system from specified source

ENCLOSING-SCOPE-BLOCK-NAME (PACKAGE ENV)

Is called by RESOLVE-DEFAULT-LOGGER-FORM to try to determine the enclosing lexical scope name. For example if logging macro is being expanded while compiling local function BAR inside of a definition of function FOO, the implementation of this method should strive to return '(FOO BAR) if possible. For CLOS method it is recommended that return value be a generic function name, followed by optional qualifier, and then followed by any non-T specializers, with EQL specializers flattened to their values, for example for the :AROUND method FOO with lambda list of ((OBJ1 BAR) (OPTION (EQL :BAZ)) OBJ3) should strive to return '(FOO AROUND BAR BAZ)

HANDLE-APPENDER-ERROR (APPENDER CONDITION)

Called when a condition is raised doing writing to the appender by APPENDER-DO-APPEND call. Before this method is called, the ERROR slot of the appender is set to CONDITION, thus preventing this appender from being used recursively. Thus its safe to use log statements from inside methods implementing this function Default method will log the condition. If this method resets the ERROR slot of the appender back to NIL, it is assumed that method had fixed whatever was wrong the appender, and the APPENDER-DO-APPEND will be attempted again

LAYOUT-TO-STREAM (LAYOUT STREAM LOGGER LEVEL LOG-FUNC)

Prints the log message to the specified stream. log message can is specified indirectly by LOG-FUNC argument, which is a callable object that accepts a stream and writes log message to it

LOG-LEVEL-FROM-OBJECT (OBJ PACKAGE)

Should return numeric log level from the user representation, can be specialized per-package to have custom log level names. Default implementation converts object to string and parses "fatal" "debug" and so on. Called by MAKE-LOG-LEVEL function

MAYBE-ROLL-FILE (APPENDER)

Should rollover the log file file if needed

NAMING-OPTION (PACKAGE OPTION)

Return the automatic logger naming option for the specified package. Valid options are keywords: :CATEGORY-SEPARATOR : String that separates category names, default method returns ":" :CATEGORY-CASE : Determining how logger naming converts symbols to in the category name. Valid values are: - NIL : As printed by PRINC (ie affected by active *READTABLE*) - :UPCASE : Convert to upper case - :DOWNCASE : Convert to lower case - :INVERT : Invert in the same way inverted READTABLE-CASE does it - :PRESERVE : Do not change Note that pattern layout offers similar facility that changes how logger category is printed on the output side :EXPR-VALUE-SEPARATOR : A string that separates expression and value printed by (LOG-SEXP). Default is equal sign :EXPR-VALUE-SUFFIX : A string inserted into the format statement after each expression and value pair printed by (LOG-SEXP). Default is " ~:_" (a space followed by conditional newline)

PACKAGE-WRAPPER (PACKAGE CATEGORIES EXPLICIT-P)

Allows packages to optionally massage logger names in their namespace. CATEGORIES will be a list of of category names from parent to child, and EXPLICIT-P will be non-NIL if that list was specified as an explicit list constant in a logging macro. Default method will prefix the passed category list with the current package shortest nickname. Example: ;; Some package wishes to always wrap their logger names in weird prefix and suffix (defmethod package-wrapper ((pkg (eql *package*)) categories explicit-p) (if explicit-p categories (append '(foo bar) categories '(baz)))) Will result in the macro (MAKE-LOGGER :NAME) returning logger named FOO:BAR:NAME:BAZ

PARSE-PROPERTY-STREAM (PARSER STREAM)

Read stream and for each line that is not a comment, call PARSE-LINE function.

RESOLVE-LOGGER-FORM (PACKAGE ENV ARGS)

Is called by all logging macros to figure out the logger to log into. PACKAGE and ENV are the current value of *PACKAGE* and the macro environment of the logging macro, and ARGS are its arguments. Returns two values, first being either a logger, or a form that when evaluated will return a logger, and second value being list of arguments to be passed to the format statement that will log the message. When second value returned is NIL, then logging macro will not log any message but will rather expand into a non-NIL value if logging is enabled on that logger.

WATCH-TOKEN-CHECK (TOKEN)

Will be called on each member of WATCH-TOKENS list when hierarchy watcher thread is started. If a unhandled condition is signaled from this function the watcher thread will remove corresponding token from the list

Private

FORMAT-TIME (STREAM PATTERN UNIVERSAL-TIME UTC-P)

Prints UNIVERSAL-TIME to the STREAM according to strftime like PATTERN.

PARSE-EXTRA-ARGS (FMT-INFO PATTERN-CHAR PATTERN-STRING START)

Should parse extra arguments after the end of the conversion character in the PATTERN-STRING and return next parse position. The START is the index of the first character in the conversion pattern after the PATTERN-CHAR, ie in the string %-5p{foobar} it will be at the opening curly brace. Should return two values, new parse position and either FMT-INFO or its subclass.

PARSE-PROPERTY-KEYWORD (PARSER KEYWORD MORE-TOKENS VALUE)

Called to handle properties that start with a common prefix. KEYWORD will be the 1st token of the property name, interned as a keyword. MORE-TOKENS are the rest of the name tokens as strings For example for a the properties stream line: "log4cl:foo:bar=baz" this function will be called with the arguments (:LOG4CL '("FOO" "BAR") "BAZ"value)

PARSE-PROPERTY-LINE (PARSER NAME VALUE)

Called for each NAME=VALUE line in the properties stream. Both NAME and VALUE are strings

PARSE-PROPERTY-TOKENS (PARSER TOKENS VALUE)

Called by default PARSE-PROPERTY-LINE method. TOKENS will be the NAME part of the NAME=VALUE line, split according to NAME-TOKEN-SEPARATOR and their case adjusted by NAME-TOKEN-READ-CASE

PROPERTY-ALIST (INSTANCE)

Should return list of valid object properties, each element of the list being (INITARG SLOT TYPE) with INITARG being the keyword, SLOT is the slot name for the property and TYPE one of: Type | Description ------------------------|------------------------------------------------------ NUMBER or :NUMBER | Integer property, converted by (parse-integer) ------------------------|------------------------------------------------------ BOOLEAN or :BOOLEAN | Boolean, accepts "true" "t" "on" "false" | "off" "nil" and empty string ------------------------|------------------------------------------------------ STRING or :STRING | Value as-is after the equal sign in NAME = <value> | Whitespace is not stripped ------------------------|------------------------------------------------------ :STRING-SKIP-WHITESPACE | Value with the leading whitespace removed Overriding this method to add extra properties is the only thing needed to allow extra properties in custom appenders/layouts to be configurable from by property file configurator. See also PROPERTY-INITARG-FROM-STRING

PROPERTY-INITARG-FROM-STRING (INSTANCE PROPERTY VALUE)

Called on appenders and layouts to possibly convert property value from a string into whatever its supposed to be. Default method will handle numeric, boolean and string properties, by calling PROPERTY-ALIST function

RESOLVE-DEFAULT-LOGGER-FORM (PACKAGE ENV ARGS)

Is called by RESOLVE-LOGGER-FORM when logging macro arguments do not specify the logger to log into. See RESOLVE-LOGGER-FORM for return values

Undocumented

CONDITION-OF (CONDITION)

SETFCONDITION-OF (NEW-VALUE CONDITION)

LINE-NUM-OF (CONDITION)

SETFLINE-NUM-OF (NEW-VALUE CONDITION)

LINE-OF (CONDITION)

SETFLINE-OF (NEW-VALUE CONDITION)

SLOT-ACCESSOR

Public

APPENDER-STREAM (APPENDER)

The Should return the stream to which appender will write log messages

SETFAPPENDER-STREAM (NEW-VALUE OBJECT)

Set the Should return the stream to which appender will write log messages

Undocumented

APPENDER-ERROR (OBJECT)

SETFAPPENDER-ERROR (NEW-VALUE OBJECT)

APPENDER-LOGGER-COUNT (OBJECT)

SETFAPPENDER-LOGGER-COUNT (NEW-VALUE OBJECT)

CONVERSION-PATTERN (OBJECT)

SETFCONVERSION-PATTERN (NEW-VALUE OBJECT)

Private

Undocumented

ELEMENTS-OF (OBJECT)

SETFELEMENTS-OF (NEW-VALUE OBJECT)

FILESPEC-OF (OBJECT)

SETFFILESPEC-OF (NEW-VALUE OBJECT)

LEVEL-OF (OBJECT)

LOGGER-OF (OBJECT)

NAME-OF (OBJECT)

SETFNAME-OF (NEW-VALUE OBJECT)

VARIABLE

Public

*CONFIGURATIONS-FILE*

The file where configurations will be saved. Is merged with result of USER-HOMEDIR-PATHNAME

*HIERARCHY*

Active hierarchy index. All logging functions use logger state indexed by this variable. Can be assigned directly or

*LOG-INDENT*

Indent level can be used to indent logging info, is printed by %I pattern format

*MAX-CONFIGURATIONS*

Maximum number of configurations in *CONFIGURATIONS* list

*NDC-CONTEXT*

Value that is printed by %x pattern format

*ROOT-LOGGER*

The one and only root logger

*SAVE-CONFIGURATIONS-TO-FILE*

When non-NIL SAVE will also write configurations to a *CONFIGURATIONS-FILE*

Undocumented

+SELF-LOGGER+

Private

%PARSE-LINE

Current line being parsed

%PARSE-LINE-NUM

Current line number in the input stream

*CONFIGURATIONS*

List of all LOGGER-CONFIGURATION objects

*HIERARCHIES*

Array of all hierarchies in the system

*HIERARCHY-LOCK*

Global lock for changing logging configuration

*HIERARCHY-MAX*

Number of hierarchies registered with the log4cl library. Each hierarchy has independent configuration with regards to log levels and appenders

*HIERARCHY-WATCHER-HEARTBEAT*

How long hierarchy watcher thread sleeps between calling WATCHER-HOOK of each hierarchy

*INSIDE-USER-LOG-FUNCTION*

True when we are inside of user log function, used to distinguish errors that are signaled the log statement itself, vs errors in layout or appender.

*LOG-EVENT-TIME*

Value of (GET-UNIVERSAL-TIME) for the current log event

*NAME-TO-HIERARCHY*

EQL hash table mapping hierarchy identifier to hierarchy index

*WATCHER-EVENT-TIME*

Universal time of the current watcher heartbeat

*WATCHER-THREAD*

The hierarchy watcher thread

Undocumented

*DEFAULT-INIT-DONE-P*

*FORMATTERS*

*SELF-LOG-CONFIG*

*WATCHER-THREAD-BINDINGS*

+DEFAULT-LOCAL-DATE-FORMAT+

+LOG-LEVEL-FROM-LETTER+

+LOG-LEVEL-FROM-STRING+

+LOG-LEVEL-MACRO-SYMBOLS+

+LOG-LEVEL-SYMBOLS+

+LOG-LEVEL-TO-KEYWORD+

+LOG-LEVEL-TO-LC-STRING+

+LOG-LEVEL-TO-STRING+

+MAKE-LOGGER-SYMBOLS+

+SBCL-WRAPPER-IGNORE+

+SBCL-WRAPPER-NAMES+

CLASS

Public

APPENDER

Appender is log message sink, and is responsible for physically delivering the log message, somewhere. The formatting of message is done by layout. Appenders can be called from multiple threads and are responsible for serializing access to any resources. Appender will not be appended into if its ERROR slot is non-nil. ERROR slot will be automatically set to the condition object, if a condition was raised while writing to the appender

CONFIGURATION

Used to remember log levels for a set of loggers

CONFIGURATION-ELEMENT

Holds logger and its log level

CONSOLE-APPENDER

A stream appender that writes messages to *debug-io* stream. The *debug-io* is late-binding, that is its the value of that variable in the thread and at the moment of log message being written. If instead you want an appender that would write log messages to the *debug-io* stream active when appender was created, use FIXED-STREAM-APPENDER class

COUNTING-APPENDER

Count the number of times APPENDER-DO-APPEND was called

DAILY-FILE-APPENDER

An appender that writes to the file named by expanding a pattern. The expansion is done by the same converter as the %d conversion pattern of the PATTERN-LAYOUT, which is a subset of patterns supported by strftime POSIX function. Properties: NAME-FORMAT : Expanded with date formatter to get the name of the current log file BACKUP-NAME-FORMAT : Expanded with date formatter to get the name of the backup log file UTC-P : Should be non-NIL if name and backup patterns expand the UTC time instead of local. Defaults to NIL. MAYBE-ROLL-FILE method works as follows. It expands both name and backup format (if present). If either of them differs from their previous values, current log file will be closed, and a new current log file will be opened. The old log file will be renamed to %NEXT-BACKUP-NAME, which is a value of the backup format expansion remembered when original log file was opened. The new value of the backup format expansion is remembered in the %NEXT-BACKUP-NAME slot. In below examples it is assumed that current log file was created an 2012-02-21, and the event being logged is the first one on the next day. 1) Example: NAME-FORMAT is "test.log" and backup is unset, will always log to the file named test.log 2) Example: NAME-FORMAT is "test.%Y%m%d.log" and BACKUP-NAME-FORMAT is unset. Will log into the file test.20120221.log file, on the rollover it will be closed and test.20120222.file will be opened. 3) Example: NAME-FORMAT is "test.log" and BACKUP-NAME-FORMAT is "test.%Y%m%d.log". Will log into the file test.log. On rollover test.log will be renamed to test.20120221.log, and new test.log will be created. 4) Example: NAME-FORMAT is "test.%Y%m%d" and BACKUP-NAME-FORMAT is "test.log.bak". Will log into the file test.20120210.log and when the day changes, will rename it to test.log.bak (erasing old one if it exists)

FILE-APPENDER

Appender that writes to a file with a fixed file name

FILE-APPENDER-BASE

Appender that writes to a file and closes it when its no longer attached to loggers

FIXED-STREAM-APPENDER

Appender that writes message to the stream in STREAM slot

LAYOUT

Abstract layout class

PATTERN-LAYOUT

Pattern layout uses a configurable conversion pattern to format log messages. For example, the following patterns produce these log messages: "%-5p [%c] - %m%n" produces the message INFO [CATEGORY:SUBCATEGORY:NAME] - message text and "%-5p [%c{2}{:invert}{.}] - %m%n" produces the message: INFO [subcategory.name] - message text Syntax of conversion pattern is: %[-][<MIN>][.<MAX>]<PATTERN-CHAR>[{<EXTRA-ARG>}...] If a string resulting from the pattern expansion is longer then MAX its truncated by omitting characters from the start. Then if its shorter then MIN its padded with spaces to the right or left (when preceded by a minus) Performance considerations: All formatting is done without consing, except for the case of %m (user message) format, when it has MIN or MAX field width flags. That is because user message is passed around as a lambda that writes to the stream, and in order for its length to be known, (with-output-to-string) is used. Following pattern characters are recognized: -------------------------------------------------------------------- %p Log level string, for example DEBUG, INFO, TRACE. %P Log level string in lower case %c Full category name of the logger for example CL-USER:FOO:BAR. There can be up to three extra flags in curly braces. Extra flag can be a set of empty curly braces, in this case the effect is same as default value. First extra flag is PRECISION. When a single integer its a number of categories to display, parent categories will be omitted if logger is more then N levels deep. For example if logger category name is CL-USER:ONE:TWO:THREE then conversion pattern %c{2 2} will produce TWO:THREE When PRECISION is specified as {<FROM>,<COUNT>}, then it means categories starting at FROM (zero-based) and output <COUNT> categories. Negative or zero means until end of the categories. Example: Category printed for a logger named CL-USER:ONE:TWO:THREE Precision | Result ----------|---------------- {1} | THREE {2} | TWO:THREE {0,1} | CL-USER {5,1} | {1,1} | ONE {1,2} | ONE:TWO {1,0} | ONE:TWO:THREE {1,100} | ONE:TWO:THREE Second extra argument is SEPARATOR and will be a separator used between category names. If not present then the loggers native value will be used, which can be overwritten per package by NAMING-OPTION method Third extra argument if present, can be one of :UPCASE, :DOWNCASE or :INVERT and will result in printing of the category name in the corresponding manner, similar to using non-standard readtable-case For example when logger category is CL-USER.FOO.BAR outputting it with conversion pattern of %c{}{--}{:invert} will result print it as cl-user--foo--bar -------------------------------------------------------------------- %d The date/time of the log message in UTC, extra argument can be a date pattern. Default date pattern is %d{%Y-%m-%d %H:%M:%S} To facilitate testing there can be optional second extra argument, which could be decimal value that will be used as universal time instead calling (GET-UNIVERSAL-TIME) Lisp does not have portable facility to get week and month names, so date format is printed by PATTERN-LAYOUT-FORMAT-DATE generic function, default method of which uses hard-coded English week/month/weekday names. Valid date format values are same as C strftime function, with GNU extensions. %A -- Full weekday name %A -- Abbreviated weekday name %B -- Full month name %b -- Abbreviated month name %c -- Standard date and time string %d -- Day of month as a decimal(01-31) %H -- Hour(00-23) %I -- Hour(01-12) %m -- Month as decimal(01-12) %M -- Minute as decimal(00-59) %p -- AM or PM %P -- am or pm %S -- Second as decimal(00-59) %y -- Year in decimal without century(0-99) %Y -- Year including century as decimal %z -- Time zone offset from UTC in -hhmm or +hhmm format %% -- The percent sign -------------------------------------------------------------------- %D date-time in local time, extra arguments can contain a strftime pattern %h hostname of the system (implementation dependent, obtained once when pattern is parsed, and cached %t Current thread name %x Value of *ndc-context* variable from (with-ndc-context (context)) macro %i Process id of the lisp process, implementation dependent. %I Two spaces repeated *log-indent* times. Different padding string can be specified in an extra argument. %n OS-dependent newline sequence. %& Optional newline, issues FRESH-LINE on the stream %m Actual user log message.

PROPERTY-CONFIGURATOR

Class that holds configurator state while parsing the properties file

PROPERTY-PARSER

Class for reading Java style property files.

ROLLING-FILE-APPENDER-BASE

File appender that periodically checks if it needs to rollover the log file. Properties: ROLLOVER-CHECK-PERIOD : An integer, when current time advances past the boundary evenly divisible by this number a call to MAYBE-ROLL-FILE will be made to check if log file needs to be rolled over

SERIALIZED-APPENDER

Appender that serializes itself using a lock

SIMPLE-LAYOUT

Simple layout outputs log level and user message separated by dash. For example: INFO - user log message

STREAM-APPENDER

Appender that writes message to stream. Stream is obtained on each output by calling APPENDER-STREAM function. Properties: IMMEDIATE-FLUSH : When non-NIL will call FINISH-OUTPUT after every log message FLUSH-INTERVAL : When set, will only flush if previous flush was earlier than FLUSH-INTERVAL seconds ago. In addition a background thread will be used to flush all appenders with FLUSH-INTERVAL set. See ADD-WATCH-TOKEN

Private

FIXED-STREAM-APPENDER-BASE

Appender that writes message to the stream in STREAM slot

FORMAT-INFO

Represents data for a single conversion pattern

PATTERN-CATEGORY-FORMAT-INFO

Extra formatting flags for %c (log category) pattern

PATTERN-DATE-FORMAT-INFO

Extra formatting flags for %d and %D patterns

PATTERN-HOSTNAME-FORMAT-INFO

Extra formatting flags for %h pattern

PATTERN-LOG-INDENT-FMT-INFO

Extra formatting flags for %I (log indent) pattern

PATTERN-NEWLINE-FORMAT-INFO

Extra formatting flags for %n pattern. Currently this is unused, but in the future it may be implemented so that newline will be conditional, if underlaying stream supports STREAM-LINE-COLUMN, so that instead of two-line pattern layout, we can use conditional newline only user message does not fit on current line

PROCESS-ID-FMT-INFO

Caches process-id

PROPERTY-LOCATION

Remembered line and line number in the input stream where object appeared, so we can signal errors with that info

Undocumented

DELAYED-APPENDER

DELAYED-INSTANCE

DELAYED-LAYOUT

HIERARCHY

LOGGER

LOGGER-RECORD

LOGGER-STATE (INSTANCE)

PROPERTY-CONFIGURATOR-FILE-WATCH

CONDITION

Public

LOG4CL-ERROR (MESSAGE &REST ARGS)

Base class for all LOG4CL errors

Undocumented

PATTERN-LAYOUT-ERROR (MESSAGE &REST ARGS)

PROPERTY-PARSER-ERROR

CONSTANT

Public

Undocumented

+LOG-LEVEL-DEBUG+

+LOG-LEVEL-ERROR+

+LOG-LEVEL-FATAL+

+LOG-LEVEL-INFO+

+LOG-LEVEL-OFF+

+LOG-LEVEL-TRACE+

+LOG-LEVEL-UNSET+

+LOG-LEVEL-USER1+

+LOG-LEVEL-USER2+

+LOG-LEVEL-USER3+

+LOG-LEVEL-USER4+

+LOG-LEVEL-USER5+

+LOG-LEVEL-USER6+

+LOG-LEVEL-USER7+

+LOG-LEVEL-USER8+

+LOG-LEVEL-USER9+

+LOG-LEVEL-WARN+

+MAX-LOG-LEVEL+

+MIN-LOG-LEVEL+