Update docs

ChangeLog.md

@@ -2,6 +2,17 @@
 
 # ChangeLog
 
+<a id="x-2840ANTS-LOGGING-DOCS-2FCHANGELOG-3A-3A-7C0-2E3-2E0-7C-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>
+
+## 0.3.0 (2025-01-12)
+
+<a id="changed"></a>
+
+### Changed
+
+* Now [`40ants-logging:setup-for-backend`][d0af] function and [`40ants-logging:setup-for-cli`][78f4] function set the given level not only for appender but also for a root logger, preventing `REPL` pollution with all debug logs.
+* Also, [`40ants-logging:setup-for-repl`][d1f2] function now uses `:DEBUG` as default for `:LEVEL` argument. This way you only need to set needed log level for selected packages using `LOG4SLY` and Emacs.
+
 <a id="x-2840ANTS-LOGGING-DOCS-2FCHANGELOG-3A-3A-7C0-2E2-2E0-7C-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>
 
 ## 0.2.0 (2024-11-20)
@@ -22,6 +33,7 @@
 
 [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
 
 * * *
 ###### [generated by [40ANTS-DOC](https://40ants.com/doc/)]

README.md

@@ -33,9 +33,33 @@ You can install this library from Quicklisp, but you want to receive updates qui
 
 ## Usage
 
-This small library encapsulates a logging approach for all `40A`nts projects. It provides
+This small library encapsulates a logging approach for all `40Ants` projects. It provides
 a few functions to setup structured logging for two kinds of applications: backend and command-line utility.
 
+<a id="the-main-idea"></a>
+
+### The main idea
+
+The idea of our approach to logging is that an application work in two modes:
+
+* regular;
+* `IDE` connected.
+
+In regular mode application should log to the standard output or to the file usually using `JSON` format. These logs should be collected and stored in some kind of log store like ElasticSearch. Usually you want to limit log to store only `WARN` and `ERROR` levels.
+
+In the second mode, a developer has connected to the app and wants to be able to see some log outputs in the `REPL`.
+
+We define two log appenders for these two modes:
+
+* main log appender writes logs in regular mode.
+* repl log appender can be added when `REPL` is enabled. This is done automatically if you start Slynk using [`40ants-slynk`][04ac] system.
+
+Note, a developer don't need to see all `INFO` and `DEBUG` logs but only these logs from some package. So, we keep root logger's level the same as was specified for the main log appender. For example, imagine the main appender was configured to log `WARN` and `INFO`, but `REPL` appender configured to show `DEBUG`. When you'll connect to the `REPL`, it will not be cluttered with `DEBUG` messages from the all packages, instead only `WARN` and `ERROR` will be logged to the `REPL` the same as they will be logged to the main appender. But if you want to debug some package, you can set `DEBUG` level for this package only using `LOG4SLY`.
+
+<a id="details"></a>
+
+### Details
+
 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].
@@ -104,19 +128,19 @@ To change log level only for the `REPL`, call `(40ants-logging:setup-for-repl :l
 
 <a id="x-2840ANTS-LOGGING-3ASETUP-FOR-BACKEND-20FUNCTION-29"></a>
 
-### [function](ab3c) `40ants-logging:setup-for-backend` &key (level \*default-level\*)
+### [function](4889) `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](18a2) `40ants-logging:setup-for-cli` &key (level \*default-level\*)
+### [function](abec) `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](f8dd) `40ants-logging:setup-for-repl` &key (level \*level\*) (stream \*debug-io\*)
+### [function](4435) `40ants-logging:setup-for-repl` &key (level :debug) (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.
 
@@ -125,7 +149,7 @@ when your `SLY` connects to the image.
 
 <a id="x-2840ANTS-LOGGING-3AREMOVE-REPL-APPENDER-20FUNCTION-29"></a>
 
-### [function](f213) `40ants-logging:remove-repl-appender`
+### [function](a05a) `40ants-logging:remove-repl-appender`
 
 Returns configuration the state as it was after [`setup-for-backend`][d0af] or [`setup-for-cli`][78f4] call.
 
@@ -141,10 +165,10 @@ when your `SLY` disconnects from the image.
 [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
-[f213]: https://github.com/40ants/logging/blob/99339d2087081a6732f50215293b2dae1934b1fa/src/core.lisp#L122
-[ab3c]: https://github.com/40ants/logging/blob/99339d2087081a6732f50215293b2dae1934b1fa/src/core.lisp#L38
-[18a2]: https://github.com/40ants/logging/blob/99339d2087081a6732f50215293b2dae1934b1fa/src/core.lisp#L69
-[f8dd]: https://github.com/40ants/logging/blob/99339d2087081a6732f50215293b2dae1934b1fa/src/core.lisp#L96
+[4435]: https://github.com/40ants/logging/blob/aec98451cfc1581485c475243fb561cb27f26443/src/core.lisp#L108
+[a05a]: https://github.com/40ants/logging/blob/aec98451cfc1581485c475243fb561cb27f26443/src/core.lisp#L135
+[4889]: https://github.com/40ants/logging/blob/aec98451cfc1581485c475243fb561cb27f26443/src/core.lisp#L38
+[abec]: https://github.com/40ants/logging/blob/aec98451cfc1581485c475243fb561cb27f26443/src/core.lisp#L81
 [cd63]: https://github.com/40ants/logging/issues
 [07be]: https://quickdocs.org/global-vars
 [691c]: https://quickdocs.org/log4cl-extras