logging

Bauhaus Setup Logging

Module to setup proper logging infrastructure.

We log using timbre.

We use structured logging writing JSON log messages to a log file which then can be tailed by a log agent and sent to your logging infrastructure.

Also, it sets up collecting messages from different logging libraries using SLF4J, so no matter what logging library a third party is using, you only configure logging in one place.

Supported logging libraries:

• clojure/tools.logging
• SLF4J
• Apache Commons Logging
• Log4J 2
• Log4J
• java.util.logging

Setup logging sets up handling of uncaught exceptions, so no exception goes by unnoticed anymore. Also, it captures elements not serializable to JSON.

⚠️ Attention ⚠️: Setup logging does not care for you logging secrets or personal identifyable information. So make sure you your logs are safe from an information security perspective and DSGVO-wise (personal identifyable information). Never log API secrets, user credentials or tokens, usernames without consent or even user IP addresses without consent.

Usage in a library

In a library, you may choose whichever logging library you want to use, as long as it's supported by setup logging in the application using that library.

We strongly advise to use timbre.

However, as you want to configure logging for the REPL used to develop the library or the tests running, you can use setup logging as follows:

Install

Add com.taoensso/timbre {:mvn/version "5.2.1"} to your deps.edn :deps map.

Also, add this project to your deps.edn as dev or test :extra-deps. In Bauhaus itself, this is possible from the local repository structure using

:aliases {:dev {:extra-deps  {org.gorillalabs.bauhaus/setup-logging {:local/root "../../modules/setup/logging"}}}}

or using git coordinates like this, but with the latest :git/sha

{       ...
 org.gorillalabs.bauhaus/setup-logging {:git/url   "git@github.com:gorillalabs/bauhaus.git"
                                          :git/sha   "AE...<commit sha>"
                                          :deps/root "modules/setup/logging"}
        ...}

Initialize

After REPL startup (or before running tests), call gorillalabs.bauhaus.setup.log/init-dev-logging which will setup simple message logging to the console.

Usage in an application

Install

Add this project to your deps.edn. In the Bauhaus project itself, this is possible from the local repository structure using

{:deps {...
        org.gorillalabs.bauhaus/setup-logging {:local/root "../../modules/setup/logging"}
        ...
        }}

or using git coordinates like this, but with the latest :git/sha

{       ...
 org.gorillalabs.bauhaus/setup-logging {:git/url   "git@github.com:gorillalabs/bauhaus.git"
                                        :git/sha   "AE...<commit sha>"
                                        :deps/root "modules/setup/logging"}
 ...}

Configure JVM

To configure clojure/tools.logging, you need to run your code with the System property -Dclojure.tools.logging.factory=clojure.tools.logging.impl/slf4j-factory set (see Selecting a logging implementation).

Initialize logging

During system startup, call gorillalabs.bauhaus.setup.log/init-logging with the location of your (rotating) logfile.

Alternatively, there's gorillalabs.bauhaus.setup.log/init-dev-logging which will use simple message logging to the console.

Start logging

Require [taoensso.timbre :as log] and use timbre just as it's supposed to be used.

You might also use any other logging API, but we recommend using timbre for our code.

Change logging configuration

You can change logging configuration at any point in time using timbre's (log/merge-config! new-config).