The a-cl-logger Reference Manual

Table of Contents

The a-cl-logger Reference Manual

This is the a-cl-logger Reference Manual, version 1.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 13:59:59 2021 GMT+0.

1 Introduction

a-cl-logger

A common lisp logging library providing context sensitive logging of more than just strings to more than just local files / output streams

This started as a significant refactor arnesi logging and the many chunks of surrounding code.

Goals

• node-logstash integration
• Swank presentations integration (objects are printed to the REPL as an inspectable presentation (C-c M-p)
• Support logging of more than just strings, eg: json
• Context sensitive logging (easily use the dynamic context to add to the data being logged)
• Gracefully handle slime/swank reconnects
• Errors in logging shouldnt cause application errors, but should still be debuggable

Quickstart

(eval-when (:compile-toplevel :load-toplevel :execute)
  (ql:quickload :a-cl-logger))

;; log to stderr
(a-cl-logger:define-logger testlog ())
(defun do-something(x)
  (testlog.debug "starting to do something to ~a" x)
  (testlog.info "did something to ~a" x))

;; log to stderr and a file (see note about buffering in "Gotchas" below)
(a-cl-logger:define-logger filelog ()
  :appenders (make-instance 'a-cl-logger:file-log-appender
                :log-file "test.log"))

;; log to stderr and a file (see note about buffering in "Gotchas" below)
(a-cl-logger:define-logger filelog ()
  :appenders (make-instance 'a-cl-logger:json-file-log-appender
                :log-file "test.json.log"))

Description and Glossary

A Logger is a mechanism for generating a text message and have that messaged saved somewhere for future review. Logging can be used as a debugging mechanism or for just reporting on the status of a system.

Messages are sent to a particular Logger. Each logger sends the messages it receives to its appenders. An appenders's job is to take a message and write it somewhere. Loggers are organized in a hierarchy and messages sent to a logger will also be sent to that loggers's parents (if valid). Only if the message is enabled for the current logger will it be propogated to the parents.

Each logger has a level which is used to determine whether a particular message should be processed or not. Loggers inherit their log level from their parents. If a logger has multiple direct parents its log level is the min of the levels of its parents.

Glossary

• Logger - an object that contains a list of places to send messages (appenders) and a level. Loggers are hierarchical and will send messages to all parent appenders and defer to parent levels.
• Level - dribble, debug, info, warn, error, fatal, a name and number indicating the sevarity of log messages. Levels are used to filter which messages are sent to which loggers and appenders
• Appenders - an object that transmits a message to a location (file, repl, node-logstash) in a given format (by using the formatter found in the formatter slot)
• Formatter - format-message is specialized on a formatter, which is stored on each appender.
• Message - The data trying to be logged, a localtime:timestamp, and a level indicating this message's importance

Log message format:

Messages contain:

• format-string and arguments
• plist of keys/values
• logger
• level

The default printing of a message is
"{ts} {logger}{level} formatted-msg {key,val ...}"

eg:

(testlog.debug "Format-string example:#~d" 1)
(testlog.debug :a-plist-key :a-plist-value :some-key "some value")

Logging

Logging can be accomplished by a couple of means:

Helper macros

Helper

(testlog.debug "Format-string example:#~d" 1)
(testlog.info :a-plist-key :a-plist-value :some-key "some value")

These helper macros will handle errors in log argument evaluation (you can still debug if debug-hook is bound). They will also capture the literal arguments provided to the macro to ease debugging.

do-log

The do-log function can also be used to create log messages

(do-log *testlog* +info+ "Format-string example:#~d" 1)
(do-log 'testlog +debug+ :a-plist-key :a-plist-value :some-key "some value")

There is also a helper get-log-fn which will create a function of (&rest args) that logs to a given logger and level). This is useful for libraries that supply functional logging hooks

(get-log-fn *testlog* :level +info+) => (lambda (&rest args) ...)

Root Logger

There is a root logger which all other loggers have as a parent by default. This is a conveneint place to put appenders that should always apply. You can remove the root by removing it from the parents slot of a logger.

Appenders and Formatters

• An appender controls writing a log message to a specific destination
• Each appender has a formatter that controls the way the log message is printed.

Filtering

This will mute timing messages to any file appenders (eg: send timing only to the repl / logstash)

(define-logger app-log ())
(define-logger timing-log (app-log))
(defun mute-timing-file-appends (c)
    (let* ((m (a-log:message c))
           (l (a-log:logger m))
           (a (a-log:appender c)))
      (when (and (typep a 'a-log:file-log-appender)
                 (eql l *timing-log*))
        (abort c))))
(a-log:add-signal-handler
 *timing-log* 'a-log:appending-message 'mute-timing-file-appends)

Signals and Restarts - Context Sensitive Logging

Messages generate signals on being created and on being appended.

• generating-message - signaled when a message is created
• logging-message - signaled when a specific logger begins handling a message
• appending-message - signaled when a specific appender begins handling a message

Muffling log messages / aborting

Each signal can be aborted which will prevent the operation from occuring.

Aborting while appending will prevent the message from going to a single destination. Aborting while logging will prevent the message from going to ANY appenders of the log or its parents. Aborting while generating a message just muffles that log message entirely

Changing / Adding to the messages being logged

At each of these points you can invoke the restart change-message to alter the message going out. Generally the message you change to will be a copy of the original (see copy-message).

Each of these signals are wrapped in a change-message restart that can be used to modify the message for the remainder of the operation. (IE: a specific appender will operate on a new copy of the message with different, supplemental data).

Default Handlers

Signals can be handled by handler-binds on the dynamic context or by adding default-handlers to the default-signal-bindings slot on the logger. This can be accomplished using add-signal-handler passing the logger, a condition type and a fn.

Here are some examples. The first prevents the timing log from being inserted into the log file. The second prevents a particular log message from being inserted into the logs.

(defun mute-timing-file-appends (c)
    (let* ((m (a-log:message c))
           (l (a-log:logger m))
           (a (a-log:appender c)))
      (when (and (typep a 'a-log:file-log-appender)
                 (eql l *timing-log*))
        (abort c))))

(a-log:add-signal-handler
 *timing-log* 'a-log:appending-message 'mute-timing-file-appends)

(defun ignore-foreach-warnings (c)
  (let ((fs (a-log:format-control (a-log:message c))))
    (when (cl-ppcre:scan #?r"(?i)invalid argument supplied for foreach" fs)
      (abort c))))

(a-log:add-signal-handler
 *wp-log* 'a-log:generating-message 'ignore-foreach-warnings)

Helper Functions

• get-log-fn: given a logger and an optional level create a function of &rest args that logs to the given logger. Useful for interacting with libraries providing functional logging hooks

• with-appender: create a dynamic scope inside which messages to logger will additionally be appended to this appender

• when-log-message-generated/logged/appended: These are macros that establish a dynamic context inside of which log messages will be intercepted at key points in their life cycle. The first body is the message handler and the second is the scope.

• setup-logger: a function that will ensure log-level and standard debug-io-appender / file-appenders are in place. Useful when debug IO become rebound etc (slime session resets). Probably not as useful now that there is a root logger and we dont have to constantly attach the same appenders everywhere

Gotchas

• There are some SBCL specifics. Cross platform help would be nice
• "--quiet" command line arg
• logstash hostname
• file log appender output may be buffered by the lisp implementation's stream operations. If you have a slow process, messages may take some time to be written to the log file. Use (make-instance 'a-cl-logger:file-log-appender :log-file "test.log" :buffer-p nil) to aggressively call force-output and ensure the log file is accurate.

Differences From Arnesi/src/log.lisp

• There has been some significant renaming
• deflogger -> define-logger
• log-category -> logger
• appenders are separate from formatters
• File streams ensure the file is open to write to
• Failing to write to one appender / logger doesnt prevent the rest from working

Examples:

!! These examples are all in SBCL !!

Capturing log output to strings

(a-log:with-logged-output (a-log:*root-logger*)
  (run-some-data *context*)
  )
=>
"Log message 1
Log message 2
Log message 3"

Filtering message content

This will abort / mute log messages that match a certain warning

(defun ignore-foreach-warnings (c)
  (let ((fs (a-log:format-control (a-log:message c))))
    (when (cl-ppcre:scan #?r"(?i)invalid argument supplied for foreach" fs)
      (abort c))))

(define-logger my-module-log (my-log))

Filter log messages globally for a specific logger:

(a-log:add-signal-handler
 *my-module-log* 'a-log:generating-message 'ignore-foreach-warnings)

Filter log messages locally for a logger:

(defmacro with-muted-foreach-warnings (() &body body)
  (handler-bind ((a-log:generating-message #'ignore-foreach-warnings))
    (progn ,@body)))

Basic Context Sensitive Logging

(a-log:when-log-message-generated ((a-log:push-into-message :a 1 :b 2)) (log.debug "This message will have a=1 and b=2 in its data"))

Logging the lexical environment

(a-log:define-logger my-log ()
  :appenders (make-instance 'a-log:stream-log-appender :stream *standard-output*))

(defun compile-env-data-list (env)
  (let* ((blocks (mapcar #'first (reverse (sb-c::lexenv-blocks env))))
         (lex-vars (reverse (sb-c::lexenv-vars env)))
         (vars (iter (for (name . v) in lex-vars)
                 (for ignore? = (ignore-errors (sb-c:lambda-var-ignorep v)))
                 (unless ignore?
                   (collect `(quote ,name))
                   (collect name)))))
    (values
     (first blocks)
     `(list :blocks (princ-to-string '(,@blocks))
       (list ,@vars)))))

(defmacro with-env-stats-recorder (()
                                   &body body &environment env)
  "puts data and tag from the lexical env into the message"
  (multiple-value-bind (name data-forms)
      (compile-env-data-list env)
    `(a-log:when-log-message-generated
      ((a-log:push-into-message :lexical-data (,@data-forms) :name ',name))
      ,@body)))

(defun test-cs-logging (&key (a 1) (b 2))
  (my-log.info "OUT of Env Recorder ")
  (with-env-stats-recorder ()
    (my-log.info "In test-cs-logger recorder ")
    (let ((c (+ 1 b)))
      (flet ((again (d)
               (incf d)
               (with-env-stats-recorder ()
                 (my-log.info "In again ~a " d))))
        (again a)
        (again b)))))

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 a-cl-logger

Author

Russ Tyndall <russ@acceleration.net>

License

BSD

Description

A logger that sends to multiple destinations in multiple formats. Based on arnesi logger

Version

1.0.1

Dependencies

• iterate
• symbol-munger
• alexandria
• cl-interpol
• cl-json
• local-time
• cl-json
• closer-mop
• osicat

Source

a-cl-logger.asd (file)

Components

• packages.lisp (file)
• utils.lisp (file)
• log.lisp (file)
• appenders.lisp (file)
• helpers.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 a-cl-logger.asd

Location

a-cl-logger.asd

Systems

a-cl-logger (system)

Packages

a-cl-logger.system

3.1.2 a-cl-logger/packages.lisp

Parent

a-cl-logger (system)

Location

packages.lisp

Packages

a-cl-logger

3.1.3 a-cl-logger/utils.lisp

Dependency

packages.lisp (file)

Parent

a-cl-logger (system)

Location

utils.lisp

Exported Definitions

• *appender* (special variable)
• *log-level-names* (special variable)
• *message* (special variable)
• *root-logger* (special variable)
• +debug+ (special variable)
• +dribble+ (special variable)
• +error+ (special variable)
• +fatal+ (special variable)
• +info+ (special variable)
• +warn+ (special variable)
• get-logger! (macro)
• require-logger! (macro)

Internal Definitions

• *logger* (special variable)
• *logger-vars* (special variable)
• *max-logger-name-length* (special variable)
• +muted+ (special variable)
• as-json-array (function)
• as-json-object-member (function)
• class-name-of (function)
• define-mutator-macros (macro)
• ensure-level-value! (macro)
• ensure-list! (macro)
• ensure-message (function)
• ensure-message! (macro)
• format-time (function)
• maybe-with-presentations (macro)
• me-or-ancestor (function)
• only-one? (function)
• push-m-plist (macro)
• replace-symbols-in-forms (function)
• with-auto-unique-names (macro)
• with-debugging-or-error-printing (macro)
• with-logger-level (macro)
• with-logging-io (macro)
• with-macro-splicing (macro)
• without-earmuffs (function)

3.1.4 a-cl-logger/log.lisp

Dependency

utils.lisp (file)

Parent

a-cl-logger (system)

Location

log.lisp

Exported Definitions

• add-signal-handler (function)
• appender (method)
• (setf appender) (method)
• appenders (method)
• (setf appenders) (method)
• appending-message (condition)
• children (method)
• (setf children) (method)
• data-plist (method)
• (setf data-plist) (method)
• default-signal-bindings (method)
• (setf default-signal-bindings) (method)
• define-logger (macro)
• do-log (function)
• do-logging (generic function)
• do-logging (method)
• do-logging (method)
• do-logging (method)
• format-args (method)
• (setf format-args) (method)
• format-control (method)
• (setf format-control) (method)
• generating-message (condition)
• get-logger (function)
• (setf get-logger) (function)
• level (method)
• (setf level) (method)
• level (method)
• (setf level) (method)
• log-level (generic function)
• log-level (method)
• log-level (method)
• (setf log-level) (generic function)
• (setf log-level) (method)
• log-level-name-of (function)
• logger (method)
• (setf logger) (method)
• logger (method)
• (setf logger) (method)
• logger (method)
• (setf logger) (method)
• logger (class)
• logging-message (condition)
• make-message (function)
• message (method)
• (setf message) (method)
• message (method)
• (setf message) (method)
• message (method)
• (setf message) (method)
• message (class)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• parents (method)
• (setf parents) (method)
• require-logger (function)

Internal Definitions

• %logger-name-for-output (function)
• %make-log-helper (function)
• %safe-log-helper-arg (function)
• arg-literals (method)
• (setf arg-literals) (method)
• compile-time-enabled-p (generic function)
• compile-time-enabled-p (method)
• compile-time-level (method)
• (setf compile-time-level) (method)
• copy-messsage (function)
• define-log-helpers (macro)
• do-append (generic function)
• do-append (method)
• do-append (method)
• enabled-p (function)
• ensure-level-value (function)
• ensure-type (function)
• form (method)
• (setf form) (method)
• get-logger-var-name (function)
• inner-error (method)
• (setf inner-error) (method)
• log-argument-evaluation-error (condition)
• log.compile-time-level (generic function)
• log.compile-time-level (method)
• (setf log.compile-time-level) (generic function)
• (setf log.compile-time-level) (method)
• logger-level-from-helper (function)
• logger-name-from-helper (function)
• logger-signal-handlers (function)
• maybe-signal-appending-message (function)
• maybe-signal-generating-message (function)
• maybe-signal-logging-message (function)
• maybe-signal-message (function)
• missing-logger (function)
• missing-logger (condition)
• rem-logger (function)
• signal-messages (method)
• (setf signal-messages) (method)
• split-log-helper (function)
• timestamp (method)
• (setf timestamp) (method)
• with-change-message (macro)

3.1.5 a-cl-logger/appenders.lisp

Dependency

log.lisp (file)

Parent

a-cl-logger (system)

Location

appenders.lisp

Exported Definitions

• alist-as-json (function)
• append-message (generic function)
• append-message (method)
• append-message (method)
• appender (class)
• debug-io-log-appender (class)
• ensure-debug-io-appender (function)
• ensure-file-appender (function)
• ensure-stderr-appender (function)
• file-log-appender (class)
• find-appender (function)
• format-message (generic function)
• format-message (method)
• format-message (method)
• formatter (method)
• (setf formatter) (method)
• formatter (class)
• json (method)
• (setf json) (method)
• json (class)
• json-formatter (class)
• level (method)
• (setf level) (method)
• (setf log-level) (method)
• log-stream (method)
• (setf log-stream) (method)
• plist-as-json (function)
• raw-formatter (class)
• remove-appender (function)
• stderr-log-appender (class)
• stream-log-appender (class)
• string-stream-appender (class)

Internal Definitions

• %filter-plist (function)
• %open-log-file (function)
• buffer-p (method)
• (setf buffer-p) (method)
• ensure-stream-appender (function)
• format-value (generic function)
• format-value (method)
• format-value (method)
• json-file-log-appender (class)
• log-file (method)
• (setf log-file) (method)
• (setf log-file) (method)
• logger-inspector-lookup-hook (function)
• with-stream-restarts (macro)

3.1.6 a-cl-logger/helpers.lisp

Dependency

appenders.lisp (file)

Parent

a-cl-logger (system)

Location

helpers.lisp

Exported Definitions

• close-all-files (function)
• get-log-fn (function)
• log-around (macro)
• log-errors (macro)
• log-serious-conditions (macro)
• make-log-path (function)
• push-into-message (function)
• setup-logger (function)
• when-log-message-appended (macro)
• when-log-message-generated (macro)
• with-appender (macro)
• with-logged-output (macro)
• with-logged-output-to-place (macro)

Internal Definitions

• close-message-block (function)
• open-message-block (function)
• root-logger.debug (macro)
• root-logger.dribble (macro)
• root-logger.error (macro)
• root-logger.fatal (macro)
• root-logger.info (macro)
• root-logger.muted (macro)
• root-logger.warn (macro)
• when-log-message-* (macro)
• when-log-message-logged (macro)

4 Packages

Packages are listed by definition order.

4.1 a-cl-logger.system

Source

a-cl-logger.asd

Use List

• asdf/interface
• common-lisp

4.2 a-cl-logger

Source

packages.lisp (file)

Nickname

a-log

Use List

• iterate
• common-lisp

Exported Definitions

• *appender* (special variable)
• *log-level-names* (special variable)
• *message* (special variable)
• *root-logger* (special variable)
• +debug+ (special variable)
• +dribble+ (special variable)
• +error+ (special variable)
• +fatal+ (special variable)
• +info+ (special variable)
• +warn+ (special variable)
• add-signal-handler (function)
• alist-as-json (function)
• append-message (generic function)
• append-message (method)
• append-message (method)
• appender (generic function)
• appender (method)
• (setf appender) (method)
• (setf appender) (generic function)
• appender (class)
• appenders (generic function)
• appenders (method)
• (setf appenders) (method)
• (setf appenders) (generic function)
• appending-message (condition)
• children (generic function)
• children (method)
• (setf children) (method)
• (setf children) (generic function)
• close-all-files (function)
• data-plist (generic function)
• data-plist (method)
• (setf data-plist) (method)
• (setf data-plist) (generic function)
• debug-io-log-appender (class)
• default-signal-bindings (generic function)
• default-signal-bindings (method)
• (setf default-signal-bindings) (method)
• (setf default-signal-bindings) (generic function)
• define-logger (macro)
• do-log (function)
• do-logging (generic function)
• do-logging (method)
• do-logging (method)
• do-logging (method)
• ensure-debug-io-appender (function)
• ensure-file-appender (function)
• ensure-stderr-appender (function)
• file-log-appender (class)
• find-appender (function)
• format-args (generic function)
• format-args (method)
• (setf format-args) (method)
• (setf format-args) (generic function)
• format-control (generic function)
• format-control (method)
• (setf format-control) (method)
• (setf format-control) (generic function)
• format-message (generic function)
• format-message (method)
• format-message (method)
• formatter (generic function)
• formatter (method)
• (setf formatter) (method)
• (setf formatter) (generic function)
• formatter (class)
• generating-message (condition)
• get-log-fn (function)
• get-logger (function)
• (setf get-logger) (function)
• get-logger! (macro)
• json (generic function)
• json (method)
• (setf json) (method)
• (setf json) (generic function)
• json (class)
• json-formatter (class)
• level (generic function)
• level (method)
• (setf level) (method)
• level (method)
• (setf level) (method)
• level (method)
• (setf level) (method)
• (setf level) (generic function)
• log-around (macro)
• log-errors (macro)
• log-level (generic function)
• log-level (method)
• log-level (method)
• (setf log-level) (generic function)
• (setf log-level) (method)
• (setf log-level) (method)
• log-level-name-of (function)
• log-serious-conditions (macro)
• log-stream (generic function)
• log-stream (method)
• (setf log-stream) (method)
• (setf log-stream) (generic function)
• logger (generic function)
• logger (method)
• (setf logger) (method)
• logger (method)
• (setf logger) (method)
• logger (method)
• (setf logger) (method)
• (setf logger) (generic function)
• logger (class)
• logging-message (condition)
• make-log-path (function)
• make-message (function)
• message (generic function)
• message (method)
• (setf message) (method)
• message (method)
• (setf message) (method)
• message (method)
• (setf message) (method)
• (setf message) (generic function)
• message (class)
• name (generic function)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• parents (generic function)
• parents (method)
• (setf parents) (method)
• (setf parents) (generic function)
• plist-as-json (function)
• push-into-message (function)
• raw-formatter (class)
• remove-appender (function)
• require-logger (function)
• require-logger! (macro)
• setup-logger (function)
• stderr-log-appender (class)
• stream-log-appender (class)
• string-stream-appender (class)
• when-log-message-appended (macro)
• when-log-message-generated (macro)
• with-appender (macro)
• with-logged-output (macro)
• with-logged-output-to-place (macro)

Internal Definitions

• %filter-plist (function)
• %logger-name-for-output (function)
• %make-log-helper (function)
• %open-log-file (function)
• %safe-log-helper-arg (function)
• *logger* (special variable)
• *logger-vars* (special variable)
• *max-logger-name-length* (special variable)
• +muted+ (special variable)
• arg-literals (generic function)
• arg-literals (method)
• (setf arg-literals) (method)
• (setf arg-literals) (generic function)
• as-json-array (function)
• as-json-object-member (function)
• buffer-p (generic function)
• buffer-p (method)
• (setf buffer-p) (method)
• (setf buffer-p) (generic function)
• class-name-of (function)
• close-message-block (function)
• compile-time-enabled-p (generic function)
• compile-time-enabled-p (method)
• compile-time-level (generic function)
• compile-time-level (method)
• (setf compile-time-level) (method)
• (setf compile-time-level) (generic function)
• copy-messsage (function)
• define-log-helpers (macro)
• define-mutator-macros (macro)
• do-append (generic function)
• do-append (method)
• do-append (method)
• enabled-p (function)
• ensure-level-value (function)
• ensure-level-value! (macro)
• ensure-list! (macro)
• ensure-message (function)
• ensure-message! (macro)
• ensure-stream-appender (function)
• ensure-type (function)
• form (generic function)
• form (method)
• (setf form) (method)
• (setf form) (generic function)
• format-time (function)
• format-value (generic function)
• format-value (method)
• format-value (method)
• get-logger-var-name (function)
• inner-error (generic function)
• inner-error (method)
• (setf inner-error) (method)
• (setf inner-error) (generic function)
• json-file-log-appender (class)
• log-argument-evaluation-error (condition)
• log-file (generic function)
• log-file (method)
• (setf log-file) (method)
• (setf log-file) (generic function)
• (setf log-file) (method)
• log.compile-time-level (generic function)
• log.compile-time-level (method)
• (setf log.compile-time-level) (generic function)
• (setf log.compile-time-level) (method)
• logger-inspector-lookup-hook (function)
• logger-level-from-helper (function)
• logger-name-from-helper (function)
• logger-signal-handlers (function)
• maybe-signal-appending-message (function)
• maybe-signal-generating-message (function)
• maybe-signal-logging-message (function)
• maybe-signal-message (function)
• maybe-with-presentations (macro)
• me-or-ancestor (function)
• missing-logger (function)
• missing-logger (condition)
• only-one? (function)
• open-message-block (function)
• push-m-plist (macro)
• rem-logger (function)
• replace-symbols-in-forms (function)
• root-logger.debug (macro)
• root-logger.dribble (macro)
• root-logger.error (macro)
• root-logger.fatal (macro)
• root-logger.info (macro)
• root-logger.muted (macro)
• root-logger.warn (macro)
• signal-messages (generic function)
• signal-messages (method)
• (setf signal-messages) (method)
• (setf signal-messages) (generic function)
• split-log-helper (function)
• timestamp (generic function)
• timestamp (method)
• (setf timestamp) (method)
• (setf timestamp) (generic function)
• when-log-message-* (macro)
• when-log-message-logged (macro)
• with-auto-unique-names (macro)
• with-change-message (macro)
• with-debugging-or-error-printing (macro)
• with-logger-level (macro)
• with-logging-io (macro)
• with-macro-splicing (macro)
• with-stream-restarts (macro)
• without-earmuffs (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *appender*

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: *log-level-names*

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: *message*

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: *root-logger*

By default all loggers have the *root-logger* as a parent

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: +debug+

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: +dribble+

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: +error+

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: +fatal+

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: +info+

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: +warn+

Package

a-cl-logger

Source

utils.lisp (file)

5.1.2 Macros

Macro: define-logger NAME PARENTS &key COMPILE-TIME-LEVEL LEVEL APPENDERS DOCUMENTATION FORCE?

Package

a-cl-logger

Source

log.lisp (file)

Macro: get-logger! &rest PLACES

Package

a-cl-logger

Source

utils.lisp (file)

Macro: log-around LOGGER-FORM &body BODY

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: log-errors (LOGGER &optional MESSAGE) &body BODY

like ignore-errors but logs instead

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: log-serious-conditions (LOGGER &optional MESSAGE) &body BODY

like ignore-errors but logs instead

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: require-logger! &rest PLACES

Package

a-cl-logger

Source

utils.lisp (file)

Macro: when-log-message-appended (&body HANDLER-BODY) &body BODY

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: when-log-message-generated (&body HANDLER-BODY) &body BODY

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: with-appender (LOGGER APPENDER) &body BODY

Add an appender to logger for the duration of the scope

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: with-logged-output (LOGGER) &body BODY

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: with-logged-output-to-place (LOGGER PLACE) &body BODY

Package

a-cl-logger

Source

helpers.lisp (file)

5.1.3 Functions

Function: add-signal-handler LOGGER CONDITION-NAME FN

Package

a-cl-logger

Source

log.lisp (file)

Function: alist-as-json ALIST

Create a pre-encoded json object from an alist

Package

a-cl-logger

Source

appenders.lisp (file)

Function: close-all-files &key LOGGERS

Package

a-cl-logger

Source

helpers.lisp (file)

Function: do-log LOG LEVEL &rest ARGS

Package

a-cl-logger

Source

log.lisp (file)

Function: ensure-debug-io-appender LOGGER

Package

a-cl-logger

Source

appenders.lisp (file)

Function: ensure-file-appender LOGGER &key BUFFER-P NAME DIRECTORY PATH

Package

a-cl-logger

Source

appenders.lisp (file)

Function: ensure-stderr-appender LOGGER

Package

a-cl-logger

Source

appenders.lisp (file)

Function: find-appender LOGGER &key TYPE PREDICATE RECURSE?

Package

a-cl-logger

Source

appenders.lisp (file)

Function: get-log-fn LOG-ID &key LEVEL

Given a logger identifier name like ’adwolf-log.debug or ’adwolf-log find the logger associated with it and build a (lambda (message &rest args)) that can be funcalled to log to that logger.

Package

a-cl-logger

Source

helpers.lisp (file)

Function: get-logger NAME

Function: (setf get-logger) NEW NAME

Package

a-cl-logger

Source

log.lisp (file)

Function: log-level-name-of LEVEL &key RAW?

Package

a-cl-logger

Source

log.lisp (file)

Function: make-log-path ROOT FILE

Package

a-cl-logger

Source

helpers.lisp (file)

Function: make-message LOGGER LEVEL ARGS &key ARG-LITERALS DATA-PLIST &aux SINGLETON FORMAT-CONTROL?

Package

a-cl-logger

Source

log.lisp (file)

Function: plist-as-json &rest PLIST

Create a pre-encoded json object from a plist

Package

a-cl-logger

Source

appenders.lisp (file)

Function: push-into-message &rest PLIST

Package

a-cl-logger

Source

helpers.lisp (file)

Function: remove-appender LOGGER &key TYPE PREDICATE PATH RECURSE?

Package

a-cl-logger

Source

appenders.lisp (file)

Function: require-logger NAME

Package

a-cl-logger

Source

log.lisp (file)

Function: setup-logger LOGGER &key LEVEL FILE-NAME LOG-ROOT BUFFER-P

Reconfigures a logger such that it matches the setup specified

This is sometimes necessary if your streams get messed up (eg: slime disconnect and reconnect)

Always ensure there is a *error-output* stream logger
and if a file-name is passed in a file-logger going to it

Package

a-cl-logger

Source

helpers.lisp (file)

5.1.4 Generic functions

Generic Function: append-message LOG-APPENDER MESSAGE

The method responsible for actually putting the logged information somewhere

Package

a-cl-logger

Source

appenders.lisp (file)

Methods

Method: append-message (APPENDER file-log-appender) MESSAGE

Method: append-message (S stream-log-appender) MESSAGE

Generic Function: appender CONDITION

Generic Function: (setf appender) NEW-VALUE CONDITION

Package

a-cl-logger

Methods

Method: appender (CONDITION appending-message)

Method: (setf appender) NEW-VALUE (CONDITION appending-message)

Source

log.lisp (file)

Generic Function: appenders OBJECT

Generic Function: (setf appenders) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: appenders (LOGGER logger)

Method: (setf appenders) NEW-VALUE (LOGGER logger)

A list of appender objects this logger sholud send messages to.

Source

log.lisp (file)

Generic Function: children OBJECT

Generic Function: (setf children) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: children (LOGGER logger)

Method: (setf children) NEW-VALUE (LOGGER logger)

The logger which inherit from this logger.

Source

log.lisp (file)

Generic Function: data-plist OBJECT

Generic Function: (setf data-plist) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: data-plist (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf data-plist) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

Generic Function: default-signal-bindings OBJECT

Generic Function: (setf default-signal-bindings) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: default-signal-bindings (LOGGER logger)

automatically generated reader method

Source

log.lisp (file)

Method: (setf default-signal-bindings) NEW-VALUE (LOGGER logger)

automatically generated writer method

Source

log.lisp (file)

Generic Function: do-logging LOGGER MESSAGE

Applys a message to the loggers appenders
Message is either a string or a list. When it’s a list and the first element is a string then it’s processed as args to cl:format.

Package

a-cl-logger

Source

log.lisp (file)

Methods

Method: do-logging LOGGER MESSAGE around

Method: do-logging LOG (MESSAGE null)

Method: do-logging LOG (MESSAGE message)

Generic Function: format-args OBJECT

Generic Function: (setf format-args) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: format-args (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf format-args) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

Generic Function: format-control OBJECT

Generic Function: (setf format-control) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: format-control (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf format-control) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

Generic Function: format-message APPENDER FORMATTER MESSAGE STREAM

Package

a-cl-logger

Source

appenders.lisp (file)

Methods

Method: format-message (APPENDER appender) FORMATTER (MESSAGE message) STREAM

Method: format-message (APPENDER appender) (FORMATTER json-formatter) (MESSAGE message) STREAM &aux SEEN LOG

Generic Function: formatter OBJECT

Generic Function: (setf formatter) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: formatter (APPENDER appender)

automatically generated reader method

Source

appenders.lisp (file)

Method: (setf formatter) NEW-VALUE (APPENDER appender)

automatically generated writer method

Source

appenders.lisp (file)

Generic Function: json OBJECT

Generic Function: (setf json) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: json (JSON json)

automatically generated reader method

Source

appenders.lisp (file)

Method: (setf json) NEW-VALUE (JSON json)

automatically generated writer method

Source

appenders.lisp (file)

Generic Function: level OBJECT

Generic Function: (setf level) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: level (APPENDER appender)

automatically generated reader method

Source

appenders.lisp (file)

Method: (setf level) NEW-VALUE (APPENDER appender)

automatically generated writer method

Source

appenders.lisp (file)

Method: level (LOGGER logger)

Method: (setf level) NEW-VALUE (LOGGER logger)

This loggers level.

Source

log.lisp (file)

Method: level (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf level) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

Generic Function: log-level LOG

Package

a-cl-logger

Source

log.lisp (file)

Writer

(setf log-level) (generic function)

Methods

Method: log-level (LOG logger)

Method: log-level IT &aux LOG

Generic Function: (setf log-level) NEW LOG &optional RECURSIVE

Change the logger’s level of to NEW-LEVEL. If RECUSIVE is T the setting is also applied to the sub logger of logger.

Package

a-cl-logger

Source

log.lisp (file)

Reader

log-level (generic function)

Methods

Method: (setf log-level) NEW-LEVEL (APPENDER appender) &optional RECURSIVE

Source

appenders.lisp (file)

Method: (setf log-level) NEW-LEVEL LOG &optional RECURSIVE

Generic Function: log-stream OBJECT

Generic Function: (setf log-stream) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: log-stream (STREAM-LOG-APPENDER stream-log-appender)

automatically generated reader method

Source

appenders.lisp (file)

Method: (setf log-stream) NEW-VALUE (STREAM-LOG-APPENDER stream-log-appender)

automatically generated writer method

Source

appenders.lisp (file)

Generic Function: logger CONDITION

Generic Function: (setf logger) NEW-VALUE CONDITION

Package

a-cl-logger

Methods

Method: logger (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf logger) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

Method: logger (CONDITION appending-message)

Method: (setf logger) NEW-VALUE (CONDITION appending-message)

Source

log.lisp (file)

Method: logger (CONDITION logging-message)

Method: (setf logger) NEW-VALUE (CONDITION logging-message)

Source

log.lisp (file)

Generic Function: message CONDITION

Generic Function: (setf message) NEW-VALUE CONDITION

Package

a-cl-logger

Methods

Method: message (CONDITION appending-message)

Method: (setf message) NEW-VALUE (CONDITION appending-message)

Source

log.lisp (file)

Method: message (CONDITION logging-message)

Method: (setf message) NEW-VALUE (CONDITION logging-message)

Source

log.lisp (file)

Method: message (CONDITION generating-message)

Method: (setf message) NEW-VALUE (CONDITION generating-message)

Source

log.lisp (file)

Generic Function: name CONDITION

Generic Function: (setf name) NEW-VALUE CONDITION

Package

a-cl-logger

Methods

Method: name (LOGGER logger)

automatically generated reader method

Source

log.lisp (file)

Method: (setf name) NEW-VALUE (LOGGER logger)

automatically generated writer method

Source

log.lisp (file)

Method: name (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf name) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

Method: name (CONDITION missing-logger)

Method: (setf name) NEW-VALUE (CONDITION missing-logger)

Source

log.lisp (file)

Generic Function: parents OBJECT

Generic Function: (setf parents) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: parents (LOGGER logger)

Method: (setf parents) NEW-VALUE (LOGGER logger)

The logger this logger inherits from.

Source

log.lisp (file)

5.1.5 Conditions

Condition: appending-message ()

Package

a-cl-logger

Source

log.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• appender (method)
• appender (method)
• logger (method)
• logger (method)
• message (method)
• message (method)

Direct slots

Slot: message

Initargs

:message

Initform

(quote nil)

Readers

message (generic function)

Writers

(setf message) (generic function)

Slot: logger

Initargs

:logger

Initform

(quote nil)

Readers

logger (generic function)

Writers

(setf logger) (generic function)

Slot: appender

Initargs

:appender

Initform

(quote nil)

Readers

appender (generic function)

Writers

(setf appender) (generic function)

Condition: generating-message ()

Package

a-cl-logger

Source

log.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• message (method)
• message (method)

Direct slots

Slot: message

Initargs

:message

Initform

(quote nil)

Readers

message (generic function)

Writers

(setf message) (generic function)

Condition: logging-message ()

Package

a-cl-logger

Source

log.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• logger (method)
• logger (method)
• message (method)
• message (method)

Direct slots

Slot: message

Initargs

:message

Initform

(quote nil)

Readers

message (generic function)

Writers

(setf message) (generic function)

Slot: logger

Initargs

:logger

Initform

(quote nil)

Readers

logger (generic function)

Writers

(setf logger) (generic function)

5.1.6 Classes

Class: appender ()

The base of all log appenders (destinations)

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

stream-log-appender (class)

Direct methods

• format-message (method)
• format-message (method)
• (setf log-level) (method)
• initialize-instance (method)
• level (method)
• level (method)
• formatter (method)
• formatter (method)

Direct slots

Slot: formatter

Initargs

:formatter

Readers

formatter (generic function)

Writers

(setf formatter) (generic function)

Slot: level

Initargs

:level

Readers

level (generic function)

Writers

(setf level) (generic function)

Class: debug-io-log-appender ()

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

stream-log-appender (class)

Direct Default Initargs

Initarg	Value
:stream	*debug-io*

Class: file-log-appender ()

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

stream-log-appender (class)

Direct subclasses

json-file-log-appender (class)

Direct methods

• append-message (method)
• (setf log-file) (method)
• buffer-p (method)
• buffer-p (method)
• log-file (method)
• log-file (method)

Direct slots

Slot: log-file

Name of the file to write log messages to.

Initargs

:log-file

Readers

log-file (generic function)

Writers

(setf log-file) (generic function)

Slot: buffer-p

Initargs

:buffer-p

Initform

t

Readers

buffer-p (generic function)

Writers

(setf buffer-p) (generic function)

Direct Default Initargs

Initarg	Value
:date-format	:iso

Class: formatter ()

The base class of all message formatters

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• raw-formatter (class)
• json-formatter (class)

Class: json ()

A type to know when something is already encoded, so that
we just write it out. It is sometimes beneficial to pre-encode some bits of log data and this allows that

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• json (method)
• json (method)

Direct slots

Slot: json

Initargs

:json

Readers

json (generic function)

Writers

(setf json) (generic function)

Class: json-formatter ()

The base class of all json formatters

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

formatter (class)

Direct methods

• format-message (method)
• format-value (method)

Class: logger ()

Package

a-cl-logger

Source

log.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• log-level (method)
• initialize-instance (method)
• print-object (method)
• compile-time-level (method)
• compile-time-level (method)
• level (method)
• level (method)
• appenders (method)
• appenders (method)
• children (method)
• children (method)
• parents (method)
• parents (method)
• default-signal-bindings (method)
• default-signal-bindings (method)
• signal-messages (method)
• signal-messages (method)
• name (method)
• name (method)

Direct slots

Slot: name

Initargs

:name

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: signal-messages

Initargs

:signal-messages

Initform

t

Readers

signal-messages (generic function)

Writers

(setf signal-messages) (generic function)

Slot: default-signal-bindings

Initargs

:default-signal-bindings

Readers

default-signal-bindings (generic function)

Writers

(setf default-signal-bindings) (generic function)

Slot: parents

The logger this logger inherits from.

Initargs

:parents

Initform

(quote nil)

Readers

parents (generic function)

Writers

(setf parents) (generic function)

Slot: children

The logger which inherit from this logger.

Initargs

:children

Initform

(quote nil)

Readers

children (generic function)

Writers

(setf children) (generic function)

Slot: appenders

A list of appender objects this logger sholud send messages to.

Initargs

:appenders

Initform

(quote nil)

Readers

appenders (generic function)

Writers

(setf appenders) (generic function)

Slot: level

This loggers level.

Type

(or null integer)

Initargs

:level

Readers

level (generic function)

Writers

(setf level) (generic function)

Slot: compile-time-level

This loggers’s compile time level. Any log expression below this level will macro-expand to NIL.

Type

(or null integer)

Initargs

:compile-time-level

Readers

compile-time-level (generic function)

Writers

(setf compile-time-level) (generic function)

Class: message ()

Package

a-cl-logger

Source

log.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• format-message (method)
• format-message (method)
• do-logging (method)
• timestamp (method)
• timestamp (method)
• arg-literals (method)
• arg-literals (method)
• data-plist (method)
• data-plist (method)
• format-args (method)
• format-args (method)
• format-control (method)
• format-control (method)
• level (method)
• level (method)
• logger (method)
• logger (method)
• name (method)
• name (method)

Direct slots

Slot: name

Initargs

:name

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: logger

Initargs

:logger

Readers

logger (generic function)

Writers

(setf logger) (generic function)

Slot: level

Initargs

:level

Readers

level (generic function)

Writers

(setf level) (generic function)

Slot: format-control

Initargs

:format-control

Readers

format-control (generic function)

Writers

(setf format-control) (generic function)

Slot: format-args

Initargs

:format-args

Readers

format-args (generic function)

Writers

(setf format-args) (generic function)

Slot: data-plist

Initargs

:data-plist

Readers

data-plist (generic function)

Writers

(setf data-plist) (generic function)

Slot: arg-literals

Initargs

:arg-literals

Readers

arg-literals (generic function)

Writers

(setf arg-literals) (generic function)

Slot: timestamp

Initargs

:timestamp

Initform

(local-time:now)

Readers

timestamp (generic function)

Writers

(setf timestamp) (generic function)

Class: raw-formatter ()

format the message with no annotations

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

formatter (class)

Class: stderr-log-appender ()

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

stream-log-appender (class)

Direct Default Initargs

Initarg	Value
:stream	*error-output*

Class: stream-log-appender ()

Human readable to the console logger.

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

appender (class)

Direct subclasses

• string-stream-appender (class)
• stderr-log-appender (class)
• debug-io-log-appender (class)
• file-log-appender (class)

Direct methods

• append-message (method)
• log-stream (method)
• log-stream (method)

Direct slots

Slot: stream

Initargs

:stream

Readers

log-stream (generic function)

Writers

(setf log-stream) (generic function)

Slot: date-format

Format to print dates. Format can be one of: (:iso :stamp :time)

Initargs

:date-format

Initform

:time

Class: string-stream-appender ()

a log that appends all messages into a string stream

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

stream-log-appender (class)

Direct methods

initialize-instance (method)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *logger*

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: *logger-vars*

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: *max-logger-name-length*

Package

a-cl-logger

Source

utils.lisp (file)

Special Variable: +muted+

Package

a-cl-logger

Source

utils.lisp (file)

5.2.2 Macros

Macro: define-log-helpers LOGGER-NAME

Package

a-cl-logger

Source

log.lisp (file)

Macro: define-mutator-macros &rest NAMES

defines mutator macros for a function name
eg: ensure-account-id =>
(defmacro ensure-account-id! (&rest places) ... ) which (setf place (name place) for each place)

%name is just so we dont accidentally run into someone using name accidentally

Package

a-cl-logger

Source

utils.lisp (file)

Macro: ensure-level-value! &rest PLACES

Package

a-cl-logger

Source

utils.lisp (file)

Macro: ensure-list! &rest PLACES

Package

a-cl-logger

Source

utils.lisp (file)

Macro: ensure-message! &rest PLACES

Package

a-cl-logger

Source

utils.lisp (file)

Macro: maybe-with-presentations (OUTPUT-STREAM VAR &rest STREAM-PROPERTIES) &body BODY

Buffer the output to var, printing as if to a swank dedicated presentation stream, dumping to a freshline on the output-stream when done.

Package

a-cl-logger

Source

utils.lisp (file)

Macro: push-m-plist PLIST PLACE

Package

a-cl-logger

Source

utils.lisp (file)

Macro: root-logger.debug &rest @MESSAGE-ARGS

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: root-logger.dribble &rest @MESSAGE-ARGS

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: root-logger.error &rest @MESSAGE-ARGS

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: root-logger.fatal &rest @MESSAGE-ARGS

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: root-logger.info &rest @MESSAGE-ARGS

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: root-logger.muted &rest @MESSAGE-ARGS

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: root-logger.warn &rest @MESSAGE-ARGS

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: when-log-message-* SIGNAL (&body HANDLER-BODY) &body BODY

A macro that allows appending data to the log message based on the dynamic context of the message as it is being generated.

The data-builder-form will be executed inside a context where (push-into-message key value) is a function to put data into the message the first form is

Inside of the handler body, a ‘change-message‘ restart is available

Ex: attaching information about the current http-context to log messages originating from it.

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: when-log-message-logged (&body HANDLER-BODY) &body BODY

Package

a-cl-logger

Source

helpers.lisp (file)

Macro: with-auto-unique-names (&rest NAMES) &body BODY

Package

a-cl-logger

Source

utils.lisp (file)

Macro: with-change-message (MESSAGE-PLACE) &body BODY

Package

a-cl-logger

Source

log.lisp (file)

Macro: with-debugging-or-error-printing (LOGGER &key CONTINUE) &body BODY

Package

a-cl-logger

Source

utils.lisp (file)

Macro: with-logger-level LOGGER-NAME NEW-LEVEL &body BODY

Set the level of the listed logger(s) to NEW-LEVEL and restore the original value in an unwind-protect.

Package

a-cl-logger

Source

utils.lisp (file)

Macro: with-logging-io () &body BODY

Package

a-cl-logger

Source

utils.lisp (file)

Macro: with-macro-splicing (&rest NAMES) &body FORMS

Double quasi-quoting hurts my head so lets do it a bit different

Instead lets replace symbols in the expansion with values named by the same symbols in the expansion environment.

Obviously care needs to be taken when processing forms passed by the user, but that is the name of the macro game.

Variables starting with an @ (such as @body) are spliced as with ‘(progn ,@)

In the interest of enhanced readability it is suggested that all template variables start with $ or @ so that they stand out

eg:
(let ((@b ’(2 3))) (with-macro-splicing (($a 1) @b) (+ $a @b 4)))
=> (+ 1 2 3 4)

Package

a-cl-logger

Source

utils.lisp (file)

Macro: with-stream-restarts (S RECALL) &body BODY

Package

a-cl-logger

Source

appenders.lisp (file)

5.2.3 Functions

Function: %filter-plist MSG &optional EXCLUDE

Package

a-cl-logger

Source

appenders.lisp (file)

Function: %logger-name-for-output LOG &key WIDTH

Output the logger name such that it takes exactly :width characters and displays the right most :width characters if name is too long

this simplifies our formatting

Package

a-cl-logger

Source

log.lisp (file)

Function: %make-log-helper LOGGER MESSAGE-LEVEL-NAME

Creates macros like logger.debug to facilitate logging

Package

a-cl-logger

Source

log.lisp (file)

Function: %open-log-file UFLA

Package

a-cl-logger

Source

appenders.lisp (file)

Function: %safe-log-helper-arg FORM

Package

a-cl-logger

Source

log.lisp (file)

Function: as-json-array LIST

Package

a-cl-logger

Source

utils.lisp (file)

Function: as-json-object-member K V FORMATTER

Package

a-cl-logger

Source

utils.lisp (file)

Function: class-name-of O

Package

a-cl-logger

Source

utils.lisp (file)

Function: close-message-block OPEN MESSAGE

Package

a-cl-logger

Source

helpers.lisp (file)

Function: copy-messsage M &rest PLIST

Package

a-cl-logger

Source

log.lisp (file)

Function: enabled-p OBJECT CHECK-AGAINST

Package

a-cl-logger

Source

log.lisp (file)

Function: ensure-level-value LEVEL

Package

a-cl-logger

Source

log.lisp (file)

Function: ensure-message IT

Package

a-cl-logger

Source

utils.lisp (file)

Function: ensure-stream-appender LOGGER STREAM &key TYPE

Package

a-cl-logger

Source

appenders.lisp (file)

Function: ensure-type VAL TYPE

Package

a-cl-logger

Source

log.lisp (file)

Function: format-time &key STREAM TIME FORMAT

Package

a-cl-logger

Source

utils.lisp (file)

Function: get-logger-var-name NAME

Package

a-cl-logger

Source

log.lisp (file)

Function: logger-inspector-lookup-hook FORM

Package

a-cl-logger

Source

appenders.lisp (file)

Function: logger-level-from-helper NAME

Package

a-cl-logger

Source

log.lisp (file)

Function: logger-name-from-helper NAME

Package

a-cl-logger

Source

log.lisp (file)

Function: logger-signal-handlers LOGGER CONDITION

Package

a-cl-logger

Source

log.lisp (file)

Function: maybe-signal-appending-message LOGGER APPENDER MESSAGE

Package

a-cl-logger

Source

log.lisp (file)

Function: maybe-signal-generating-message MESSAGE

Package

a-cl-logger

Source

log.lisp (file)

Function: maybe-signal-logging-message LOGGER MESSAGE

Package

a-cl-logger

Source

log.lisp (file)

Function: maybe-signal-message C MESSAGE &aux *MESSAGE* LOGGER

Package

a-cl-logger

Source

log.lisp (file)

Function: me-or-ancestor LOGGER TO-MATCH

Package

a-cl-logger

Source

utils.lisp (file)

Function: missing-logger NAME

Package

a-cl-logger

Source

log.lisp (file)

Function: only-one? THING

Package

a-cl-logger

Source

utils.lisp (file)

Function: open-message-block MESSAGE

Package

a-cl-logger

Source

helpers.lisp (file)

Function: rem-logger NAME &aux VAR

Package

a-cl-logger

Source

log.lisp (file)

Function: replace-symbols-in-forms PLIST FORMS &aux TBL

Processor for forms using with-macro-splicing

Package

a-cl-logger

Source

utils.lisp (file)

Function: split-log-helper SYM

Package

a-cl-logger

Source

log.lisp (file)

Function: without-earmuffs SYMBOL

Package

a-cl-logger

Source

utils.lisp (file)

5.2.4 Generic functions

Generic Function: arg-literals OBJECT

Generic Function: (setf arg-literals) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: arg-literals (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf arg-literals) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

Generic Function: buffer-p OBJECT

Generic Function: (setf buffer-p) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: buffer-p (FILE-LOG-APPENDER file-log-appender)

automatically generated reader method

Source

appenders.lisp (file)

Method: (setf buffer-p) NEW-VALUE (FILE-LOG-APPENDER file-log-appender)

automatically generated writer method

Source

appenders.lisp (file)

Generic Function: compile-time-enabled-p MESSAGE-LEVEL LOGGER

Package

a-cl-logger

Source

log.lisp (file)

Methods

Method: compile-time-enabled-p MESSAGE-LEVEL LOGGER

Generic Function: compile-time-level OBJECT

Generic Function: (setf compile-time-level) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: compile-time-level (LOGGER logger)

Method: (setf compile-time-level) NEW-VALUE (LOGGER logger)

This loggers’s compile time level. Any log expression below this level will macro-expand to NIL.

Source

log.lisp (file)

Generic Function: do-append LOGGER APPENDER MESSAGE

Package

a-cl-logger

Source

log.lisp (file)

Methods

Method: do-append LOG APPENDER MESSAGE around

Method: do-append LOG APPENDER MESSAGE

Generic Function: form CONDITION

Generic Function: (setf form) NEW-VALUE CONDITION

Package

a-cl-logger

Methods

Method: form (CONDITION log-argument-evaluation-error)

Method: (setf form) NEW-VALUE (CONDITION log-argument-evaluation-error)

Source

log.lisp (file)

Generic Function: format-value V FORMATTER

Package

a-cl-logger

Source

appenders.lisp (file)

Methods

Method: format-value V FORMATTER

Method: format-value V (F json-formatter)

Generic Function: inner-error CONDITION

Generic Function: (setf inner-error) NEW-VALUE CONDITION

Package

a-cl-logger

Methods

Method: inner-error (CONDITION log-argument-evaluation-error)

Method: (setf inner-error) NEW-VALUE (CONDITION log-argument-evaluation-error)

Source

log.lisp (file)

Generic Function: log-file OBJECT

Generic Function: (setf log-file) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: log-file (FILE-LOG-APPENDER file-log-appender)

Method: (setf log-file) NEW-VALUE (FILE-LOG-APPENDER file-log-appender)

Name of the file to write log messages to.

Source

appenders.lisp (file)

Method: (setf log-file) VAL (UFLA file-log-appender) after

Source

appenders.lisp (file)

Generic Function: log.compile-time-level LOG

Package

a-cl-logger

Source

log.lisp (file)

Writer

(setf log.compile-time-level) (generic function)

Methods

Method: log.compile-time-level LOG

Generic Function: (setf log.compile-time-level) NEW LOG &optional RECURSIVE

Change the compile time log level of logger to NEW-LEVEL. If RECUSIVE is T the setting is also applied to the sub loggers.

Package

a-cl-logger

Source

log.lisp (file)

Reader

log.compile-time-level (generic function)

Methods

Method: (setf log.compile-time-level) NEW-LEVEL LOG &optional RECURSIVE

Generic Function: signal-messages OBJECT

Generic Function: (setf signal-messages) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: signal-messages (LOGGER logger)

automatically generated reader method

Source

log.lisp (file)

Method: (setf signal-messages) NEW-VALUE (LOGGER logger)

automatically generated writer method

Source

log.lisp (file)

Generic Function: timestamp OBJECT

Generic Function: (setf timestamp) NEW-VALUE OBJECT

Package

a-cl-logger

Methods

Method: timestamp (MESSAGE message)

automatically generated reader method

Source

log.lisp (file)

Method: (setf timestamp) NEW-VALUE (MESSAGE message)

automatically generated writer method

Source

log.lisp (file)

5.2.5 Conditions

Condition: log-argument-evaluation-error ()

Package

a-cl-logger

Source

log.lisp (file)

Direct superclasses

error (condition)

Direct methods

• inner-error (method)
• inner-error (method)
• form (method)
• form (method)

Direct slots

Slot: form

Initargs

:form

Initform

(quote nil)

Readers

form (generic function)

Writers

(setf form) (generic function)

Slot: inner-error

Initargs

:inner-error

Initform

(quote nil)

Readers

inner-error (generic function)

Writers

(setf inner-error) (generic function)

Condition: missing-logger ()

Package

a-cl-logger

Source

log.lisp (file)

Direct superclasses

error (condition)

Direct methods

• name (method)
• name (method)

Direct slots

Slot: name

Initargs

:name

Initform

(quote nil)

Readers

name (generic function)

Writers

(setf name) (generic function)

5.2.6 Classes

Class: json-file-log-appender ()

Package

a-cl-logger

Source

appenders.lisp (file)

Direct superclasses

file-log-appender (class)

Direct Default Initargs

Initarg	Value
:date-format	:iso
:formatter	(quote a-cl-logger:json-formatter)

Appendix A Indexes

A.1 Concepts