Timbre Logging Library

Timbre is a pure Clojure and ClojureScript logging library designed to be fast, flexible, and easy to configure using pure Clojure data. It avoids the complexity of XML or properties-based Java logging configurations and works out of the box.

Key features include:

• Full support for both Clojure and ClojureScript with built-in appenders for both.
• Configuration via a single, simple Clojure map.
• Extensible via appenders (fn [data]) -> ?effects and middleware (fn [data]) -> ?data.
• Ability to save raw logging arguments to databases.
• Granular filtering by level, namespace, or appender.
• Zero overhead compile-time level/namespace elision.
• Support for rate limits and asynchronous logging.
• Optional interop with tools.logging and Java logging via SLF4Jv2.

Timbre's behavior is controlled by the dynamic *config* map. You can override the default configuration using:

• Utility functions like set-config!, merge-config!, or set-min-level!.
• JVM properties.
• Environment variables.
• An .edn file on your resource path.

Timbre follows a simple data-driven flow for every logging call (e.g., (info ...)):

1. Config Check: Uses the dynamic *config* to determine the active configuration.
2. Level Check: If the call's level is lower than the active minimum level, the call is a no-op.
3. Namespace Filter: If the current namespace is filtered out, the call is a no-op.
4. Data Preparation: A log data map is created containing the log level, namespace, and all arguments.
5. Middleware: The data map is passed through middleware functions (fn [data]) -> ?data. If a middleware returns nil, the process stops.
6. Appenders: The (potentially transformed) data map is passed to all appender functions (fn [data]) -> ?effects, which handle the actual output (printing, DB writes, etc.).

To route logging from legacy frameworks like Log4j, java.util.logging (JUL), or Apache Commons Logging (JCL) into Timbre, you must use an SLF4J bridge. The data flow follows this path:

1. Legacy Framework (Log4j/JUL/JCL) $\rightarrow$ SLF4J Bridge $\rightarrow$ SLF4J API
2. SLF4J API $\rightarrow$ Timbre (via timbre-slf4j)

Ensure you have configured the SLF4J backend to use Timbre as described in the SLF4J setup guide.

The Postal appender sends log entries via email using the postal library.

Setup:

1. Add [com.draines/postal <latest-version>] to your project dependencies.
2. Require taoensso.timbre.appenders (postal :as postal-appender) in your namespace.
3. Configure the appender with server credentials and email metadata (from/to) using postal-appender/postal-appender.

;; (:require [taoensso.timbre.appenders (postal :as postal-appender)])

(timbre/merge-config!
  {:appenders
   {:postal
    (postal-appender/postal-appender
      ^{:host "mail.isp.net" :user "jsmith" :pass "sekrat!!1"}
      {:from "me@draines.com" :to "foo@example.com"})}})

The Carmine appender provides high-performance logging to Redis. It preserves all raw logging arguments in serialized form (including errors) and allows you to configure the number of entries kept per log level. It only keeps the most recent instance of each unique entry. The resulting log is a Clojure vector of log entry maps, which can be queried using standard Clojure tools or the car-appender/query-entries function.

Setup:

1. Add [com.taoensso/carmine <latest-version>] to your project dependencies.
2. Require taoensso.timbre.appenders [carmine :as car-appender] in your namespace.
3. Register it via timbre/merge-config!.

;; (:require [taoensso.timbre.appenders [carmine :as car-appender]])

(timbre/merge-config! {:appenders {:carmine (car-appender/carmine-appender)}})

To reduce bundle size or improve performance, Timbre can exclude disabled logging calls at compile-time using JVM properties or environment variables. This is useful for production builds where you want to strip out :debug or :trace calls entirely.

Environment Variables:

• TAOENSSO_TIMBRE_MIN_LEVEL_EDN: Set the minimum level (e.g., ':warn').
• TAOENSSO_TIMBRE_NS_PATTERN_EDN: Set the namespace filter pattern.

# Elide all lower-level logging calls:
export TAOENSSO_TIMBRE_MIN_LEVEL_EDN=':warn'

# Elide all other ns logging calls:
export TAOENSSO_TIMBRE_NS_PATTERN_EDN='{:allow #{"my-app.*"} :deny #{"my-app.foo" "my-app.bar.*"}}'

lein cljsbuild once # Compile js with appropriate logging calls excluded
lein uberjar        # Compile jar

To use Timbre, require it in your namespace. You can manually list the functions you want to refer, or use (timbre/refer-timbre) to automatically refer all standard logging functions.

(ns my-ns
  (:require
    [taoensso.timbre :as timbre
      ;; Optional, just refer what you like:
      :refer [log  trace  debug  info  warn  error  fatal  report
              logf tracef debugf infof warnf errorf fatalf reportf
              spy]]))

Add Timbre as a dependency to your project using Leiningen or Clojure CLI (deps.edn).

Leiningen: [com.taoensso/timbre               "x-y-z"]
; or
deps.edn:   com.taoensso/timbre {:mvn/version "x-y-z"}

The spit appender writes log entries to a specified file. You can configure it using timbre/merge-config! by passing a map with the :appenders key and a :spit map containing the :fname option.

To disable the appender, set :enabled? to false. To remove it entirely from the configuration, set it to nil.