taoensso.timbre

Simple, flexible logging for Clojure/Script. No XML.

*config*

dynamic

This map controls all Timbre behaviour including:
  - When to log (via level and namespace filtering)
  - How  to log (which appenders to use)
  - What to log (config to control how data sent to appenders
                 will be formatted to output string)

See `default-config` for default value (and example config).

Modify this config with `binding`, `alter-var-root`, or with utils:
     `set-level!`,         `with-level`,
    `set-config!`,        `with-config`,
  `merge-config!`, `with-merged-config`.

MAIN OPTIONS

  :min-level
    Logging will occur only if a logging call's level is >= this
    min-level. Possible values, in order:

      :trace  = level 0
      :debug  = level 1 ; Default min-level
      :info   = level 2
      :warn   = level 3
      :error  = level 4 ; Error type
      :fatal  = level 5 ; Error type
      :report = level 6 ; High general-purpose (non-error) type

    It's also possible to set the min-level based on the namespace
    by providing a vector that maps `ns-pattern`s to min-levels, e.g.:
    `[[#{"taoensso.*"} :error] ... [#{"*"} :debug]]`.

    Example `ns-pattern`s:
      #{}, "*", "foo.bar", "foo.bar.*", #{"foo" "bar.*"},
      {:allow #{"foo" "bar.*"} :deny #{"foo.*.bar.*"}}.

  :ns-filter
    Logging will occur only if a logging call's namespace is permitted
    by this ns-filter. Possible values:

      - Arbitrary (fn may-log-ns? [ns]) predicate fn.
      - An `ns-pattern` (see :min-level docs above).

    Useful for turning off logging in noisy libraries, etc.

  :middleware
    Vector of simple (fn [appender-data]) -> ?new-data fns (applied left->right)
    that transform the data map dispatched to appender fns. If any middleware
    returns nil, NO dispatch will occur (i.e. the event will be filtered).

    Useful for layering advanced functionality. Similar to Ring middleware.

  :timestamp-opts ; Config map, see `default-timestamp-opts`
  :output-fn      ; (fn [appender-data]) -> string, see `default-output-fn`

  :appenders ; {<appender-id> <appender-map>}

    Where each appender-map has keys:
      :enabled?        ; Must be truthy to log
      :min-level       ; Optional *additional* appender-specific min-level
      :ns-filter       ; Optional *additional* appender-specific ns-filter

      :async?          ; Dispatch using agent? Useful for slow appenders (clj only)

      :rate-limit      ; [[<ncalls-limit> <window-msecs>] ...], or nil
                       ; Appender will noop a call after exceeding given number
                       ; of the "same" calls within given rolling window/s.
                       ;
                       ; Example:
                       ;   [[100  (encore/ms :mins  1)]
                       ;    [1000 (encore/ms :hours 1)]] will noop a call after:
                       ;
                       ;   - >100  "same" calls in 1 rolling minute, or
                       ;   - >1000 "same" calls in 1 rolling hour
                       ;
                       ; "Same" calls are identified by default as the
                       ; combined hash of:
                       ;   - Callsite (i.e. each individual Timbre macro form)
                       ;   - Logging level
                       ;   - All arguments provided for logging
                       ;
                       ; You can manually override call identification:
                       ;   (timbre/infof ^:meta {:id "my-limiter-call-id"} ...)
                       ;

      :output-fn       ; Optional override for inherited (fn [appender-data]) -> string
      :timestamp-opts  ; Optional override for inherited config map
      :fn              ; (fn [appender-data]) -> side-effects, with keys described below

APPENDER DATA
  An appender's fn takes a single data map with keys:
    :config          ; Entire active config map
    :appender-id     ; Id of appender currently dispatching
    :appender        ; Entire map of appender currently dispatching
    :instant         ; Platform date (java.util.Date or js/Date)
    :level           ; Call's level keyword (e.g. :info) (>= active min-level)
    :error-level?    ; Is level e/o #{:error :fatal}?
    :?ns-str         ; String,  or nil
    :?file           ; String,  or nil
    :?line           ; Integer, or nil ; Waiting on CLJ-865
    :?err            ; First-arg platform error, or nil
    :?meta           ; First-arg map when it has ^:meta metadata, used as a
                       way of passing advanced per-call options to appenders
    :vargs           ; Vector of raw args provided to logging call
    :output_         ; Forceable - final formatted output string created
                     ; by calling (output-fn <this-data-map>)
    :msg_            ; Forceable - args as a string
    :timestamp_      ; Forceable - string
    :hostname_       ; Forceable - string (clj only)
    :output-fn       ; (fn [data]) -> formatted output string
                     ; (see `default-output-fn` for details)
    :context         ; `*context*` value at log time (see `with-context`)
    :spying?         ; Is call occuring via the `spy` macro?

    **NB** - any keys not specifically documented here should be
    considered private / subject to change without notice.

COMPILE-TIME LEVEL/NS ELISION
  To control :min-level and :ns-filter at compile-time, use:

    - `taoensso.timbre.min-level.edn`  JVM property (read as edn)
    - `taoensso.timbre.ns-pattern.edn` JVM property (read as edn)

    - `TAOENSSO_TIMBRE_MIN_LEVEL_EDN`  env var      (read as edn)
    - `TAOENSSO_TIMBRE_NS_PATTERN_EDN` env var      (read as edn)

*context*

dynamic

General-purpose dynamic logging context

-elide?

(-elide? level-form ns-str-form)
Returns true iff level or ns are compile-time filtered.
Called only at macro-expansiom time.

-log!

(-log! config level ?ns-str ?file ?line msg-type ?err vargs_ ?base-data)(-log! config level ?ns-str ?file ?line msg-type ?err vargs_ ?base-data callsite-id)(-log! config level ?ns-str ?file ?line msg-type ?err vargs_ ?base-data callsite-id spying?)
Core low-level log fn. Implementation detail!

-log-and-rethrow-errors

macro

(-log-and-rethrow-errors ?line & body)

-log-errors

macro

(-log-errors ?line & body)

-logged-future

macro

(-logged-future ?line & body)

-spy

macro

(-spy ?line config level name expr)

color-str

(color-str color & xs)

debug

macro

(debug & args)

debugf

macro

(debugf & args)

default-config

Default/example Timbre `*config*` value:

{:min-level :debug #_[["taoensso.*" :error] ["*" :debug]]
 :ns-filter #{"*"} #_{:deny #{"taoensso.*"} :allow #{"*"}}

 :middleware [] ; (fns [appender-data]) -> ?data, applied left->right

 :timestamp-opts default-timestamp-opts ; {:pattern _ :locale _ :timezone _}
 :output-fn      default-output-fn ; (fn [appender-data]) -> string

 :appenders
 #?(:clj
    {:println (println-appender {:stream :auto})
     ;; :spit (spit-appender    {:fname "./timbre-spit.log"})
     }

    :cljs
    (if (exists? js/window)
      {:console (console-appender {})}
      {:println (println-appender {})}))}

See `*config*` for more info.

default-err

default-out

default-output-fn

(default-output-fn data)(default-output-fn opts data)
Default (fn [data]) -> string output fn.
Use`(partial default-output-fn <opts-map>)` to modify default opts.

default-timestamp-opts

Controls (:timestamp_ data)

error

macro

(error & args)

errorf

macro

(errorf & args)

fatal

macro

(fatal & args)

fatalf

macro

(fatalf & args)

get-?hostname

(get-?hostname)
Returns live local hostname, or nil.

get-env

macro

(get-env)

get-hostname

Returns cached hostname string.

handle-uncaught-jvm-exceptions!

(handle-uncaught-jvm-exceptions! & [handler])
Sets JVM-global DefaultUncaughtExceptionHandler.

info

macro

(info & args)

infof

macro

(infof & args)

level>=

(level>= x y)
Implementation detail.

log

macro

(log level & args)

log!

macro

(log! level msg-type args & [opts])
Core low-level log macro. Useful for tooling/library authors, etc.

  * `level`    - must eval to a valid logging level
  * `msg-type` - must eval to e/o #{:p :f nil}
  * `args`     - arguments for logging call
  * `opts`     - ks e/o #{:config :?err :?ns-str :?file :?line :?base-data :spying?}

Supports compile-time elision when compile-time const vals
provided for `level` and/or `?ns-str`.

Logging wrapper examples:

  (defn     log-wrapper-fn    [& args]  (timbre/log! :info :p  args))
  (defmacro log-wrapper-macro [& args] `(timbre/log! :info :p ~args))

log*

macro

(log* config level & args)

log-and-rethrow-errors

macro

(log-and-rethrow-errors & body)

log-errors

macro

(log-errors & body)

logf

macro

(logf level & args)

logf*

macro

(logf* config level & args)

logged-future

macro

(logged-future & body)

may-log?

(may-log? level)(may-log? level ?ns-str)(may-log? level ?ns-str ?config)(may-log? default-min-level level ?ns-str ?config)
Implementation detail.
Returns true iff level and ns are runtime unfiltered.

merge-config!

(merge-config! m)

println-appender

(println-appender & [{:keys [stream], :or {stream :auto}}])
Returns a simple `println` appender for Clojure/Script.
Use with ClojureScript requires that `cljs.core/*print-fn*` be set.

:stream (clj only) - e/o #{:auto :*out* :*err* :std-err :std-out <io-stream>}.

refer-timbre

(refer-timbre)
Shorthand for:
(require '[taoensso.timbre :as timbre
           :refer (log  trace  debug  info  warn  error  fatal  report
                   logf tracef debugf infof warnf errorf fatalf reportf
                   spy get-env log-env)])

report

macro

(report & args)

reportf

macro

(reportf & args)

set-config!

(set-config! m)

set-level!

(set-level! level)

sometimes

macro

(sometimes probability & body)
Handy for sampled logging, etc.

spit-appender

(spit-appender & [{:keys [fname append? locking?], :or {fname "./timbre-spit.log", append? true, locking? true}}])
Returns a simple `spit` file appender for Clojure.

spy

macro

(spy expr)(spy level expr)(spy level name expr)(spy config level name expr)
Evaluates named expression and logs its result. Always returns the result.
Defaults to :debug logging level and unevaluated expression as name.

stacktrace

(stacktrace err)(stacktrace err opts)

swap-config!

(swap-config! f & args)

trace

macro

(trace & args)

tracef

macro

(tracef & args)

warn

macro

(warn & args)

warnf

macro

(warnf & args)

with-config

macro

(with-config config & body)

with-context

macro

(with-context context & body)
Executes body so that given arbitrary data will be passed (as `:context`)
to appenders for any enclosed logging calls.

(with-context
  {:user-name "Stu"} ; Will be incl. in data dispatched to appenders
  (info "User request"))

See also `with-context+`.

with-context+

macro

(with-context+ context & body)
Like `with-context`, but merges given context into current context.

with-default-outs

macro

(with-default-outs & body)

with-level

macro

(with-level level & body)

with-merged-config

macro

(with-merged-config config & body)