The log4cl-extras Reference Manual

This is the log4cl-extras Reference Manual, version 0.9.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 05:57:49 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 log4cl-extras

A bunch of addons to LOG4CL: JSON appender, context fields, cross-finger appender, etc.

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Long Description

This library extends LOG4CL system in a few ways:

* It helps with configuration of multiple appenders and layouts.
* Has a facility to catch context fields and to log them.
* Has a macro to log unhandled errors.
* Adds a layout to write messages as JSON, which is useful for production as makes easier to parse and process such logs. * Uses the appenders which are not disabled in case of some error which again, should be useful for production.

Version

0.9.0

Defsystem Dependency

40ants-asdf-system (system).

Dependencies
Source

log4cl-extras.asd.


2.2 log4cl-extras/config

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Dependencies
Source

log4cl-extras.asd.


2.3 log4cl-extras/json

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Dependencies
Source

log4cl-extras.asd.


2.4 log4cl-extras/context

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Dependencies
  • pythonic-string-reader (system).
  • named-readtables (system).
  • 40ants-doc (system).
Source

log4cl-extras.asd.


2.5 log4cl-extras/utils

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Dependencies
  • local-time (system).
  • cl-strings (system).
Source

log4cl-extras.asd.


2.6 log4cl-extras/plain

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Dependencies
Source

log4cl-extras.asd.


2.7 log4cl-extras/appenders

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Dependency

log4cl (system).

Source

log4cl-extras.asd.


2.8 log4cl-extras/error

Author

Alexander Artemenko

Home Page

https://40ants.com/log4cl-extras/

Source Control

(GIT https://github.com/40ants/log4cl-extras)

Bug Tracker

https://github.com/40ants/log4cl-extras/issues

License

BSD

Dependencies
  • pythonic-string-reader (system).
  • named-readtables (system).
  • dissect (system).
  • log4cl (system).
  • log4cl-extras/context (system).
  • log4cl-extras/utils (system).
  • global-vars (system).
  • with-output-to-stream (system).
  • alexandria (system).
Source

log4cl-extras.asd.


3 Files

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


3.1 Lisp


3.1.2 log4cl-extras/config/file-type.lisp

Source

log4cl-extras.asd.

Parent Component

log4cl-extras/config (system).

Packages

log4cl-extras/config.

Public Interface

setup (function).

Internals

3.1.3 log4cl-extras/json/file-type.lisp

Source

log4cl-extras.asd.

Parent Component

log4cl-extras/json (system).

Packages

log4cl-extras/json.

Public Interface
Internals

3.1.4 log4cl-extras/context/file-type.lisp

Source

log4cl-extras.asd.

Parent Component

log4cl-extras/context (system).

Packages

log4cl-extras/context.

Public Interface
Internals

3.1.5 log4cl-extras/utils/file-type.lisp

Source

log4cl-extras.asd.

Parent Component

log4cl-extras/utils (system).

Packages

log4cl-extras/utils.

Public Interface

3.1.6 log4cl-extras/plain/file-type.lisp

Source

log4cl-extras.asd.

Parent Component

log4cl-extras/plain (system).

Packages

log4cl-extras/plain.

Public Interface
Internals

3.1.7 log4cl-extras/appenders/file-type.lisp

Source

log4cl-extras.asd.

Parent Component

log4cl-extras/appenders (system).

Packages

log4cl-extras/appenders.

Public Interface

3.1.8 log4cl-extras/error/file-type.lisp

Source

log4cl-extras.asd.

Parent Component

log4cl-extras/error (system).

Packages

log4cl-extras/error.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 log4cl-extras/utils

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

4.2 log4cl-extras/plain

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

plain-layout (class).

Internals

4.3 log4cl-extras/config

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

setup (function).

Internals

4.4 log4cl-extras/appenders

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

4.5 log4cl-extras/context

Source

file-type.lisp.

Use List

common-lisp.

Public Interface
Internals

4.6 log4cl-extras/error

Source

file-type.lisp.

Use List

common-lisp.

Public Interface
Internals

4.7 log4cl-extras/json

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

json-layout (class).

Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Macros

Macro: with-fields ((&rest fields) &body body)

Captures content of given fields into a dynamic variable.

These fields will be logged along with any log entry inside the WITH-FIELDS body.

Package

log4cl-extras/context.

Source

file-type.lisp.

Macro: with-log-unhandled ((&key depth errors-to-ignore) &body body)

Logs any ERROR condition signaled from the body. Logged message will have a "traceback" field.

You may specify a list of error classes to ignore as ERRORS-TO-IGNORE argument.
Errors matching (typep err <each-of errors-to-ignore>) will not be logged as "Unhandled".

Package

log4cl-extras/error.

Source

file-type.lisp.


5.1.2 Ordinary functions

Function: get-fields ()

Returns an alist of all fields defined using WITH-FIELDS macro in the current stack.

Keys are returned as downcased strings, prepared for logging.

Package

log4cl-extras/context.

Source

file-type.lisp.

Function: get-timestamp (&key timezone)
Package

log4cl-extras/utils.

Source

file-type.lisp.

Function: is-sly-stream (stream)
Package

log4cl-extras/utils.

Source

file-type.lisp.

Function: limit-length (text max-len)
Package

log4cl-extras/utils.

Source

file-type.lisp.

Function: make-args-filter (predicate placeholder)

Returns a function, suitable to be used in *ARGS-FILTERS* variable.

Function PREDICATE will be applied to each argument in the frame and if it returns T, then argument will be replaced with PLACEHOLDER.

Package

log4cl-extras/error.

Source

file-type.lisp.

Function: make-placeholder (name)

Creates a placeholder for some secret value or omitted argument.

“‘
CL-USER> (log4cl-extras/error:make-placeholder "secret value")

#<secret value>
“‘

See LOG4CL-EXTRAS/SECRETS::@HARD-WAY section to learn, how to use placeholders to remove sensitive information from logs.

Package

log4cl-extras/error.

Source

file-type.lisp.

Function: placeholder-p (obj)
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: print-backtrace (&key stream condition depth max-call-length args-filters format-condition)

A helper to print backtrace. Could be useful to out backtrace
at places other than logs, for example at a web page.

This function applies the same filtering rules as WITH-LOG-UNHANDLED macro.

By default condition description is printed like this:

“‘
Condition REBLOCKS-WEBSOCKET:NO-ACTIVE-WEBSOCKETS: No active websockets bound to the current page. “‘

But you can change this by providing an argument FORMAT-CONDITION. It should be a
function of two arguments: ‘(stream condition)‘.

Package

log4cl-extras/error.

Source

file-type.lisp.

Function: print-with-indent (stream prefix text)

Prints a prefix to each line of the of the text.

Package

log4cl-extras/utils.

Source

file-type.lisp.

Function: remove-newlines (text)
Package

log4cl-extras/utils.

Source

file-type.lisp.

Function: setup (config)

Setup loggers and appenders via confg.

Example:

“‘
(setup
’(:level :error
:appenders
(this-console
(file
:file "foo.log"
:layout json))
:loggers
((log4cl-extras/config
:loggers
((foo :level :debug)
(bar
:loggers
((some-class
:level debug))))))))
“‘

As you can see, SETUP function accepts a plist with keys :LEVEL, :APPENDERS and :LOGGERS.

:LEVEL key holds a logging level for the root logger. It could be :INFO, :WARN or :ERROR.

:APPENDERS is a list of list where each sublist should start from the appender type and arguments for it’s constructor.

Supported appenders are:

* ‘THIS-CONSOLE‘ corresponds to LOG4CL:THIS-CONSOLE-APPENDER class.
* ‘DAILY‘ corresponds to LOG4CL:DAILY-FILE-APPENDER class.
* ‘FILE‘ corresponds to LOG4CL:FILE-APPENDER.

To lookup supported arguments for each appender type, see these classes initargs.
the only difference is that :LAYOUT argument is processed in a special way:
:JSON value replaced with LOG4CL-EXTRAS/JSON:JSON-LAYOUT and :PLAIN is replaced
with LOG4CL-EXTRAS/PLAIN:PLAIN-LAYOUT.

And finally, you can pass to SETUP a list of loggers. Each item in this list
should be plist where first item is a symbolic name of a package or a function name
inside a package and other items are params for a nested SETUP call.

Package

log4cl-extras/config.

Source

file-type.lisp.


5.1.3 Generic functions

Generic Reader: placeholder-name (object)
Package

log4cl-extras/error.

Methods
Reader Method: placeholder-name ((placeholder placeholder))

automatically generated reader method

Source

file-type.lisp.

Target Slot

name.


5.1.4 Standalone methods

Method: handle-appender-error ((a dont-disable-mixin) condition)
Package

log4cl-impl.

Source

file-type.lisp.

Method: layout-to-stream ((layout plain-layout) stream logger level log-func)
Package

log4cl-impl.

Source

file-type.lisp.

Method: layout-to-stream ((layout json-layout) stream logger level log-func)
Package

log4cl-impl.

Source

file-type.lisp.

Method: print-object ((obj placeholder) stream)
Source

file-type.lisp.


5.1.5 Classes

Class: dont-disable-mixin
Package

log4cl-extras/appenders.

Source

file-type.lisp.

Direct subclasses
Direct methods

handle-appender-error.

Class: json-layout
Package

log4cl-extras/json.

Source

file-type.lisp.

Direct superclasses

layout.

Direct methods
Direct slots
Slot: timezone
Type

local-time::timezone

Initform

local-time:*default-timezone*

Initargs

:timezone

Readers

get-timezone.

Writers

This slot is read-only.

Class: placeholder

Objects of this class can be used as replacement to arguments in a backtrace.

They are printed like ‘#<some-name>‘.

This form was choosen to match the way how SBCL shows unused arguments: ‘#<unused argument>‘.

Placeholders should be created with MAKE-PLACEHOLDER function.

Package

log4cl-extras/error.

Source

file-type.lisp.

Direct methods
Direct slots
Slot: name
Type

string

Initargs

:name

Readers

placeholder-name.

Writers

This slot is read-only.

Class: plain-layout
Package

log4cl-extras/plain.

Source

file-type.lisp.

Direct superclasses

layout.

Direct methods
Direct slots
Slot: timezone
Type

local-time::timezone

Initform

local-time:*default-timezone*

Initargs

:timezone

Readers

get-timezone.

Writers

This slot is read-only.

Class: stable-daily-file-appender
Package

log4cl-extras/appenders.

Source

file-type.lisp.

Direct superclasses
Class: stable-file-appender
Package

log4cl-extras/appenders.

Source

file-type.lisp.

Direct superclasses
Class: stable-this-console-appender
Package

log4cl-extras/appenders.

Source

file-type.lisp.

Direct superclasses

5.2 Internals


5.2.1 Special variables

Special Variable: *fields*

A stack of data fields to be serialized to JSON

Fields are stored as a plist, and transformed into an alist before serialization.

Package

log4cl-extras/context.

Source

file-type.lisp.

Special Variable: +format-info+
Package

log4cl-extras/plain.

Source

file-type.lisp.

Special Variable: +format-info+
Package

log4cl-extras/json.

Source

file-type.lisp.

Special Variable: @configuration
Package

log4cl-extras/config.

Source

file-type.lisp.

Special Variable: @context
Package

log4cl-extras/context.

Source

file-type.lisp.

Special Variable: @errors
Package

log4cl-extras/error.

Source

file-type.lisp.

Special Variable: @intro
Package

log4cl-extras/error.

Source

file-type.lisp.

Special Variable: @printing
Package

log4cl-extras/error.

Source

file-type.lisp.


5.2.2 Ordinary functions

Function: apply-args-filters (func-name args &key args-filters)
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: call-with-log-unhandled (thunk &key depth errors-to-ignore)
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: format-condition-object (stream condition)
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: format-frame (stream idx call args file line &key max-call-length)
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: from-current-package (frame)
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: get-backtrace ()
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: get-current-args-filters ()
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: make-appender (name args)
Package

log4cl-extras/config.

Source

file-type.lisp.

Function: make-layout (name args)
Package

log4cl-extras/config.

Source

file-type.lisp.

Function: make-logger (categories)
Package

log4cl-extras/config.

Source

file-type.lisp.

Function: prepare (frame args-filters)
Package

log4cl-extras/error.

Source

file-type.lisp.

Function: setup-logger (logger &key appenders loggers level)
Package

log4cl-extras/config.

Source

file-type.lisp.

Function: write-json-item (stream logger log-func level &key timezone)
Package

log4cl-extras/json.

Source

file-type.lisp.

Function: write-plain-item (stream logger log-func level &key timezone)
Package

log4cl-extras/plain.

Source

file-type.lisp.


5.2.3 Generic functions

Generic Reader: get-timezone (object)
Package

log4cl-extras/plain.

Methods
Reader Method: get-timezone ((plain-layout plain-layout))

automatically generated reader method

Source

file-type.lisp.

Target Slot

timezone.

Generic Reader: get-timezone (object)
Package

log4cl-extras/json.

Methods
Reader Method: get-timezone ((json-layout json-layout))

automatically generated reader method

Source

file-type.lisp.

Target Slot

timezone.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   F   G   H   I   L   M   P   R   S   W  
Index Entry  Section

A
apply-args-filters: Private ordinary functions

C
call-with-log-unhandled: Private ordinary functions

F
format-condition-object: Private ordinary functions
format-frame: Private ordinary functions
from-current-package: Private ordinary functions
Function, apply-args-filters: Private ordinary functions
Function, call-with-log-unhandled: Private ordinary functions
Function, format-condition-object: Private ordinary functions
Function, format-frame: Private ordinary functions
Function, from-current-package: Private ordinary functions
Function, get-backtrace: Private ordinary functions
Function, get-current-args-filters: Private ordinary functions
Function, get-fields: Public ordinary functions
Function, get-timestamp: Public ordinary functions
Function, is-sly-stream: Public ordinary functions
Function, limit-length: Public ordinary functions
Function, make-appender: Private ordinary functions
Function, make-args-filter: Public ordinary functions
Function, make-layout: Private ordinary functions
Function, make-logger: Private ordinary functions
Function, make-placeholder: Public ordinary functions
Function, placeholder-p: Public ordinary functions
Function, prepare: Private ordinary functions
Function, print-backtrace: Public ordinary functions
Function, print-with-indent: Public ordinary functions
Function, remove-newlines: Public ordinary functions
Function, setup: Public ordinary functions
Function, setup-logger: Private ordinary functions
Function, write-json-item: Private ordinary functions
Function, write-plain-item: Private ordinary functions

G
Generic Function, get-timezone: Private generic functions
Generic Function, get-timezone: Private generic functions
Generic Function, placeholder-name: Public generic functions
get-backtrace: Private ordinary functions
get-current-args-filters: Private ordinary functions
get-fields: Public ordinary functions
get-timestamp: Public ordinary functions
get-timezone: Private generic functions
get-timezone: Private generic functions
get-timezone: Private generic functions
get-timezone: Private generic functions

H
handle-appender-error: Public standalone methods

I
is-sly-stream: Public ordinary functions

L
layout-to-stream: Public standalone methods
layout-to-stream: Public standalone methods
limit-length: Public ordinary functions

M
Macro, with-fields: Public macros
Macro, with-log-unhandled: Public macros
make-appender: Private ordinary functions
make-args-filter: Public ordinary functions
make-layout: Private ordinary functions
make-logger: Private ordinary functions
make-placeholder: Public ordinary functions
Method, get-timezone: Private generic functions
Method, get-timezone: Private generic functions
Method, handle-appender-error: Public standalone methods
Method, layout-to-stream: Public standalone methods
Method, layout-to-stream: Public standalone methods
Method, placeholder-name: Public generic functions
Method, print-object: Public standalone methods

P
placeholder-name: Public generic functions
placeholder-name: Public generic functions
placeholder-p: Public ordinary functions
prepare: Private ordinary functions
print-backtrace: Public ordinary functions
print-object: Public standalone methods
print-with-indent: Public ordinary functions

R
remove-newlines: Public ordinary functions

S
setup: Public ordinary functions
setup-logger: Private ordinary functions

W
with-fields: Public macros
with-log-unhandled: Public macros
write-json-item: Private ordinary functions
write-plain-item: Private ordinary functions


A.4 Data types

Jump to:   C   D   F   J   L   P   S  
Index Entry  Section

C
Class, dont-disable-mixin: Public classes
Class, json-layout: Public classes
Class, placeholder: Public classes
Class, plain-layout: Public classes
Class, stable-daily-file-appender: Public classes
Class, stable-file-appender: Public classes
Class, stable-this-console-appender: Public classes

D
dont-disable-mixin: Public classes

F
File, file-type.lisp: The log4cl-extras/config/file-type․lisp file
File, file-type.lisp: The log4cl-extras/json/file-type․lisp file
File, file-type.lisp: The log4cl-extras/context/file-type․lisp file
File, file-type.lisp: The log4cl-extras/utils/file-type․lisp file
File, file-type.lisp: The log4cl-extras/plain/file-type․lisp file
File, file-type.lisp: The log4cl-extras/appenders/file-type․lisp file
File, file-type.lisp: The log4cl-extras/error/file-type․lisp file
File, log4cl-extras.asd: The log4cl-extras/log4cl-extras․asd file
file-type.lisp: The log4cl-extras/config/file-type․lisp file
file-type.lisp: The log4cl-extras/json/file-type․lisp file
file-type.lisp: The log4cl-extras/context/file-type․lisp file
file-type.lisp: The log4cl-extras/utils/file-type․lisp file
file-type.lisp: The log4cl-extras/plain/file-type․lisp file
file-type.lisp: The log4cl-extras/appenders/file-type․lisp file
file-type.lisp: The log4cl-extras/error/file-type․lisp file

J
json-layout: Public classes

L
log4cl-extras: The log4cl-extras system
log4cl-extras.asd: The log4cl-extras/log4cl-extras․asd file
log4cl-extras/appenders: The log4cl-extras/appenders system
log4cl-extras/appenders: The log4cl-extras/appenders package
log4cl-extras/config: The log4cl-extras/config system
log4cl-extras/config: The log4cl-extras/config package
log4cl-extras/context: The log4cl-extras/context system
log4cl-extras/context: The log4cl-extras/context package
log4cl-extras/error: The log4cl-extras/error system
log4cl-extras/error: The log4cl-extras/error package
log4cl-extras/json: The log4cl-extras/json system
log4cl-extras/json: The log4cl-extras/json package
log4cl-extras/plain: The log4cl-extras/plain system
log4cl-extras/plain: The log4cl-extras/plain package
log4cl-extras/utils: The log4cl-extras/utils system
log4cl-extras/utils: The log4cl-extras/utils package

P
Package, log4cl-extras/appenders: The log4cl-extras/appenders package
Package, log4cl-extras/config: The log4cl-extras/config package
Package, log4cl-extras/context: The log4cl-extras/context package
Package, log4cl-extras/error: The log4cl-extras/error package
Package, log4cl-extras/json: The log4cl-extras/json package
Package, log4cl-extras/plain: The log4cl-extras/plain package
Package, log4cl-extras/utils: The log4cl-extras/utils package
placeholder: Public classes
plain-layout: Public classes

S
stable-daily-file-appender: Public classes
stable-file-appender: Public classes
stable-this-console-appender: Public classes
System, log4cl-extras: The log4cl-extras system
System, log4cl-extras/appenders: The log4cl-extras/appenders system
System, log4cl-extras/config: The log4cl-extras/config system
System, log4cl-extras/context: The log4cl-extras/context system
System, log4cl-extras/error: The log4cl-extras/error system
System, log4cl-extras/json: The log4cl-extras/json system
System, log4cl-extras/plain: The log4cl-extras/plain system
System, log4cl-extras/utils: The log4cl-extras/utils system