The log4cl-extras Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The log4cl-extras Reference Manual

This is the log4cl-extras Reference Manual, version 0.5.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 05:30:46 2022 GMT+0.

Table of Contents


1 Introduction

LOG4CL-EXTRAS - Addons for Log4CL

LOG4CL-EXTRAS ASDF System Details

Installation

You can install this library from Quicklisp, but you want to receive updates quickly, then install it from Ultralisp.org:

(ql-dist:install-dist "http://dist.ultralisp.org/"
                      :prompt nil)
(ql:quickload :log4cl-extras)

Configuration

By default LOG4CL outputs log items like this:

CL-USER> (log:info "Hello")
 <INFO> [01:15:37] cl-user () - Hello

However logging extra context fields requires a custom "layout". Layout defines the way how the message will be formatted.

This system defines two layout types:

To use these custom layouts, you have to use setup function. It also allows to set a log level for root logger and appenders. Here is a minimal example showing how to configure logger for the REPL:

CL-USER> (log4cl-extras/config:setup
          '(:level :debug
            :appenders ((this-console :layout :plain))))
NIL

CL-USER> (log:info "Hello")
<INFO> [2021-05-16T01:16:46.978992+03:00] Hello

CL-USER> (log4cl-extras/context:with-fields (:foo "Bar")
           (log:info "Hello"))
<INFO> [2021-05-16T01:26:30.331849+03:00] Hello
  Fields:
    foo: Bar

If you replace :PLAIN with :JSON, you'll get this:

CL-USER> (log4cl-extras/config:setup
          '(:level :debug
            :appenders ((this-console :layout :json))))
; No values
CL-USER> (log4cl-extras/context:with-fields (:foo "Bar")
           (log:info "Hello"))
{"fields":{"foo":"Bar"},"level":"INFO","message":"Hello","timestamp":"2021-05-16T01:27:54.879336+03:00"}

Appender in terms of log4cl is a target for log output. You can combine multiple appenders in a single call to setup function.

Here is the example of the config, suitable for production. Here we log all messages as JSON records into the file, rotated on the daily basis. And all errors and warnings will be written to the REPL.

(log4cl-extras/config:setup
 '(:level :debug
   :appenders ((this-console :layout :plain
                             :filter :warn)
               (daily :layout :json
                      :name-format "/app/logs/app.log"
                      :backup-name-format "app-%Y%m%d.log"))))

Also, setup allows to change log levels for different loggers:

function log4cl-extras/config: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:

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.

Layouts

class log4cl-extras/plain:plain-layout (layout)

class log4cl-extras/json:json-layout (layout)

Context Fields

Macro with-fields let to to capture some information into the dynamic variable. All messages logged inside the with-fields form will have these fields attached:

CL-USER> (log4cl-extras/config:setup
          '(:level :debug
            :appenders ((this-console :layout :plain))))

CL-USER> (defun process-request ()
           (log:info "Processing request"))

CL-USER> (log4cl-extras/context:with-fields (:request-id 42)
           (process-request))
<INFO> [2020-07-19T10:03:21.079636Z] Processing request
  Fields:
    request-id: 42

;; Now let's switch to JSON layout:
CL-USER> (log4cl-extras/config:setup
          '(:level :debug
            :appenders ((this-console :layout :json))))

CL-USER> (log4cl-extras/context:with-fields (:request-id 42)
           (process-request))
{"fields": {"request-id": 42},
 "level": "INFO",
 "message": "Processing request",
 "timestamp": "2020-07-19T10:03:32.855593Z"}

Beware!, catching context fields costs some time even if they are not logged.

macro log4cl-extras/context: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.

function log4cl-extras/context: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.

Logging Unhandled Errors

Quickstart

If you want to log unhandled signals traceback, then use with-log-unhandled macro.

Usually it is good idea, to use with-log-unhandled in the main function or in a function which handles a HTTP request.

If some error condition will be signaled by the body, it will be logged as an error with "traceback" field like this:

CL-USER> (defun foo ()
           (error "Some error happened"))

CL-USER> (defun bar ()
           (foo))

CL-USER> (log4cl-extras/error:with-log-unhandled ()
           (bar))

<ERROR> [2020-07-19T10:14:39.644805Z] Unhandled exception
  Fields:
  Traceback (most recent call last):
    File "NIL", line NIL, in FOO
      (FOO)
    File "NIL", line NIL, in BAR
      (BAR)
    File "NIL", line NIL, in (LAMBDA (…
      ((LAMBDA ()))
    File "NIL", line NIL, in SIMPLE-EV…
      (SB-INT:SIMPLE-EVAL-IN-LEXENV
       (LOG4CL-EXTRAS/ERROR:WITH-LOG-UNHANDLED NIL
         (BAR))
       #<NULL-LEXENV>)
    ...
       #<CLOSURE (LAMBDA () :IN SLYNK::CALL-WITH-LISTENER) {100A6B043B}>)
     
     
  Condition: Some error happened
; Debugger entered on #<SIMPLE-ERROR "Some error happened" {100A7A5DB3}>

The JSON layout will write such error like this:

{
  "fields": {
    "traceback": "Traceback (most recent call last):\n  File \"NIL\", line NIL, in FOO\n    (FOO)\n  File \"NIL\", line NIL, in BAR\n    (BAR)\n...\nCondition: Some error happened"
  },
  "level": "ERROR",
  "message": "Unhandled exception",
  "timestamp": "2020-07-19T10:21:33.557418Z"
}

Printing Backtrace

There is a helper function print-backtrace for extracting and printing backtrace, which can be used separately from logging. One use case is to render backtrace on the web page when a site is in a debug mode:

CL-USER> (log4cl-extras/error:print-backtrace :depth 3)
Traceback (most recent call last):
   0 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/eval.lisp", line 291
       In SB-INT:SIMPLE-EVAL-IN-LEXENV
     Args ((LOG4CL-EXTRAS/ERROR:PRINT-BACKTRACE :DEPTH 3) #<NULL-LEXENV>)
   1 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/eval.lisp", line 311
       In EVAL
     Args ((LOG4CL-EXTRAS/ERROR:PRINT-BACKTRACE :DEPTH 3))
   2 File "/Users/art/projects/lisp/sly/contrib/slynk-mrepl.lisp"
       In (LAMBDA () :IN SLYNK-MREPL::MREPL-EVAL-1)
     Args ()

By default, it prints to the *DEBUG-IO*, but you can pass it a :STREAM argument which has the same semantic as a stream for FORMAT function.

Other useful parameters are :DEPTH and :MAX-CALL-LENGTH. They allow to control how long and wide backtrace will be.

Also, you might pass :CONDITION. If it is given, it will be printed after the backtrace.

And finally, you can pass a list of functions to filter arguments before printing. This way secret or unnecesary long values can be stripped. See the next section to learn how to not log secret values.

API

variable log4cl-extras/error:*max-traceback-depth* 10

Keeps default value for traceback depth logged by with-log-unhandled macro

variable log4cl-extras/error:*max-call-length* 100

The max length of each line in a traceback. It is useful to limit it because otherwise some log collectors can discard the whole log entry.

variable log4cl-extras/error:*args-filters* nil

Add to this variable functions of two arguments to change arguments before they will be dumped as part of the backtrace to the log.

This is not a special variable, because it should be changed system-wide and can be accessedd from multiple threads.

macro log4cl-extras/error:with-log-unhandled (&key (depth *max-traceback-depth*)) &body body

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

function log4cl-extras/error:print-backtrace &key (stream *debug-io*) (condition nil) (depth *max-traceback-depth*) (max-call-length *max-call-length*) (args-filters *args-filters*)

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.

function log4cl-extras/error: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.

class log4cl-extras/error: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.

function log4cl-extras/error: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 Hard Way section to learn, how to use placeholders to remove sensitive information from logs.

function log4cl-extras/error:placeholder-p obj

reader log4cl-extras/error:placeholder-name (placeholder) (:name)

How Keep Secrets Out of Logs

When backtrace is printed to log files it is good idea to omit passwords, tokens, cookies, and other potentially sensitive values.

Here is a potential situation where you have a password and trying to create a new connection to the database. But because of some network error, an unhandled error along with a backtrace will be logged. Pay attention to our secret password in the log:

CL-USER> (log4cl-extras/config:setup
           '(:level :error
             :appenders ((this-console :layout plain))))
   
CL-USER> (defun connect (password)
           "Normally, we don't control this function's code
  because it is from the third-party library."
           (check-type password string)
           (error "Network timeout"))
   
CL-USER> (defun authenticate (password)
           "This function is in our app's codebase.
  It is calling a third-party DB driver."     
           (connect password))
   
CL-USER> (defun bar (password)
           (authenticate password))
   
CL-USER> (log4cl-extras/error:with-log-unhandled (:depth 5)
           (bar "The Secret Password"))
<ERROR> [2021-01-24T14:13:24.460890+03:00] Unhandled exception
  Fields:
  Traceback (most recent call last):
     0 File "unknown"
         In (FLET "H0")
       Args (#<SIMPLE-ERROR "Network timeout" {100F065533}>)
     1 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 81
         In SB-KERNEL::%SIGNAL
       Args (#<SIMPLE-ERROR "Network timeout" {100F065533}>)
     2 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 154
         In ERROR
       Args ("Network timeout")
     3 File "unknown"
         In CONNECT
       Args ("The Secret Password")
     4 File "unknown"
         In AUTHENTICATE
       Args ("The Secret Password")
  
  Condition: Network timeout

With log4cl-extras you can keep values in secret in two ways.

Easy Way

The easiest way, is two wrap all sensitive data using secret-values library as soon as possible and unwrap them only before usage.

Lets see what will happen if we'll use a wrapped password.

First, we need to teach AUTHENTICATE function, how to unwrap the password, before passing it to the driver:

CL-USER> (defun authenticate (password)
           "This function is in our app's codebase.
  It is calling a third-party DB driver."
           (connect
            (secret-values:ensure-value-revealed
             password)))

Next, we need to wrap password into a special object. It is better to do this as soon as possible. In production code you'll probably have something like (secret-values:conceal-value (uiop:getenv "POSTGRES_PASSWORD")):

CL-USER> (log4cl-extras/error:with-log-unhandled (:depth 5)
           (bar (secret-values:conceal-value
                 "The Secret Password")))
<ERROR> [2021-01-24T14:16:01.667651+03:00] Unhandled exception
  Fields:
  Traceback (most recent call last):
     0 File "unknown"
         In (FLET "H0")
       Args (#<SIMPLE-ERROR "Network timeout" {10036CB1A3}>)
     1 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 81
         In SB-KERNEL::%SIGNAL
       Args (#<SIMPLE-ERROR "Network timeout" {10036CB1A3}>)
     2 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 154
         In ERROR
       Args ("Network timeout")
     3 File "unknown"
         In CONNECT
       Args ("The Secret Password")
     4 File "unknown"
         In AUTHENTICATE
       Args (#<SECRET-VALUES:SECRET-VALUE {10036CB183}>)
     
  Condition: Network timeout

Pay attention to the fourth stack frame. AUTHENTICATE function has #<SECRET-VALUES:SECRET-VALUE {10036CB183}> as the first argument. But why do we see "The Secret Password" in the third frame anyway?

It is because we have to pass a raw version of the password to the libraries we don't control.

Here is where log4cl-extras comes to the resque. It provides a package LOG4CL-EXTRAS/SECRETS. It is optional and is not loaded together with the primary system.

Earlier, I've mentioned :ARGS-FILTERS argument to the log4cl-extras/error:print-backtrace function. Package LOG4CL-EXTRAS/SECRETS provides a function make-secrets-replacer which can be used to filter secret values.

We can add it into the global variable log4cl-extras/error:*args-filters* like this:

CL-USER> (ql:quickload :log4cl-extras/secrets)
(:LOG4CL-EXTRAS/SECRETS)
   
CL-USER> (setf log4cl-extras/error:*args-filters*
               (list (log4cl-extras/secrets:make-secrets-replacer)))
(#<CLOSURE (LABELS LOG4CL-EXTRAS/SECRETS::REMOVE-SECRETS :IN LOG4CL-EXTRAS/SECRETS:MAKE-SECRETS-REPLACER) {1007E4464B}>)

Now let's try to connect to our fake database again:

CL-USER> (log4cl-extras/error:with-log-unhandled (:depth 5)
           (bar (secret-values:conceal-value
                 "The Secret Password")))
<ERROR> [2021-01-24T14:27:17.851716+03:00] Unhandled exception
  Fields:
  Traceback (most recent call last):
     0 File "unknown"
         In (FLET "H0")
       Args (#<SIMPLE-ERROR "Network timeout" {100800F723}>)
     1 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 81
         In SB-KERNEL::%SIGNAL
       Args (#<SIMPLE-ERROR "Network timeout" {100800F723}>)
     2 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 154
         In ERROR
       Args ("Network timeout")
     3 File "unknown"
         In CONNECT
       Args (#<secret value>)
     4 File "unknown"
         In AUTHENTICATE
       Args (#<secret value>)
  
  Condition: Network timeout

Now both third and fourth frames show #<secret value> instead of the password. This is because (log4cl-extras/secrets:make-secrets-replacer) call returns a closure which remembers and replaces raw values of the secrets too!

Hard Way

Sometimes it is desireable to remove from tracebacks other kinds of data. For example I don't want to see Lack's environments, because of a few reasons:

Let's create a filter for arguments, which will replace Lack's environments with a placeholder.

First, we need to create a placeholder object:

CL-USER> (defvar +lack-env-placeholder+
           (log4cl-extras/error:make-placeholder "lack env"))
+LACK-ENV-PLACEHOLDER+

Next, we need to define a filter function. Each filter function should accept two arguments:

Filter should return two values, which can be the same is inputs or a transformed in some way.

For example, we know that the Lack's env is a plist with :REQUEST-METHOD, :REQUEST-URI and other values. We can to write a predicate like this:

CL-USER> (defun lack-env-p (arg)
           (and (listp arg)
                (member :request-method arg)
                (member :request-uri arg)))

And to use it in our filter:

CL-USER> (defun remove-lack-env-from-frame (func-name args)
           "Removes Lack's env from stackframes to make backtrace concise."
           (values func-name
                   (loop for arg in args
                         if (lack-env-p arg)
                           collect +lack-env-placeholder+
                         else
                           collect arg)))

Now let's try to use it:

CL-USER> (defun request-handler (app env)
           (authenticate (secret-values:conceal-value
                          "Secret password"))
           (pass-further app env))
   
CL-USER> (setf log4cl-extras/error:*args-filters*
               (list 'remove-lack-env-from-frame
                     ;; We need this too to keep DB password safe, remember?
                     (log4cl-extras/secrets:make-secrets-replacer)))

Now pay attention to the fifth frame, where second argument is replaced with #<lack env>!!!

CL-USER> (log4cl-extras/error:with-log-unhandled (:depth 7)
           (request-handler 42
                            (list :request-method :post
                                  :request-uri "/login/"
                                  :cookies "Session hash, and other secrets.")))
<ERROR> [2021-01-24T14:56:45.502656+03:00] Unhandled exception
  Fields:
  Traceback (most recent call last):
     0 File "unknown"
         In (FLET "H0")
       Args (#<SIMPLE-ERROR "Network timeout" {1004233EB3}>)
     1 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 81
         In SB-KERNEL::%SIGNAL
       Args (#<SIMPLE-ERROR "Network timeout" {1004233EB3}>)
     2 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 154
         In ERROR
       Args ("Network timeout")
     3 File "unknown"
         In CONNECT
       Args (#<secret value>)
     4 File "unknown"
         In AUTHENTICATE
       Args (#<secret value>)
     5 File "unknown"
         In REQUEST-HANDLER
       Args (42 #<lack env>)
     6 File "unknown"
         In (LAMBDA ())
       Args ()
     
  Condition: Network timeout

For such simple case like replacing args matching a predicate, log4cl-extras has a small helper log4cl-extras/error:make-args-filter:

CL-USER> (setf log4cl-extras/error:*args-filters*
               (list (log4cl-extras/error:make-args-filter
                      'lack-env-p
                      (log4cl-extras/error:make-placeholder "LACK ENV BEING HERE"))
                     ;; We need this too to keep DB password safe, remember?
                     (log4cl-extras/secrets:make-secrets-replacer)))
   
<ERROR> [2021-01-24T15:09:48.839513+03:00] Unhandled exception
  Fields:
  Traceback (most recent call last):
     0 File "unknown"
         In (FLET "H0")
       Args (#<SIMPLE-ERROR "Network timeout" {1003112243}>)
     1 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 81
         In SB-KERNEL::%SIGNAL
       Args (#<SIMPLE-ERROR "Network timeout" {1003112243}>)
     2 File "/Users/art/.roswell/src/sbcl-2.0.11/src/code/cold-error.lisp", line 154
         In ERROR
       Args ("Network timeout")
     3 File "unknown"
         In CONNECT
       Args (#<secret value>)
     4 File "unknown"
         In AUTHENTICATE
       Args (#<secret value>)
     5 File "unknown"
         In REQUEST-HANDLER
       Args (42 #<LACK ENV BEING HERE>)
     6 File "unknown"
         In (LAMBDA ())
       Args ()
  
  Condition: Network timeout

function log4cl-extras/secrets:make-secrets-replacer

Returns a function which can be used to filter backtrace arguments.

See log4cl-extras/error:*args-filters*


[generated by [40ANTS-DOC](https://40ants.com/doc

2 Systems

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


Next: , Previous: , Up: Systems   [Contents][Index]

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.5.1

Dependencies
Source

log4cl-extras.asd.


Next: , Previous: , Up: Systems   [Contents][Index]

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).
Source

log4cl-extras.asd.


3 Files

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


Previous: , Up: Files   [Contents][Index]

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/context

Source

file-type.lisp.

Use List

common-lisp.

Public Interface
Internals

4.2 log4cl-extras/appenders

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

4.3 log4cl-extras/error

Source

file-type.lisp.

Use List

common-lisp.

Public Interface
Internals

4.4 log4cl-extras/config

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

setup (function).

Internals

4.5 log4cl-extras/utils

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

4.6 log4cl-extras/json

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

json-layout (class).

Internals

Previous: , Up: Packages   [Contents][Index]

4.7 log4cl-extras/plain

Source

file-type.lisp.

Use List

common-lisp.

Public Interface

plain-layout (class).

Internals

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

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) &body body)

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

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)

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.

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 json-layout) stream logger level log-func)
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: 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


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *d*
Package

log4cl-extras/error.

Source

file-type.lisp.

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/json.

Source

file-type.lisp.

Special Variable: +format-info+
Package

log4cl-extras/plain.

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)
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: 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/json.

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

automatically generated reader method

Source

file-type.lisp.

Target Slot

timezone.

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.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

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-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-frame: Private ordinary functions
Function, from-current-package: Private ordinary functions
Function, get-backtrace: 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-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

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

Previous: , Up: Indexes   [Contents][Index]

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

Jump to:   C   D   F   J   L   P   S