The 40ants-logging Reference Manual

This is the 40ants-logging Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 05:57:56 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 40ants-logging

Functions to configure log4cl for different contexts: REPL, Backend, Command Line Application.

Author

Alexander Artemenko <>

Home Page

https://40ants.com/logging/

Source Control

(GIT https://github.com/40ants/logging)

Bug Tracker

https://github.com/40ants/logging/issues

License

Unlicense

Long Description

<a id="x-2840ANTS-LOGGING-DOCS-2FINDEX-3A-40README-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

# 40ants-logging - Functions to configure log4cl for different contexts: REPL, Backend, Command Line Application.

<a id="40-ants-logging-asdf-system-details"></a>

## 40ANTS-LOGGING ASDF System Details

* Version: 0.1.0

* Description: Functions to configure log4cl for different contexts: ‘REPL‘, Backend, Command Line Application.

* Licence: Unlicense

* Author: Alexander Artemenko <svetlyak.40wt@gmail.com>

* Homepage: [https://40ants.com/logging/][3eb9]

* Bug tracker: [https://github.com/40ants/logging/issues][cd63]

* Source control: [GIT][0aac]

[![](https://github-actions.40ants.com/40ants/logging/matrix.svg?only=ci.run-tests)][2779]

![](http://quickdocs.org/badge/40ants-logging.svg)

<a id="x-2840ANTS-LOGGING-DOCS-2FINDEX-3A-3A-40INSTALLATION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

## 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 :40ants-logging)
“‘
<a id="x-2840ANTS-LOGGING-DOCS-2FINDEX-3A-3A-40USAGE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

## Usage

This small library encapsulates a logging approach for all ‘40A‘nts projects. It provides
a few functions to setup structured logging for two kinds of applications: backend and command-line utility.

For a backend you need to call [‘40ants-logging:setup-for-backend‘][d0af] function. It configures ‘LOG4CL‘ to output all logs to ‘STDOUT‘ in ‘JSON‘ format. We are doing this because these days most backends are running in the Docker or Kubernetes where easiest way to collect logs is to capture daemon’s ‘STDOUT‘.

For a command line utilities we are configuring ‘LOG4CL‘ to use plaintext format. Call [‘40ants-logging:setup-for-cli‘][78f4] to make the job. Why ‘LOG:CONFIG‘ is not enought? ‘LOG:CONFIG‘ uses ‘LOG4CL‘ appenders which are not aware of fields added by structured logging macro [‘log4cl-extras/context:with-fields‘][b464].

You can also build an example app to test how this logging works:

“‘
./build-example.sh
./logging-example –help
“‘
Here is how it’s output looks like for ‘CLI‘ mode:

“‘
% ./logging-example
<INFO> [2023-03-05T10:44:25.861365Z] 40ants-logging-example/cli cli.lisp (run-as-cli) Running as a command line application.
Fields:
request-id: 120002
<INFO> [2023-03-05T10:44:25.864960Z] 40ants-logging-example/cli cli.lisp (run-cli-loop) Sleeping 1 seconds
Fields:
request-id: 120002
iteration: 0
<INFO> [2023-03-05T10:44:26.865200Z] 40ants-logging-example/cli cli.lisp (run-cli-loop) Sleeping 1 seconds
Fields:
request-id: 120002
iteration: 1
...
“‘
and for backend mode:

“‘json
% ./logging-example –backend
{"fields":{"logger":"40ants-logging-example/cli","func":"run-as-backend","file":"cli.lisp","request-id":"120002"},"level":"INFO","message":"Running as a backend.","timestamp":"2023-03-05T10:46:12.812570Z"} {"fields":{"logger":"40ants-logging-example/cli","func":"run-backend-loop","file":"cli.lisp","request-id":"120002","iteration":0},"level":"INFO","message":"Sleeping 15 seconds","timestamp":"2023-03-05T10:46:12.822253Z"} {"fields":{"logger":"40ants-logging-example/cli","func":"run-backend-loop","file":"cli.lisp","request-id":"120002","iteration":1},"level":"INFO","message":"Sleeping 15 seconds","timestamp":"2023-03-05T10:46:27.822530Z"}
...
“‘
If you are using [‘40ants-slynk‘][04ac] system to setup a Slynk server, then [‘40ants-logging:setup-for-repl‘][d1f2] function will be called automatically on connect to the repl. You can observe logging configuration by like this:

“‘
CL-USER> (log:config)
ROOT, DEBUG
|
+-(1)-#<STABLE-THIS-CONSOLE-APPENDER {10055B18F3}>
| with #<JSON-LAYOUT {10055B6AD3}>
| :immediate-flush NIL
| :flush-interval 1
| :stream-owner NIL
| :stream #<SB-SYS:FD-STREAM for "standard output" {1001D016C3}>
| :message-count 0
| :filter :INFO
|
+-(2)-#<STABLE-THIS-CONSOLE-APPENDER {10023FB1D3}>
with #<PLAIN-LAYOUT {10055B46D3}>
:immediate-flush NIL
:flush-interval 1
:stream-owner NIL
:stream #<SLYNK-GRAY::SLY-OUTPUT-STREAM {1001D00153}>
:message-count 0
:filter :WARN
“‘
To change log level only for the ‘REPL‘, call ‘(40ants-logging:setup-for-repl :level :warn)‘ function. If you will change log level via standard function of ‘LOG4CL‘: ‘(log:config :warn)‘, it will change the global logging level which will affect the backend’s log in ‘JSON‘ format.

<a id="x-2840ANTS-LOGGING-DOCS-2FINDEX-3A-3A-40API-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>

## API

<a id="x-2840ANTS-LOGGING-3ASETUP-FOR-BACKEND-20FUNCTION-29"></a>

### [function](a285) ‘40ants-logging:setup-for-backend‘ &key (level \*default-level\*)

Configures ‘LOG4CL‘ for logging in ‘JSON‘ format.

<a id="x-2840ANTS-LOGGING-3ASETUP-FOR-CLI-20FUNCTION-29"></a>

### [function](8984) ‘40ants-logging:setup-for-cli‘ &key (level \*default-level\*)

Configures ‘LOG4CL‘ for logging in plain-text format with context fields support.

<a id="x-2840ANTS-LOGGING-3ASETUP-FOR-REPL-20FUNCTION-29"></a>

### [function](3e3a) ‘40ants-logging:setup-for-repl‘ &key (level \*level\*) (stream \*debug-io\*)

Configures ‘LOG4CL‘ for logging in ‘REPL‘ when you connect to the running lisp image already configured as a backend or ‘CLI‘ application.

If you are using [‘40ants-slynk‘][04ac] system, this function will be called automatically
when your ‘SLY‘ connects to the image.

<a id="x-2840ANTS-LOGGING-3AREMOVE-REPL-APPENDER-20FUNCTION-29"></a>

### [function](8f2a) ‘40ants-logging:remove-repl-appender‘

Returns configuration the state as it was after [‘setup-for-backend‘][d0af] or [‘setup-for-cli‘][78f4] call.

If you are using [‘40ants-slynk‘][04ac] system, this function will be called automatically
when your ‘SLY‘ disconnects from the image.

[b464]: https://40ants.com/log4cl-extras/#x-28LOG4CL-EXTRAS-2FCONTEXT-3AWITH-FIELDS-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29
[3eb9]: https://40ants.com/logging/
[d0af]: https://40ants.com/logging/#x-2840ANTS-LOGGING-3ASETUP-FOR-BACKEND-20FUNCTION-29
[78f4]: https://40ants.com/logging/#x-2840ANTS-LOGGING-3ASETUP-FOR-CLI-20FUNCTION-29
[d1f2]: https://40ants.com/logging/#x-2840ANTS-LOGGING-3ASETUP-FOR-REPL-20FUNCTION-29
[04ac]: https://40ants.com/slynk/#x-28-23A-28-2812-29-20BASE-CHAR-20-2E-20-2240ants-slynk-22-29-20ASDF-2FSYSTEM-3ASYSTEM-29
[0aac]: https://github.com/40ants/logging
[2779]: https://github.com/40ants/logging/actions
[a285]: https://github.com/40ants/logging/blob/8f32a96d500ee95bb43f1d98b6ee6d6782b7149b/src/core.lisp#L22
[3e3a]: https://github.com/40ants/logging/blob/8f32a96d500ee95bb43f1d98b6ee6d6782b7149b/src/core.lisp#L36
[8f2a]: https://github.com/40ants/logging/blob/8f32a96d500ee95bb43f1d98b6ee6d6782b7149b/src/core.lisp#L53
[8984]: https://github.com/40ants/logging/blob/8f32a96d500ee95bb43f1d98b6ee6d6782b7149b/src/core.lisp#L63
[cd63]: https://github.com/40ants/logging/issues

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

Version

0.1.0

Defsystem Dependency

40ants-asdf-system (system).

Dependency

40ants-logging/core (system).

Source

40ants-logging.asd.


2.2 40ants-logging/core

Author

Alexander Artemenko <>

Home Page

https://40ants.com/logging/

Source Control

(GIT https://github.com/40ants/logging)

Bug Tracker

https://github.com/40ants/logging/issues

License

Unlicense

Dependencies
  • log4cl-extras/config (system).
  • global-vars (system).
Source

40ants-logging.asd.


3 Files

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


3.1 Lisp


3.1.1 40ants-logging/40ants-logging.asd

Source

40ants-logging.asd.

Parent Component

40ants-logging (system).

ASDF Systems

3.1.2 40ants-logging/core/file-type.lisp

Source

40ants-logging.asd.

Parent Component

40ants-logging/core (system).

Packages

40ants-logging.

Public Interface

4 Packages

Packages are listed by definition order.


4.1 40ants-logging

Source

file-type.lisp.

Nickname

40ants-logging/core

Use List

common-lisp.

Public Interface

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Function: remove-repl-appender ()

Returns configuration the state as it was after SETUP-FOR-BACKEND or SETUP-FOR-CLI call.

If you are using 40ANTS-SLYNK system, this function will be called automatically when your SLY disconnects from the image.

Package

40ants-logging.

Source

file-type.lisp.

Function: setup-for-backend (&key level)

Configures LOG4CL for logging in JSON format.

Package

40ants-logging.

Source

file-type.lisp.

Function: setup-for-cli (&key level)

Configures LOG4CL for logging in plain-text format with context fields support.

Package

40ants-logging.

Source

file-type.lisp.

Function: setup-for-repl (&key level stream)

Configures LOG4CL for logging in REPL when you connect to the running lisp image already configured as a backend or CLI application.

If you are using 40ANTS-SLYNK system, this function will be called automatically
when your SLY connects to the image.

Package

40ants-logging.

Source

file-type.lisp.


Appendix A Indexes


A.1 Concepts


A.3 Variables