taoensso.timbre

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

*config*

dynamic

See `example-config` for info.

*context*

dynamic

General-purpose dynamic logging context. Context will be included in
appender data map at logging time.

-elide?

(-elide? level-form ns-str-form)

-levels-map

-levels-set

-levels-vec

-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)
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)

compile-ns-filter

Returns (fn [?ns]) -> truthy.

debug

macro

(debug & args)

debugf

macro

(debugf & args)

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)

example-config

Example (+default) Timbre v4 config map.

APPENDERS
  An appender is a map with keys:
    :min-level       ; Level keyword, or nil (=> no minimum level)
    :enabled?        ;
    :async?          ; Dispatch using agent? Useful for slow appenders (clj only)
    :rate-limit      ; [[ncalls-limit window-ms] <...>], or nil
    :output-fn       ; Optional override for inherited (fn [data]) -> string
    :timestamp-opts  ; Optional override for inherited {:pattern _ :locale _ :timezone _}
    :ns-whitelist    ; Optional, stacks with active config's whitelist
    :ns-blacklist    ; Optional, stacks with active config's blacklist
    :middleware-fn   ; Optional, stacks with active config's middleware
    :fn              ; (fn [data]) -> side effects, with keys described below

  An appender's fn takes a single data map with keys:
    :config          ; Entire config map (this map, etc.)
    :appender-id     ; Id of appender currently dispatching
    :appender        ; Entire map of appender currently dispatching
    :instant         ; Platform date (java.util.Date or js/Date)
    :level           ; Keyword
    :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
    :vargs           ; Vector of raw args
    :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`)

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

MIDDLEWARE
  Middleware are simple (fn [data]) -> ?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).

The `example-config` source code contains further settings and details.
See also `set-config!`, `merge-config!`, `set-level!`.

fatal

macro

(fatal & args)

fatalf

macro

(fatalf & args)

get-?hostname

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

get-?hostname_

(get-?hostname_)
Returns a new `(get-?hostname)` promise.

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)

log

macro

(log level & args)

log!

macro

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

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

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

log*

macro

(log* config level & args)

log-and-rethrow-errors

macro

(log-and-rethrow-errors & body)

log-env

macro

(log-env)(log-env level)(log-env level name)(log-env config level name)

log-errors

macro

(log-errors & body)

log?

logf

macro

(logf level & args)

logf*

macro

(logf* config level & args)

logged-future

macro

(logged-future & body)

logging-enabled?

(logging-enabled? level compile-time-ns)

logp

macro

(logp & sigs)

may-log?

(may-log? level)(may-log? level ?ns-str)(may-log? level ?ns-str ?config)
Runtime check: would Timbre currently log at the given logging level?
* `?ns-str` arg required to support ns filtering
* `config`  arg required to support non-global config

merge-config!

(merge-config! m)

ordered-levels

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], :or {fname "./timbre-spit.log"}}])
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)

str-println

(str-println & xs)

swap-config!

(swap-config! f & args)

trace

macro

(trace & args)

tracef

macro

(tracef & args)

valid-level

(valid-level x)

valid-level?

(valid-level? x)

warn

macro

(warn & args)

warnf

macro

(warnf & args)

with-config

macro

(with-config config & body)

with-context

macro

(with-context context & body)

with-default-outs

macro

(with-default-outs & body)

with-level

macro

(with-level level & body)

with-log-level

macro

(with-log-level level & body)

with-logging-config

macro

(with-logging-config config & body)

with-merged-config

macro

(with-merged-config config & body)